    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    }