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: 811827 $ $Date: 2009-09-06 17:32:50 +0200 (dim. 06 sept. 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 /** Measurement weight. */
060 private final double weight;
061
062 /** Value of the measurements. */
063 private final double measuredValue;
064
065 /** Ignore measurement indicator. */
066 private boolean ignored;
067
068 /**
069 * Simple constructor.
070 * Build a measurement with the given parameters, and set its ignore
071 * flag to false.
072 * @param weight weight of the measurement in the least squares problem
073 * (two common choices are either to use 1.0 for all measurements, or to
074 * use a value proportional to the inverse of the variance of the measurement
075 * type)
076 *
077 * @param measuredValue measured value
078 */
079 public WeightedMeasurement(double weight, double measuredValue) {
080 this.weight = weight;
081 this.measuredValue = measuredValue;
082 ignored = false;
083 }
084
085 /** Simple constructor.
086 *
087 * Build a measurement with the given parameters
088 *
089 * @param weight weight of the measurement in the least squares problem
090 * @param measuredValue measured value
091 * @param ignored true if the measurement should be ignored
092 */
093 public WeightedMeasurement(double weight, double measuredValue,
094 boolean ignored) {
095 this.weight = weight;
096 this.measuredValue = measuredValue;
097 this.ignored = ignored;
098 }
099
100 /**
101 * Get the weight of the measurement in the least squares problem
102 *
103 * @return weight
104 */
105 public double getWeight() {
106 return weight;
107 }
108
109 /**
110 * Get the measured value
111 *
112 * @return measured value
113 */
114 public double getMeasuredValue() {
115 return measuredValue;
116 }
117
118 /**
119 * Get the residual for this measurement
120 * The residual is the measured value minus the theoretical value.
121 *
122 * @return residual
123 */
124 public double getResidual() {
125 return measuredValue - getTheoreticalValue();
126 }
127
128 /**
129 * Get the theoretical value expected for this measurement
130 * <p>The theoretical value is the value expected for this measurement
131 * if the model and its parameter were all perfectly known.</p>
132 * <p>The value must be computed using the current estimate of the parameters
133 * set by the solver in the problem.</p>
134 *
135 * @return theoretical value
136 */
137 public abstract double getTheoreticalValue();
138
139 /**
140 * Get the partial derivative of the {@link #getTheoreticalValue
141 * theoretical value} according to the parameter.
142 * <p>The value must be computed using the current estimate of the parameters
143 * set by the solver in the problem.</p>
144 *
145 * @param parameter parameter against which the partial derivative
146 * should be computed
147 * @return partial derivative of the {@link #getTheoreticalValue
148 * theoretical value}
149 */
150 public abstract double getPartial(EstimatedParameter parameter);
151
152 /**
153 * Set the ignore flag to the specified value
154 * Setting the ignore flag to true allow to reject wrong
155 * measurements, which sometimes can be detected only rather late.
156 *
157 * @param ignored value for the ignore flag
158 */
159 public void setIgnored(boolean ignored) {
160 this.ignored = ignored;
161 }
162
163 /**
164 * Check if this measurement should be ignored
165 *
166 * @return true if the measurement should be ignored
167 */
168 public boolean isIgnored() {
169 return ignored;
170 }
171
172 }