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 }