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.FunctionEvaluationException;
024    import org.apache.commons.math.analysis.DifferentiableMultivariateVectorialFunction;
025    import org.apache.commons.math.analysis.MultivariateMatrixFunction;
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: 927009 $ $Date: 2010-03-24 07:14:07 -0400 (Wed, 24 Mar 2010) $
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
122         * the search
123         * @exception OptimizationException if the algorithm failed to converge
124         * @exception IllegalArgumentException if the start point dimension is wrong
125         */
126        public double[] fit(final ParametricRealFunction f,
127                            final double[] initialGuess)
128            throws FunctionEvaluationException, OptimizationException, IllegalArgumentException {
129    
130            // prepare least squares problem
131            double[] target  = new double[observations.size()];
132            double[] weights = new double[observations.size()];
133            int i = 0;
134            for (WeightedObservedPoint point : observations) {
135                target[i]  = point.getY();
136                weights[i] = point.getWeight();
137                ++i;
138            }
139    
140            // perform the fit
141            VectorialPointValuePair optimum =
142                optimizer.optimize(new TheoreticalValuesFunction(f), target, weights, initialGuess);
143    
144            // extract the coefficients
145            return optimum.getPointRef();
146    
147        }
148    
149        /** Vectorial function computing function theoretical values. */
150        private class TheoreticalValuesFunction
151            implements DifferentiableMultivariateVectorialFunction {
152    
153            /** Function to fit. */
154            private final ParametricRealFunction f;
155    
156            /** Simple constructor.
157             * @param f function to fit.
158             */
159            public TheoreticalValuesFunction(final ParametricRealFunction f) {
160                this.f = f;
161            }
162    
163            /** {@inheritDoc} */
164            public MultivariateMatrixFunction jacobian() {
165                return new MultivariateMatrixFunction() {
166                    public double[][] value(double[] point)
167                        throws FunctionEvaluationException, IllegalArgumentException {
168    
169                        final double[][] jacobian = new double[observations.size()][];
170    
171                        int i = 0;
172                        for (WeightedObservedPoint observed : observations) {
173                            jacobian[i++] = f.gradient(observed.getX(), point);
174                        }
175    
176                        return jacobian;
177    
178                    }
179                };
180            }
181    
182            /** {@inheritDoc} */
183            public double[] value(double[] point)
184                    throws FunctionEvaluationException, IllegalArgumentException {
185    
186                // compute the residuals
187                final double[] values = new double[observations.size()];
188                int i = 0;
189                for (WeightedObservedPoint observed : observations) {
190                    values[i++] = f.value(observed.getX(), point);
191                }
192    
193                return values;
194    
195            }
196    
197        }
198    
199    }