001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    
018    package org.apache.commons.math.estimation;
019    
020    import java.io.Serializable;
021    
022    /** 
023     * This class represents measurements in estimation problems.
024     *
025     * <p>This abstract class implements all the methods needed to handle
026     * measurements in a general way. It defines neither the {@link
027     * #getTheoreticalValue getTheoreticalValue} nor the {@link
028     * #getPartial getPartial} methods, which should be defined by
029     * sub-classes according to the specific problem.</p>
030     *
031     * <p>The {@link #getTheoreticalValue getTheoreticalValue} and {@link
032     * #getPartial getPartial} methods must always use the current
033     * estimate of the parameters set by the solver in the problem. These
034     * parameters can be retrieved through the {@link
035     * EstimationProblem#getAllParameters
036     * EstimationProblem.getAllParameters} method if the measurements are
037     * independent of the problem, or directly if they are implemented as
038     * inner classes of the problem.</p>
039     *
040     * <p>The instances for which the <code>ignored</code> flag is set
041     * through the {@link #setIgnored setIgnored} method are ignored by the
042     * solvers. This can be used to reject wrong measurements at some
043     * steps of the estimation.</p>
044     *
045     * @see EstimationProblem
046     *
047     * @version $Revision: 754732 $ $Date: 2009-03-15 15:30:44 -0400 (Sun, 15 Mar 2009) $
048     * @since 1.2
049     * @deprecated as of 2.0, everything in package org.apache.commons.math.estimation has
050     * been deprecated and replaced by package org.apache.commons.math.optimization.general
051     */
052    
053    @Deprecated
054    public abstract class WeightedMeasurement implements Serializable {
055    
056        /** Serializable version identifier. */
057        private static final long serialVersionUID = 4360046376796901941L;
058    
059        /** 
060       * Simple constructor.
061       * Build a measurement with the given parameters, and set its ignore
062       * flag to false.
063       * @param weight weight of the measurement in the least squares problem
064       * (two common choices are either to use 1.0 for all measurements, or to
065       * use a value proportional to the inverse of the variance of the measurement
066       * type)
067       * 
068       * @param measuredValue measured value
069       */
070      public WeightedMeasurement(double weight, double measuredValue) {
071        this.weight        = weight;
072        this.measuredValue = measuredValue;
073        ignored            = false;
074      }
075    
076      /** Simple constructor.
077       * 
078       * Build a measurement with the given parameters
079       * 
080       * @param weight weight of the measurement in the least squares problem
081       * @param measuredValue measured value
082       * @param ignored true if the measurement should be ignored
083       */
084      public WeightedMeasurement(double weight, double measuredValue,
085                                 boolean ignored) {
086        this.weight        = weight;
087        this.measuredValue = measuredValue;
088        this.ignored       = ignored;
089      }
090    
091      /** 
092       * Get the weight of the measurement in the least squares problem
093       * 
094       * @return weight
095       */
096      public double getWeight() {
097        return weight;
098      }
099    
100      /** 
101       * Get the measured value
102       * 
103       * @return measured value
104       */
105      public double getMeasuredValue() {
106        return measuredValue;
107      }
108    
109      /** 
110       * Get the residual for this measurement
111       * The residual is the measured value minus the theoretical value.
112       * 
113       * @return residual
114       */
115      public double getResidual() {
116        return measuredValue - getTheoreticalValue();
117      }
118    
119      /** 
120       * Get the theoretical value expected for this measurement
121       * <p>The theoretical value is the value expected for this measurement
122       * if the model and its parameter were all perfectly known.</p>
123       * <p>The value must be computed using the current estimate of the parameters
124       * set by the solver in the problem.</p>
125       * 
126       * @return theoretical value
127       */
128      public abstract double getTheoreticalValue();
129    
130      /** 
131       * Get the partial derivative of the {@link #getTheoreticalValue
132       * theoretical value} according to the parameter.
133       * <p>The value must be computed using the current estimate of the parameters
134       * set by the solver in the problem.</p>
135       * 
136       * @param parameter parameter against which the partial derivative
137       * should be computed
138       * @return partial derivative of the {@link #getTheoreticalValue
139       * theoretical value}
140       */
141      public abstract double getPartial(EstimatedParameter parameter);
142    
143      /** 
144       * Set the ignore flag to the specified value
145       * Setting the ignore flag to true allow to reject wrong
146       * measurements, which sometimes can be detected only rather late.
147       * 
148       * @param ignored value for the ignore flag
149       */
150      public void setIgnored(boolean ignored) {
151        this.ignored = ignored;
152      }
153    
154      /** 
155       * Check if this measurement should be ignored
156       * 
157       * @return true if the measurement should be ignored
158       */
159      public boolean isIgnored() {
160        return ignored;
161      }
162    
163      /** Measurement weight. */
164      private final double  weight;
165    
166      /** Value of the measurements. */
167      private final double  measuredValue;
168    
169      /** Ignore measurement indicator. */
170      private       boolean ignored;
171    
172    }