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 }