    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.optimization.fitting;
    019
    020    import java.util.ArrayList;
    021    import java.util.List;
    022
    023    import org.apache.commons.math.analysis.DifferentiableMultivariateVectorialFunction;
    024    import org.apache.commons.math.analysis.MultivariateMatrixFunction;
    025    import org.apache.commons.math.FunctionEvaluationException;
    026    import org.apache.commons.math.optimization.DifferentiableMultivariateVectorialOptimizer;
    027    import org.apache.commons.math.optimization.OptimizationException;
    028    import org.apache.commons.math.optimization.VectorialPointValuePair;
    029
    030    /** Fitter for parametric univariate real functions y = f(x).
    031     * <p>When a univariate real function y = f(x) does depend on some
    032     * unknown parameters p<sub>0</sub>, p<sub>1</sub> ... p<sub>n-1</sub>,
    033     * this class can be used to find these parameters. It does this
    034     * by <em>fitting</em> the curve so it remains very close to a set of
    035     * observed points (x<sub>0</sub>, y<sub>0</sub>), (x<sub>1</sub>,
    036     * y<sub>1</sub>) ... (x<sub>k-1</sub>, y<sub>k-1</sub>). This fitting
    037     * is done by finding the parameters values that minimizes the objective
    038     * function &sum;(y<sub>i</sub>-f(x<sub>i</sub>))<sup>2</sup>. This is
    039     * really a least squares problem.</p>
    040     * @version $Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 f??vr. 2011) $
    041     * @since 2.0
    042     */
    043    public class CurveFitter {
    044
    045        /** Optimizer to use for the fitting. */
    046        private final DifferentiableMultivariateVectorialOptimizer optimizer;
    047
    048        /** Observed points. */
    049        private final List<WeightedObservedPoint> observations;
    050
    051        /** Simple constructor.
    052         * @param optimizer optimizer to use for the fitting
    053         */
    054        public CurveFitter(final DifferentiableMultivariateVectorialOptimizer optimizer) {
    055            this.optimizer = optimizer;
    056            observations = new ArrayList<WeightedObservedPoint>();
    057        }
    058
    059        /** Add an observed (x,y) point to the sample with unit weight.
    060         * <p>Calling this method is equivalent to call
    061         * <code>addObservedPoint(1.0, x, y)</code>.</p>
    062         * @param x abscissa of the point
    063         * @param y observed value of the point at x, after fitting we should
    064         * have f(x) as close as possible to this value
    065         * @see #addObservedPoint(double, double, double)
    066         * @see #addObservedPoint(WeightedObservedPoint)
    067         * @see #getObservations()
    068         */
    069        public void addObservedPoint(double x, double y) {
    070            addObservedPoint(1.0, x, y);
    071        }
    072
    073        /** Add an observed weighted (x,y) point to the sample.
    074         * @param weight weight of the observed point in the fit
    075         * @param x abscissa of the point
    076         * @param y observed value of the point at x, after fitting we should
    077         * have f(x) as close as possible to this value
    078         * @see #addObservedPoint(double, double)
    079         * @see #addObservedPoint(WeightedObservedPoint)
    080         * @see #getObservations()
    081         */
    082        public void addObservedPoint(double weight, double x, double y) {
    083            observations.add(new WeightedObservedPoint(weight, x, y));
    084        }
    085
    086        /** Add an observed weighted (x,y) point to the sample.
    087         * @param observed observed point to add
    088         * @see #addObservedPoint(double, double)
    089         * @see #addObservedPoint(double, double, double)
    090         * @see #getObservations()
    091         */
    092        public void addObservedPoint(WeightedObservedPoint observed) {
    093            observations.add(observed);
    094        }
    095
    096        /** Get the observed points.
    097         * @return observed points
    098         * @see #addObservedPoint(double, double)
    099         * @see #addObservedPoint(double, double, double)
    100         * @see #addObservedPoint(WeightedObservedPoint)
    101         */
    102        public WeightedObservedPoint[] getObservations() {
    103            return observations.toArray(new WeightedObservedPoint[observations.size()]);
    104        }
    105
    106        /**
    107         * Remove all observations.
    108         */
    109        public void clearObservations() {
    110            observations.clear();
    111        }
    112
    113        /** Fit a curve.
    114         * <p>This method compute the coefficients of the curve that best
    115         * fit the sample of observed points previously given through calls
    116         * to the {@link #addObservedPoint(WeightedObservedPoint)
    117         * addObservedPoint} method.</p>
    118         * @param f parametric function to fit
    119         * @param initialGuess first guess of the function parameters
    120         * @return fitted parameters
    121         * @exception FunctionEvaluationException if the objective function throws one during the search
    122         * @exception OptimizationException if the algorithm failed to converge
    123         * @exception IllegalArgumentException if the start point dimension is wrong
    124         */
    125        public double[] fit(final ParametricRealFunction f,
    126                            final double[] initialGuess)
    127            throws FunctionEvaluationException, OptimizationException, IllegalArgumentException {
    128
    129            // prepare least squares problem
    130            double[] target  = new double[observations.size()];
    131            double[] weights = new double[observations.size()];
    132            int i = 0;
    133            for (WeightedObservedPoint point : observations) {
    134                target[i]  = point.getY();
    135                weights[i] = point.getWeight();
    136                ++i;
    137            }
    138
    139            // perform the fit
    140            VectorialPointValuePair optimum =
    141                optimizer.optimize(new TheoreticalValuesFunction(f), target, weights, initialGuess);
    142
    143            // extract the coefficients
    144            return optimum.getPointRef();
    145
    146        }
    147
    148        /** Vectorial function computing function theoretical values. */
    149        private class TheoreticalValuesFunction
    150            implements DifferentiableMultivariateVectorialFunction {
    151
    152            /** Function to fit. */
    153            private final ParametricRealFunction f;
    154
    155            /** Simple constructor.
    156             * @param f function to fit.
    157             */
    158            public TheoreticalValuesFunction(final ParametricRealFunction f) {
    159                this.f = f;
    160            }
    161
    162            /** {@inheritDoc} */
    163            public MultivariateMatrixFunction jacobian() {
    164                return new MultivariateMatrixFunction() {
    165                    public double[][] value(double[] point)
    166                        throws FunctionEvaluationException, IllegalArgumentException {
    167
    168                        final double[][] jacobian = new double[observations.size()][];
    169
    170                        int i = 0;
    171                        for (WeightedObservedPoint observed : observations) {
    172                            jacobian[i++] = f.gradient(observed.getX(), point);
    173                        }
    174
    175                        return jacobian;
    176
    177                    }
    178                };
    179            }
    180
    181            /** {@inheritDoc} */
    182            public double[] value(double[] point) throws FunctionEvaluationException, IllegalArgumentException {
    183
    184                // compute the residuals
    185                final double[] values = new double[observations.size()];
    186                int i = 0;
    187                for (WeightedObservedPoint observed : observations) {
    188                    values[i++] = f.value(observed.getX(), point);
    189                }
    190
    191                return values;
    192
    193            }
    194
    195        }
    196
    197    }