| <?xml version="1.0"?> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <document url="fitting.html"> |
| |
| <properties> |
| <title>The Commons Math User Guide - Curve Fitting</title> |
| </properties> |
| |
| <body> |
| <section name="13 Curve Fitting"> |
| <subsection name="13.1 Overview" href="overview"> |
| <p> |
| The fitting package deals with curve fitting for univariate real functions. |
| When a univariate real function y = f(x) does depend on some unknown parameters |
| p<sub>0</sub>, p<sub>1</sub> ... p<sub>n-1</sub>, curve fitting can be used to |
| find these parameters. It does this by <em>fitting</em> the curve so it remains |
| very close to a set of observed points (x<sub>0</sub>, y<sub>0</sub>), |
| (x<sub>1</sub>, y<sub>1</sub>) ... (x<sub>k-1</sub>, y<sub>k-1</sub>). This |
| fitting is done by finding the parameters values that minimizes the objective |
| function Σ(y<sub>i</sub> - f(x<sub>i</sub>))<sup>2</sup>. This is actually a |
| least-squares problem. |
| </p> |
| <p> |
| For all provided curve fitters, the operating principle is the same. |
| Users must |
| <ul> |
| <li> |
| create an instance of the fitter using the <code>create</code> factory method of the |
| appropriate class, |
| </li> |
| <li> |
| call the <a href="../apidocs/org/apache/commons/math4/fitting/AbstractCurveFitter">fit</a> |
| with a <code>Collection</code> of <a href="../apidocs/org/apache/commons/math4/fitting/WeightedObservedPoint.html"> |
| observed data points</a> as argument, which will return an array with the parameters that |
| best fit the given data points. |
| </li> |
| </ul> |
| |
| The list of observed data points to be passed to <code>fit</code> can be built by incrementally |
| adding instances to an instance of <a href="../apidocs/org/apache/commons/math4/fitting/WeightedObservedPoints.html">WeightedObservedPoints</a>, |
| and then retrieve the list of <code>WeightedObservedPoint</code> by calling the <code>toList</code> |
| method on that container. |
| A weight can be associated with each observed point; it allows to take into account uncertainty |
| on some points when they come from noisy measurements for example. If no such information exist and |
| all points should be treated the same, it is safe to put 1.0 as the weight for all points (and this |
| is the default when no weight is passed to the <code>add</code>. |
| </p> |
| |
| <p> |
| Some fitters require that initial values for the parameters are provided by the user, |
| through the <code>withStartPoint</code> method, before attempting to perform the fit. |
| When that's the case the fitter class usually defines a guessing procedure within a |
| <code>ParameterGuesser</code> inner class, that attempts to provide appropriate initial |
| values based on the user-supplied data. |
| When initial values are required but are not provided, the <code>fit</code> method will |
| internally call the guessing procedure. |
| </p> |
| |
| </subsection> |
| |
| <subsection name="13.2 Implemented Functions" href="special"> |
| |
| <p> |
| Fitting of specific functions are provided through the following classes: |
| <ul> |
| <li> |
| <a href="../apidocs/org/apache/commons/math4/fitting/PolynomialCurveFitter.html"> |
| PolynomialFitter</a> fits a |
| <a href="../apidocs/org/apache/commons/math4/analysis/polynomials/PolynomialFunction.Parametric.html"> |
| polynomial</a> function. |
| </li> |
| <li> |
| <a href="../apidocs/org/apache/commons/math4/fitting/HarmonicCurveFitter.html"> |
| HarmonicFitter</a> fits a |
| <a href="../apidocs/org/apache/commons/math4/analysis/function/HarmonicOscillator.Parametric.html"> |
| harmonic</a> function. |
| An instance of the inner class <a href="../apidocs/org/apache/commons/math4/fitting/HarmonicCurveFitter.ParameterGuesser.html"> |
| ParameterGuesser</a> can be used to retrieve initial values for the fitting procedure. |
| </li> |
| <li> |
| <a href="../apidocs/org/apache/commons/math4/fitting/GaussianCurveFitter.html"> |
| GaussianFitter</a> fits a |
| <a href="../apidocs/org/apache/commons/math4/analysis/function/Gaussian.Parametric.html"> |
| Gaussian</a> function. |
| An instance of the inner class <a href="../apidocs/org/apache/commons/math4/fitting/GaussianCurveFitter.ParameterGuesser.html"> |
| ParameterGuesser</a> can be used to retrieve initial values for the fitting procedure. |
| </li> |
| </ul> |
| </p> |
| |
| <p> |
| The following example shows how to fit data with a polynomial function. |
| </p> |
| |
| <source>// Collect data. |
| final WeightedObservedPoints obs = new WeightedObservedPoints(); |
| obs.add(-1.00, 2.021170021833143); |
| obs.add(-0.99, 2.221135431136975); |
| obs.add(-0.98, 2.09985277659314); |
| obs.add(-0.97, 2.0211192647627025); |
| // ... Lots of lines omitted ... |
| obs.addt(0.99, -2.4345814727089854); |
| |
| // Instantiate a third-degree polynomial fitter. |
| final PolynomialCurveFitter fitter = PolynomialCurveFitter.create(3); |
| |
| // Retrieve fitted parameters (coefficients of the polynomial function). |
| final double[] coeff = fitter.fit(obs.toList()); |
| </source> |
| |
| </subsection> |
| |
| <subsection name="13.3 General Case" href="general"> |
| <p> |
| The <a href="../apidocs/org/apache/commons/math4/fitting/AbstractCurveFitter.html"> |
| AbstractCurveFitter</a> class provides the basic functionality for implementing other |
| curve fitting classes. |
| Users must provide their own implementation of the curve template as a class that implements |
| the <a href="../apidocs/org/apache/commons/math4/analysis/ParametricUnivariateFunction.html"> |
| ParametricUnivariateFunction</a> interface. |
| </p> |
| </subsection> |
| |
| </section> |
| </body> |
| </document> |