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 }