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
18package org.apache.commons.math.estimation;
19
20import 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: 811827 $ $Date: 2009-09-06 17:32:50 +0200 (dim. 06 sept. 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
54public abstract class WeightedMeasurement implements Serializable {
55
56    /** Serializable version identifier. */
57    private static final long serialVersionUID = 4360046376796901941L;
58
59    /** Measurement weight. */
60    private final double  weight;
61
62    /** Value of the measurements. */
63    private final double  measuredValue;
64
65    /** Ignore measurement indicator. */
66    private boolean ignored;
67
68  /**
69   * Simple constructor.
70   * Build a measurement with the given parameters, and set its ignore
71   * flag to false.
72   * @param weight weight of the measurement in the least squares problem
73   * (two common choices are either to use 1.0 for all measurements, or to
74   * use a value proportional to the inverse of the variance of the measurement
75   * type)
76   *
77   * @param measuredValue measured value
78   */
79  public WeightedMeasurement(double weight, double measuredValue) {
80    this.weight        = weight;
81    this.measuredValue = measuredValue;
82    ignored            = false;
83  }
84
85  /** Simple constructor.
86   *
87   * Build a measurement with the given parameters
88   *
89   * @param weight weight of the measurement in the least squares problem
90   * @param measuredValue measured value
91   * @param ignored true if the measurement should be ignored
92   */
93  public WeightedMeasurement(double weight, double measuredValue,
94                             boolean ignored) {
95    this.weight        = weight;
96    this.measuredValue = measuredValue;
97    this.ignored       = ignored;
98  }
99
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}
173