Author: erans
Date: Wed Apr 17 22:30:46 2013
New Revision: 1469085
URL: http://svn.apache.org/r1469085
Log:
MATH-874
First steps in updating the "optimization" section of the userguide.
Moved "fitting" to its own section.
Added:
commons/proper/math/trunk/src/site/xdoc/userguide/fitting.xml (with props)
Modified:
commons/proper/math/trunk/src/site/site.xml
commons/proper/math/trunk/src/site/xdoc/userguide/index.xml
commons/proper/math/trunk/src/site/xdoc/userguide/optimization.xml
commons/proper/math/trunk/src/site/xdoc/userguide/overview.xml
Modified: commons/proper/math/trunk/src/site/site.xml
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/site.xml?rev=1469085&r1=1469084&r2=1469085&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/site.xml (original)
+++ commons/proper/math/trunk/src/site/site.xml Wed Apr 17 22:30:46 2013
@@ -64,6 +64,7 @@
<item name="Ordinary Differential Equations" href="/userguide/ode.html"/>
<item name="Genetic Algorithms" href="/userguide/genetics.html"/>
<item name="Filters" href="/userguide/filter.html"/>
+ <item name="Fitting" href="/userguide/fitting.html"/>
</menu>
</body>
Added: 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=1469085&view=auto
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/fitting.xml (added)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/fitting.xml Wed Apr 17
22:30:46 2013
@@ -0,0 +1,122 @@
+<?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.
+ -->
+
+<?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
+<!-- $Id$ -->
+<document url="fitting.html">
+
+ <properties>
+ <title>The Commons Math User Guide - Curve Fitting</title>
+ </properties>
+
+ <body>
+ <section name="17 Curve Fitting">
+ <subsection name="17.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 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:
+ <ul>
+ <li>
+ <a
href="../apidocs/org/apache/commons/math3/fitting/PolynomialFitter.html">
+ PolynomialFitter</a> fits a
+ <a
href="../apidocs/org/apache/commons/math3/analysis/polynomials/PolynomialFunction.Parametric.html">
+ polynomial</a> function
+ </li>
+ <li>
+ <a
href="../apidocs/org/apache/commons/math3/fitting/HarmonicFitter.html">
+ HarmonicFitter</a> fits a
+ <a
href="../apidocs/org/apache/commons/math3/analysis/function/HarmonicOscillator.Parametric.html">
+ harmonic</a> function
+ </li>
+ <li>
+ <a
href="../apidocs/org/apache/commons/math3/fitting/GaussianFitter.html">
+ GaussianFitter</a> fits a
+ <a
href="../apidocs/org/apache/commons/math3/analysis/function/Gaussian.Parametric.html">
+ Gaussian</a> function
+ </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.
+ </p>
+ </subsection>
+
+ </section>
+ </body>
+</document>
Propchange: commons/proper/math/trunk/src/site/xdoc/userguide/fitting.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: commons/proper/math/trunk/src/site/xdoc/userguide/index.xml
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/userguide/index.xml?rev=1469085&r1=1469084&r2=1469085&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/index.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/index.xml Wed Apr 17
22:30:46 2013
@@ -127,7 +127,6 @@
<li><a href="optimization.html#a12.3_Linear_Programming">12.3
Linear Programming</a></li>
<li><a href="optimization.html#a12.4_Direct_Methods">12.4
Direct Methods</a></li>
<li><a href="optimization.html#a12.5_General_Case">12.5
General Case</a></li>
- <li><a href="optimization.html#a12.6_Curve_Fitting">12.6 Curve
Fitting</a></li>
</ul></li>
<li><a href="ode.html">13. Ordinary Differential Equations
Integration</a>
<ul>
@@ -157,6 +156,13 @@
<li><a href="exceptions.html#a16.4_Features">16.4 Features</a></li>
</ul>
</li>
+ <li><a href="fitting.html">17. Curve Fitting</a>
+ <ul>
+ <li><a href="fitting.html#a17.1_Overview">17.1 Overview</a></li>
+ <li><a href="fitting.html#a17.2_General_Case">17.2 General
Case</a></li>
+ <li><a href="fitting.html#a17.3_Special_Cases">17.3 Special
Cases</a></li>
+ </ul>
+ </li>
</ul>
</section>
Modified: commons/proper/math/trunk/src/site/xdoc/userguide/optimization.xml
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/userguide/optimization.xml?rev=1469085&r1=1469084&r2=1469085&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/optimization.xml
(original)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/optimization.xml Wed Apr
17 22:30:46 2013
@@ -27,6 +27,10 @@
<body>
<section name="12 Optimization">
+ <p><em>The contents of this section currently describes deprecated
classes.</em>
+ Please refer to the new <a
href="../apidocs/org/apache/commons/math3/optim/package-summary.html">API
description</a>.
+ </p>
+
<subsection name="12.1 Overview" href="overview">
<p>
The optimization package provides algorithms to optimize (i.e.
either minimize
@@ -578,66 +582,6 @@ C: 16.324008168386605
PowellOptimizer</a> provides an optimization method for
non-differentiable functions.
</p>
</subsection>
- <subsection name="12.6 Curve Fitting" href="fitting">
- <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 sum(y<sub>i</sub>-f(x<sub>i</sub>))<sup>2</sup>. This is
really a 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>
- <p>
- The <a
-
href="../apidocs/org/apache/commons/math3/optimization/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>
-
- <p>
- The more specialized <a
href="../apidocs/org/apache/commons/math3/optimization/fitting/HarmonicFitter.html">
- HarmonicFitter</a> classes requires neither an implementation of the
parametric real function
- nor an initial guess as it is are able to compute them internally.
- </p>
- </subsection>
</section>
</body>
</document>
Modified: commons/proper/math/trunk/src/site/xdoc/userguide/overview.xml
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/userguide/overview.xml?rev=1469085&r1=1469084&r2=1469085&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/overview.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/overview.xml Wed Apr 17
22:30:46 2013
@@ -45,6 +45,7 @@
<ul>
<li>Computing means, variances and other summary statistics for a list
of numbers</li>
<li>Fitting a line to a set of data points using linear regression</li>
+ <li>Fitting a curve to a set of data points</li>
<li>Finding a smooth curve that passes through a collection of points
(interpolation)</li>
<li>Fitting a parametric model to a set of measurements using
least-squares methods</li>
<li>Solving equations involving real-valued functions (i.e.
root-finding)</li>
@@ -72,7 +73,7 @@
<subsection name="0.3 How commons-math is organized" href="organization">
<p>
Commons Math is divided into fourteen subpackages, based on functionality
provided.
- <ol>
+ <ul>
<li><a href="stat.html">org.apache.commons.math3.stat</a> - statistics,
statistical tests</li>
<li><a href="analysis.html">org.apache.commons.math3.analysis</a> -
rootfinding, integration, interpolation, polynomials</li>
<li><a href="random.html">org.apache.commons.math3.random</a> - random
numbers, strings and data generation</li>
@@ -84,10 +85,11 @@
<li><a href="fraction.html">org.apache.commons.math3.fraction</a> -
rational numbers</li>
<li><a href="transform.html">org.apache.commons.math3.transform</a> -
transform methods (Fast Fourier)</li>
<li><a href="geometry.html">org.apache.commons.math3.geometry</a> -
geometry (Euclidean spaces and Binary Space Partitioning)</li>
- <li><a
href="optimization.html">org.apache.commons.math3.optimization</a> - function
maximization or minimization</li>
+ <li><a href="optimization.html">org.apache.commons.math3.optim</a> -
function maximization or minimization</li>
<li><a href="ode.html">org.apache.commons.math3.ode</a> - Ordinary
Differential Equations integration</li>
<li><a href="genetics.html">org.apache.commons.math3.genetics</a> -
Genetic Algorithms</li>
- </ol>
+ <li><a href="fitting.html">org.apache.commons.math3.fitting</a> - Curve
Fitting</li>
+ </ul>
Package javadocs are <a href="../apidocs/index.html">here</a>
</p>
</subsection>
