Apache
/
commons-math
mirror of https://github.com/apache/commons-math.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Userguide update. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1606503 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Gilles Sadowski 2014-06-29 13:48:19 +00:00
parent 25e774c315
commit 41b4ca622c
1 changed files with 80 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

137
src/site/xdoc/userguide/fitting.xml
View File

@ -40,80 +40,103 @@
least-squares problem.
</p>
<p>
For all provided curve fitters, the operating principle is the same. Users must first
create an instance of the fitter, then add the observed points and once the complete
sample of observed points has been added they must call the <code>fit</code> method
which will compute the parameters that best fit the sample. A weight is associated
with each observed point, this allows to take into account uncertainty on some points
when they come from loosy 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.
</p>
</subsection>
<subsection name="17.2 General Case" href="general">
<p>
The <a href="../apidocs/org/apache/commons/math3/fitting/CurveFitter.html">
CurveFitter</a> class provides curve fitting for general curves. Users must
provide their own implementation of the curve template as a class implementing
the <a href="../apidocs/org/apache/commons/math3/analysis/ParametricUnivariateFunction.html">
ParametricUnivariateFunction</a> interface and they must provide the initial guess of the
parameters.
</p>
<p>
The following example shows how to fit data with a polynomial function.
</p>
<source>final CurveFitter fitter = new CurveFitter(new LevenbergMarquardtOptimizer());
fitter.addObservedPoint(-1.00, 2.021170021833143);
fitter.addObservedPoint(-0.99, 2.221135431136975);
fitter.addObservedPoint(-0.98, 2.09985277659314);
fitter.addObservedPoint(-0.97, 2.0211192647627025);
// ... Lots of lines omitted ...
fitter.addObservedPoint( 0.99, -2.4345814727089854);
// The degree of the polynomial is deduced from the length of the array containing
// the initial guess for the coefficients of the polynomial.
final double[] init = { 12.9, -3.4, 2.1 }; // 12.9 - 3.4 x + 2.1 x^2
// Compute optimal coefficients.
final double[] best = fitter.fit(new PolynomialFunction.Parametric(), init);
// Construct the polynomial that best fits the data.
final PolynomialFunction fitted = new PolynomialFunction(best);
</source>
</subsection>
<subsection name="17.3 Special Cases" href="special">
<p>
There are more specialized classes, for which the appropriate parametric
function is implicitly used:
For all provided curve fitters, the operating principle is the same.
Users must
<ul>
<li>
<a href="../apidocs/org/apache/commons/math3/fitting/PolynomialFitter.html">
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/math3/fitting/AbstractCurveFitter">fit</a>
with a <code>Collection</code> of <a href="../apidocs/org/apache/commons/math3/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/math3/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="17.2 Implemented Functions" href="special">
<p>
Fitting of specific functions are provided through the following classes:
<ul>
<li>
<a href="../apidocs/org/apache/commons/math3/fitting/PolynomialCurveFitter.html">
PolynomialFitter</a> fits a
<a href="../apidocs/org/apache/commons/math3/analysis/polynomials/PolynomialFunction.Parametric.html">
polynomial</a> function
polynomial</a> function.
</li>
<li>
<a href="../apidocs/org/apache/commons/math3/fitting/HarmonicFitter.html">
<a href="../apidocs/org/apache/commons/math3/fitting/HarmonicCurveFitter.html">
HarmonicFitter</a> fits a
<a href="../apidocs/org/apache/commons/math3/analysis/function/HarmonicOscillator.Parametric.html">
harmonic</a> function
harmonic</a> function.
An instance of the inner class <a href="../apidocs/org/apache/commons/math3/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/math3/fitting/GaussianFitter.html">
<a href="../apidocs/org/apache/commons/math3/fitting/GaussianCurveFitter.html">
GaussianFitter</a> fits a
<a href="../apidocs/org/apache/commons/math3/analysis/function/Gaussian.Parametric.html">
Gaussian</a> function
Gaussian</a> function.
An instance of the inner class <a href="../apidocs/org/apache/commons/math3/fitting/GaussianCurveFitter.ParameterGuesser.html">
ParameterGuesser</a> can be used to retrieve initial values for the fitting procedure.
</li>
</ul>
</p>
<p>
The <code>HarmonicFitter</code> and <code>GaussianFitter</code> also provide a
no-argument <code>fit()</code> method that will internally estimate initial
guess values for the parameters.
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="17.3 General Case" href="general">
<p>
The <a href="../apidocs/org/apache/commons/math3/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/math3/analysis/ParametricUnivariateFunction.html">
ParametricUnivariateFunction</a> interface.
</p>
</subsection>