.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Algorithm::CurveFit 3"
.TH Algorithm::CurveFit 3 "2015-08-21" "perl v5.22.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Algorithm::CurveFit \- Nonlinear Least Squares Fitting
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Algorithm::CurveFit;
.PP
.Vb 11
\&  # Known form of the formula
\&  my $formula = \*(Aqc + a * x^2\*(Aq;
\&  my $variable = \*(Aqx\*(Aq;
\&  my @xdata = read_file(\*(Aqxdata\*(Aq); # The data corresponsing to $variable
\&  my @ydata = read_file(\*(Aqydata\*(Aq); # The data on the other axis
\&  my @parameters = (
\&      # Name    Guess   Accuracy
\&      [\*(Aqa\*(Aq,     0.9,    0.00001],  # If an iteration introduces smaller
\&      [\*(Aqc\*(Aq,     20,     0.00005],  # changes that the accuracy, end.
\&  );
\&  my $max_iter = 100; # maximum iterations
\&
\&  my $square_residual = Algorithm::CurveFit\->curve_fit(
\&      formula            => $formula, # may be a Math::Symbolic tree instead
\&      params             => \e@parameters,
\&      variable           => $variable,
\&      xdata              => \e@xdata,
\&      ydata              => \e@ydata,
\&      maximum_iterations => $max_iter,
\&  );
\&
\&  use Data::Dumper;
\&  print Dumper \e@parameters;
\&  # Prints
\&  # $VAR1 = [
\&  #          [
\&  #            \*(Aqa\*(Aq,
\&  #            \*(Aq0.201366784209602\*(Aq,
\&  #            \*(Aq1e\-05\*(Aq
\&  #          ],
\&  #          [
\&  #            \*(Aqc\*(Aq,
\&  #            \*(Aq1.94690440147554\*(Aq,
\&  #            \*(Aq5e\-05\*(Aq
\&  #          ]
\&  #        ];
\&  #
\&  # Real values of the parameters (as demonstrated by noisy input data):
\&  # a = 0.2
\&  # c = 2
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Algorithm::CurveFit\*(C'\fR implements a nonlinear least squares curve fitting
algorithm. That means, it fits a curve of known form (sine-like, exponential,
polynomial of degree n, etc.) to a given set of data points.
.PP
For details about the algorithm and its capabilities and flaws, you're
encouraged to read the MathWorld page referenced below. Note, however, that it
is an iterative algorithm that improves the fit with each iteration until it
converges. The following rule of thumb usually holds true:
.IP "\(bu" 2
A good guess improves the probability of convergence and the quality
of the fit.
.IP "\(bu" 2
Increasing the number of free parameters decreases the quality and
convergence speed.
.IP "\(bu" 2
Make sure that there are no correlated parameters such as in 'a + b * e^(c+x)'.
(The example can be rewritten as 'a + b * e^c * e^x' in which 'c' and 'b' are
basically equivalent parameters.
.PP
The curve fitting algorithm is accessed via the 'curve_fit' subroutine.
It requires the following parameters as 'key => value' pairs:
.IP "formula" 2
.IX Item "formula"
The formula should be a string that can be parsed by Math::Symbolic.
Alternatively, it can be an existing Math::Symbolic tree.
Please refer to the documentation of that module for the syntax.
.Sp
Evaluation of the formula for a specific value of the variable (X\-Data)
and the parameters (see below) should yield the associated Y\-Data value
in case of perfect fit.
.IP "variable" 2
.IX Item "variable"
The 'variable' is the variable in the formula that will be replaced with the
X\-Data points for evaluation. If omitted in the call to \f(CW\*(C`curve_fit\*(C'\fR, the
name 'x' is default. (Hence 'xdata'.)
.IP "params" 2
.IX Item "params"
The parameters are the symbols in the formula whose value is varied by the
algorithm to find the best fit of the curve to the data. There may be
one or more parameters, but please keep in mind that the number of parameters
not only increases processing time, but also decreases the quality of the fit.
.Sp
The value of this options should be an anonymous array. This array should
hold one anonymous array for each parameter. That array should hold (in order)
a parameter name, an initial guess, and optionally an accuracy measure.
.Sp
Example:
.Sp
.Vb 5
\&  $params = [
\&    [\*(Aqparameter1\*(Aq, 5,  0.00001],
\&    [\*(Aqparameter2\*(Aq, 12, 0.0001 ],
\&    ...
\&  ];
\&
\&  Then later:
\&  curve_fit(
\&  ...
\&    params => $params,
\&  ...
\&  );
.Ve
.Sp
The accuracy measure means that if the change of parameters from one iteration
to the next is below each accuracy measure for each parameter, convergence is
assumed and the algorithm stops iterating.
.Sp
In order to prevent looping forever, you are strongly encouraged to make use of
the accuracy measure (see also: maximum_iterations).
.Sp
The final set of parameters is \fBnot\fR returned from the subroutine but the
parameters are modified in-place. That means the original data structure will
hold the best estimate of the parameters.
.IP "xdata" 2
.IX Item "xdata"
This should be an array reference to an array holding the data for the
variable of the function. (Which defaults to 'x'.)
.IP "ydata" 2
.IX Item "ydata"
This should be an array reference to an array holding the function values
corresponding to the x\-values in 'xdata'.
.IP "maximum_iterations" 2
.IX Item "maximum_iterations"
Optional parameter to make the process stop after a given number of iterations.
Using the accuracy measure and this option together is encouraged to prevent
the algorithm from going into an endless loop in some cases.
.PP
The subroutine returns the sum of square residuals after the final iteration
as a measure for the quality of the fit.
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None by default, but you may choose to export \f(CW\*(C`curve_fit\*(C'\fR using the
standard Exporter semantics.
.SS "\s-1SUBROUTINES\s0"
.IX Subsection "SUBROUTINES"
This is a list of public subroutines
.IP "curve_fit" 2
.IX Item "curve_fit"
This subroutine implements the curve fitting as explained in
\&\s-1DESCRIPTION\s0 above.
.SH "NOTES AND CAVEATS"
.IX Header "NOTES AND CAVEATS"
.IP "\(bu" 2
When computing the derivative symbolically using \f(CW\*(C`Math::Symbolic\*(C'\fR, the
formula simplification algorithm can sometimes fail to find the equivalent
of \f(CW\*(C`(x\-x_0)/(x\-x_0)\*(C'\fR. Typically, these would be hidden in a more complex
product. The effect is that for \f(CW\*(C`x \-> x_0\*(C'\fR, the evaluation of the
derivative becomes undefined.
.Sp
Since version 1.05, we fall back to numeric differentiation
using five-point stencil in such cases. This should help with one of the
primary complaints about the reliability of the module.
.IP "\(bu" 2
This module is \s-1NOT\s0 fast.
For slightly better performance, the formulas are compiled to
Perl code if possible.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The algorithm implemented in this module was taken from:
.PP
Eric W. Weisstein. \*(L"Nonlinear Least Squares Fitting.\*(R" From MathWorld\*(--A Wolfram Web Resource. http://mathworld.wolfram.com/NonlinearLeastSquaresFitting.html
.PP
New versions of this module can be found on http://steffen\-mueller.net or \s-1CPAN.\s0
.PP
This module uses the following modules. It might be a good idea to be familiar
with them. Math::Symbolic, Math::MatrixReal, Test::More
.SH "AUTHOR"
.IX Header "AUTHOR"
Steffen Mueller, <smueller@cpan.org<gt>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2005\-2010 by Steffen Mueller
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.6 or,
at your option, any later version of Perl 5 you may have available.