You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by er...@apache.org on 2014/06/29 15:48:20 UTC
svn commit: r1606503 -
/commons/proper/math/trunk/src/site/xdoc/userguide/fitting.xml
Author: erans
Date: Sun Jun 29 13:48:19 2014
New Revision: 1606503
URL: http://svn.apache.org/r1606503
Log:
Userguide update.
Modified:
commons/proper/math/trunk/src/site/xdoc/userguide/fitting.xml
Modified: commons/proper/math/trunk/src/site/xdoc/userguide/fitting.xml
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/userguide/fitting.xml?rev=1606503&r1=1606502&r2=1606503&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/fitting.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/fitting.xml Sun Jun 29 13:48:19 2014
@@ -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>
+ 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/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>
- <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.
+ 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>
- The following example shows how to fit data with a polynomial function.
+ 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>
- <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">
+ <subsection name="17.2 Implemented Functions" href="special">
<p>
- There are more specialized classes, for which the appropriate parametric
- function is implicitly used:
+ Fitting of specific functions are provided through the following classes:
<ul>
<li>
- <a href="../apidocs/org/apache/commons/math3/fitting/PolynomialFitter.html">
+ <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>