View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.math.estimation;
19  
20  import java.io.Serializable;
21  
22  /** 
23   * This class represents measurements in estimation problems.
24   *
25   * <p>This abstract class implements all the methods needed to handle
26   * measurements in a general way. It defines neither the {@link
27   * #getTheoreticalValue getTheoreticalValue} nor the {@link
28   * #getPartial getPartial} methods, which should be defined by
29   * sub-classes according to the specific problem.</p>
30   *
31   * <p>The {@link #getTheoreticalValue getTheoreticalValue} and {@link
32   * #getPartial getPartial} methods must always use the current
33   * estimate of the parameters set by the solver in the problem. These
34   * parameters can be retrieved through the {@link
35   * EstimationProblem#getAllParameters
36   * EstimationProblem.getAllParameters} method if the measurements are
37   * independent of the problem, or directly if they are implemented as
38   * inner classes of the problem.</p>
39   *
40   * <p>The instances for which the <code>ignored</code> flag is set
41   * through the {@link #setIgnored setIgnored} method are ignored by the
42   * solvers. This can be used to reject wrong measurements at some
43   * steps of the estimation.</p>
44   *
45   * @see EstimationProblem
46   *
47   * @version $Revision: 754732 $ $Date: 2009-03-15 15:30:44 -0400 (Sun, 15 Mar 2009) $
48   * @since 1.2
49   * @deprecated as of 2.0, everything in package org.apache.commons.math.estimation has
50   * been deprecated and replaced by package org.apache.commons.math.optimization.general
51   */
52  
53  @Deprecated
54  public abstract class WeightedMeasurement implements Serializable {
55  
56      /** Serializable version identifier. */
57      private static final long serialVersionUID = 4360046376796901941L;
58  
59      /** 
60     * Simple constructor.
61     * Build a measurement with the given parameters, and set its ignore
62     * flag to false.
63     * @param weight weight of the measurement in the least squares problem
64     * (two common choices are either to use 1.0 for all measurements, or to
65     * use a value proportional to the inverse of the variance of the measurement
66     * type)
67     * 
68     * @param measuredValue measured value
69     */
70    public WeightedMeasurement(double weight, double measuredValue) {
71      this.weight        = weight;
72      this.measuredValue = measuredValue;
73      ignored            = false;
74    }
75  
76    /** Simple constructor.
77     * 
78     * Build a measurement with the given parameters
79     * 
80     * @param weight weight of the measurement in the least squares problem
81     * @param measuredValue measured value
82     * @param ignored true if the measurement should be ignored
83     */
84    public WeightedMeasurement(double weight, double measuredValue,
85                               boolean ignored) {
86      this.weight        = weight;
87      this.measuredValue = measuredValue;
88      this.ignored       = ignored;
89    }
90  
91    /** 
92     * Get the weight of the measurement in the least squares problem
93     * 
94     * @return weight
95     */
96    public double getWeight() {
97      return weight;
98    }
99  
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 }