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.optimization.fitting;
19
20 import java.util.ArrayList;
21 import java.util.List;
22
23 import org.apache.commons.math.FunctionEvaluationException;
24 import org.apache.commons.math.analysis.DifferentiableMultivariateVectorialFunction;
25 import org.apache.commons.math.analysis.MultivariateMatrixFunction;
26 import org.apache.commons.math.optimization.DifferentiableMultivariateVectorialOptimizer;
27 import org.apache.commons.math.optimization.OptimizationException;
28 import org.apache.commons.math.optimization.VectorialPointValuePair;
29
30 /** Fitter for parametric univariate real functions y = f(x).
31 * <p>When a univariate real function y = f(x) does depend on some
32 * unknown parameters p<sub>0</sub>, p<sub>1</sub> ... p<sub>n-1</sub>,
33 * this class can be used to find these parameters. It does this
34 * by <em>fitting</em> the curve so it remains very close to a set of
35 * observed points (x<sub>0</sub>, y<sub>0</sub>), (x<sub>1</sub>,
36 * y<sub>1</sub>) ... (x<sub>k-1</sub>, y<sub>k-1</sub>). This fitting
37 * is done by finding the parameters values that minimizes the objective
38 * function ∑(y<sub>i</sub>-f(x<sub>i</sub>))<sup>2</sup>. This is
39 * really a least squares problem.</p>
40 * @version $Revision: 790380 $ $Date: 2009-07-01 17:03:38 -0400 (Wed, 01 Jul 2009) $
41 * @since 2.0
42 */
43 public class CurveFitter {
44
45 /** Optimizer to use for the fitting. */
46 private final DifferentiableMultivariateVectorialOptimizer optimizer;
47
48 /** Observed points. */
49 private final List<WeightedObservedPoint> observations;
50
51 /** Simple constructor.
52 * @param optimizer optimizer to use for the fitting
53 */
54 public CurveFitter(final DifferentiableMultivariateVectorialOptimizer optimizer) {
55 this.optimizer = optimizer;
56 observations = new ArrayList<WeightedObservedPoint>();
57 }
58
59 /** Add an observed (x,y) point to the sample with unit weight.
60 * <p>Calling this method is equivalent to call
61 * <code>addObservedPoint(1.0, x, y)</code>.</p>
62 * @param x abscissa of the point
63 * @param y observed value of the point at x, after fitting we should
64 * have f(x) as close as possible to this value
65 * @see #addObservedPoint(double, double, double)
66 * @see #addObservedPoint(WeightedObservedPoint)
67 * @see #getObservations()
68 */
69 public void addObservedPoint(double x, double y) {
70 addObservedPoint(1.0, x, y);
71 }
72
73 /** Add an observed weighted (x,y) point to the sample.
74 * @param weight weight of the observed point in the fit
75 * @param x abscissa of the point
76 * @param y observed value of the point at x, after fitting we should
77 * have f(x) as close as possible to this value
78 * @see #addObservedPoint(double, double)
79 * @see #addObservedPoint(WeightedObservedPoint)
80 * @see #getObservations()
81 */
82 public void addObservedPoint(double weight, double x, double y) {
83 observations.add(new WeightedObservedPoint(weight, x, y));
84 }
85
86 /** Add an observed weighted (x,y) point to the sample.
87 * @param observed observed point to add
88 * @see #addObservedPoint(double, double)
89 * @see #addObservedPoint(double, double, double)
90 * @see #getObservations()
91 */
92 public void addObservedPoint(WeightedObservedPoint observed) {
93 observations.add(observed);
94 }
95
96 /** Get the observed points.
97 * @return observed points
98 * @see #addObservedPoint(double, double)
99 * @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 /** Fit a curve.
107 * <p>This method compute the coefficients of the curve that best
108 * fit the sample of observed points previously given through calls
109 * to the {@link #addObservedPoint(WeightedObservedPoint)
110 * addObservedPoint} method.</p>
111 * @param f parametric function to fit
112 * @param initialGuess first guess of the function parameters
113 * @return fitted parameters
114 * @exception FunctionEvaluationException if the objective function throws one during
115 * the search
116 * @exception OptimizationException if the algorithm failed to converge
117 * @exception IllegalArgumentException if the start point dimension is wrong
118 */
119 public double[] fit(final ParametricRealFunction f,
120 final double[] initialGuess)
121 throws FunctionEvaluationException, OptimizationException, IllegalArgumentException {
122
123 // prepare least squares problem
124 double[] target = new double[observations.size()];
125 double[] weights = new double[observations.size()];
126 int i = 0;
127 for (WeightedObservedPoint point : observations) {
128 target[i] = point.getY();
129 weights[i] = point.getWeight();
130 ++i;
131 }
132
133 // perform the fit
134 VectorialPointValuePair optimum =
135 optimizer.optimize(new TheoreticalValuesFunction(f), target, weights, initialGuess);
136
137 // extract the coefficients
138 return optimum.getPointRef();
139
140 }
141
142 /** Vectorial function computing function theoretical values. */
143 private class TheoreticalValuesFunction
144 implements DifferentiableMultivariateVectorialFunction {
145
146 /** Function to fit. */
147 private final ParametricRealFunction f;
148
149 /** Simple constructor.
150 * @param f function to fit.
151 */
152 public TheoreticalValuesFunction(final ParametricRealFunction f) {
153 this.f = f;
154 }
155
156 /** {@inheritDoc} */
157 public MultivariateMatrixFunction jacobian() {
158 return new MultivariateMatrixFunction() {
159 public double[][] value(double[] point)
160 throws FunctionEvaluationException, IllegalArgumentException {
161
162 final double[][] jacobian = new double[observations.size()][];
163
164 int i = 0;
165 for (WeightedObservedPoint observed : observations) {
166 jacobian[i++] = f.gradient(observed.getX(), point);
167 }
168
169 return jacobian;
170
171 }
172 };
173 }
174
175 /** {@inheritDoc} */
176 public double[] value(double[] point)
177 throws FunctionEvaluationException, IllegalArgumentException {
178
179 // compute the residuals
180 final double[] values = new double[observations.size()];
181 int i = 0;
182 for (WeightedObservedPoint observed : observations) {
183 values[i++] = f.value(observed.getX(), point);
184 }
185
186 return values;
187
188 }
189
190 }
191
192 }