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: 620312 $ $Date: 2008-02-10 12:28:59 -0700 (Sun, 10 Feb 2008) $
48 * @since 1.2
49 *
50 */
51
52 public abstract class WeightedMeasurement implements Serializable {
53
54 /**
55 * Simple constructor.
56 * Build a measurement with the given parameters, and set its ignore
57 * flag to false.
58 * @param weight weight of the measurement in the least squares problem
59 * (two common choices are either to use 1.0 for all measurements, or to
60 * use a value proportional to the inverse of the variance of the measurement
61 * type)
62 *
63 * @param measuredValue measured value
64 */
65 public WeightedMeasurement(double weight, double measuredValue) {
66 this.weight = weight;
67 this.measuredValue = measuredValue;
68 ignored = false;
69 }
70
71 /** Simple constructor.
72 *
73 * Build a measurement with the given parameters
74 *
75 * @param weight weight of the measurement in the least squares problem
76 * @param measuredValue measured value
77 * @param ignored true if the measurement should be ignored
78 */
79 public WeightedMeasurement(double weight, double measuredValue,
80 boolean ignored) {
81 this.weight = weight;
82 this.measuredValue = measuredValue;
83 this.ignored = ignored;
84 }
85
86 /**
87 * Get the weight of the measurement in the least squares problem
88 *
89 * @return weight
90 */
91 public double getWeight() {
92 return weight;
93 }
94
95 /**
96 * Get the measured value
97 *
98 * @return measured value
99 */
100 public double getMeasuredValue() {
101 return measuredValue;
102 }
103
104 /**
105 * Get the residual for this measurement
106 * The residual is the measured value minus the theoretical value.
107 *
108 * @return residual
109 */
110 public double getResidual() {
111 return measuredValue - getTheoreticalValue();
112 }
113
114 /**
115 * Get the theoretical value expected for this measurement
116 * <p>The theoretical value is the value expected for this measurement
117 * if the model and its parameter were all perfectly known.</p>
118 * <p>The value must be computed using the current estimate of the parameters
119 * set by the solver in the problem.</p>
120 *
121 * @return theoretical value
122 */
123 public abstract double getTheoreticalValue();
124
125 /**
126 * Get the partial derivative of the {@link #getTheoreticalValue
127 * theoretical value} according to the parameter.
128 * <p>The value must be computed using the current estimate of the parameters
129 * set by the solver in the problem.</p>
130 *
131 * @param parameter parameter against which the partial derivative
132 * should be computed
133 * @return partial derivative of the {@link #getTheoreticalValue
134 * theoretical value}
135 */
136 public abstract double getPartial(EstimatedParameter parameter);
137
138 /**
139 * Set the ignore flag to the specified value
140 * Setting the ignore flag to true allow to reject wrong
141 * measurements, which sometimes can be detected only rather late.
142 *
143 * @param ignored value for the ignore flag
144 */
145 public void setIgnored(boolean ignored) {
146 this.ignored = ignored;
147 }
148
149 /**
150 * Check if this measurement should be ignored
151 *
152 * @return true if the measurement should be ignored
153 */
154 public boolean isIgnored() {
155 return ignored;
156 }
157
158 /** Measurement weight. */
159 private final double weight;
160
161 /** Value of the measurements. */
162 private final double measuredValue;
163
164 /** Ignore measurement indicator. */
165 private boolean ignored;
166
167 }