Clean up Fit POD

pod/Fit.pod

@@ -17,27 +17,86 @@ Math::GSL::Fit - Least-squares functions for a general linear model with one- or
 
 =head1 SYNOPSIS
 
-use Math::GSL::Fit qw /:all/;
+    use Math::GSL::Fit qw/:all/;
 
 =head1 DESCRIPTION
 
-The functions in this module perform least-squares fits to a general linear model, y = X c where y is a vector of n observations, X is an n by p matrix of predictor variables, and the elements of the vector c are the p unknown best-fit parameters which are to be estimated.
+The functions in this module perform least-squares fits to a general linear
+model, y = X c where y is a vector of n observations, X is an n by p matrix of
+predictor variables, and the elements of the vector c are the p unknown
+best-fit parameters which are to be estimated.
 
 Here is a list of all the functions in this module :
 
-=over 
-
-=item C<gsl_fit_linear($x, $xstride, $y, $ystride, $n)> - This function computes the best-fit linear regression coefficients (c0,c1) of the model Y = c_0 + c_1 X for the dataset ($x, $y), two vectors (in form of arrays) of length $n with strides $xstride and $ystride. The errors on y are assumed unknown so the variance-covariance matrix for the parameters (c0, c1) is estimated from the scatter of the points around the best-fit line and returned via the parameters (cov00, cov01, cov11). The sum of squares of the residuals from the best-fit line is returned in sumsq. Note: the correlation coefficient of the data can be computed using gsl_stats_correlation (see Correlation), it does not depend on the fit. The function returns the following values in this order : 0 if the operation succeeded, 1 otherwise, c0, c1, cov00, cov01, cov11 and sumsq.
-
-=item C<gsl_fit_wlinear($x, $xstride, $w, $wstride, $y, $ystride, $n)> - This function computes the best-fit linear regression coefficients (c0,c1) of the model Y = c_0 + c_1 X for the weighted dataset ($x, $y), two vectors (in form of arrays) of length $n with strides $xstride and $ystride. The vector (also in the form of an array) $w, of length $n and stride $wstride, specifies the weight of each datapoint. The weight is the reciprocal of the variance for each datapoint in y. The covariance matrix for the parameters (c0, c1) is computed using the weights and returned via the parameters (cov00, cov01, cov11). The weighted sum of squares of the residuals from the best-fit line, \chi^2, is returned in chisq. The function returns the following values in this order : 0 if the operation succeeded, 1 otherwise, c0, c1, cov00, cov01, cov11 and sumsq.
-
-=item C<gsl_fit_linear_est($x, $c0, $c1, $cov00, $cov01, $cov11)> - This function uses the best-fit linear regression coefficients $c0, $c1 and their covariance $cov00, $cov01, $cov11 to compute the fitted function y and its standard deviation y_err for the model Y = c_0 + c_1 X at the point $x. The function returns the following values in this order : 0 if the operation succeeded, 1 otherwise, y and y_err.
-
-=item C<gsl_fit_mul($x, $xstride, $y, $ystride, $n)> - This function computes the best-fit linear regression coefficient c1 of the model Y = c_1 X for the datasets ($x, $y), two vectors (in form of arrays) of length $n with strides $xstride and $ystride. The errors on y are assumed unknown so the variance of the parameter c1 is estimated from the scatter of the points around the best-fit line and returned via the parameter cov11. The sum of squares of the residuals from the best-fit line is returned in sumsq. The function returns the following values in this order : 0 if the operation succeeded, 1 otherwise, c1, cov11 and sumsq.
-
-=item C<gsl_fit_wmul($x, $xstride, $w, $wstride, $y, $ystride, $n)> - This function computes the best-fit linear regression coefficient c1 of the model Y = c_1 X for the weighted datasets ($x, $y), two vectors (in form of arrays) of length $n with strides $xstride and $ystride. The vector (also in the form of an array) $w, of length $n and stride $wstride, specifies the weight of each datapoint. The weight is the reciprocal of the variance for each datapoint in y. The variance of the parameter c1 is computed using the weights and returned via the parameter cov11. The weighted sum of squares of the residuals from the best-fit line, \chi^2, is returned in chisq. The function returns the following values in this order : 0 if the operation succeeded, 1 otherwise, c1, cov11 and sumsq.
-
-=item C<gsl_fit_mul_est($x, $c1, $cov11)> - This function uses the best-fit linear regression coefficient $c1 and its covariance $cov11 to compute the fitted function y and its standard deviation y_err for the model Y = c_1 X at the point $x. The function returns the following values in this order : 0 if the operation succeeded, 1 otherwise, y and y_err.
+=over
+
+=item gsl_fit_linear($x, $xstride, $y, $ystride, $n)
+
+This function computes the best-fit linear regression coefficients (c0,c1) of
+the model Y = c_0 + c_1 X for the dataset ($x, $y), two vectors (in form of
+arrays) of length $n with strides $xstride and $ystride. The errors on y are
+assumed unknown so the variance-covariance matrix for the parameters (c0, c1)
+is estimated from the scatter of the points around the best-fit line and
+returned via the parameters (cov00, cov01, cov11). The sum of squares of the
+residuals from the best-fit line is returned in sumsq. Note: the correlation
+coefficient of the data can be computed using gsl_stats_correlation (see
+Correlation), it does not depend on the fit. The function returns the following
+values in this order : 0 if the operation succeeded, 1 otherwise, c0, c1,
+cov00, cov01, cov11 and sumsq.
+
+=item gsl_fit_wlinear($x, $xstride, $w, $wstride, $y, $ystride, $n)
+
+This function computes the best-fit linear regression coefficients (c0,c1) of
+the model Y = c_0 + c_1 X for the weighted dataset ($x, $y), two vectors (in
+form of arrays) of length $n with strides $xstride and $ystride. The vector
+(also in the form of an array) $w, of length $n and stride $wstride, specifies
+the weight of each datapoint. The weight is the reciprocal of the variance for
+each datapoint in y. The covariance matrix for the parameters (c0, c1) is
+computed using the weights and returned via the parameters (cov00, cov01,
+cov11). The weighted sum of squares of the residuals from the best-fit line,
+\chi^2, is returned in chisq. The function returns the following values in this
+order : 0 if the operation succeeded, 1 otherwise, c0, c1, cov00, cov01, cov11
+and sumsq.
+
+=item gsl_fit_linear_est($x, $c0, $c1, $cov00, $cov01, $cov11)
+
+This function uses the best-fit linear regression coefficients $c0, $c1 and
+their covariance $cov00, $cov01, $cov11 to compute the fitted function y and
+its standard deviation y_err for the model Y = c_0 + c_1 X at the point $x. The
+function returns the following values in this order : 0 if the operation
+succeeded, 1 otherwise, y and y_err.
+
+=item gsl_fit_mul($x, $xstride, $y, $ystride, $n)
+
+This function computes the best-fit linear regression coefficient c1 of the
+model Y = c_1 X for the datasets ($x, $y), two vectors (in form of arrays) of
+length $n with strides $xstride and $ystride. The errors on y are assumed
+unknown so the variance of the parameter c1 is estimated from the scatter of
+the points around the best-fit line and returned via the parameter cov11. The
+sum of squares of the residuals from the best-fit line is returned in sumsq.
+The function returns the following values in this order : 0 if the operation
+succeeded, 1 otherwise, c1, cov11 and sumsq.
+
+=item gsl_fit_wmul($x, $xstride, $w, $wstride, $y, $ystride, $n)
+
+This function computes the best-fit linear regression coefficient c1 of the
+model Y = c_1 X for the weighted datasets ($x, $y), two vectors (in form of
+arrays) of length $n with strides $xstride and $ystride. The vector (also in
+the form of an array) $w, of length $n and stride $wstride, specifies the
+weight of each datapoint. The weight is the reciprocal of the variance for each
+datapoint in y. The variance of the parameter c1 is computed using the weights
+and returned via the parameter cov11. The weighted sum of squares of the
+residuals from the best-fit line, \chi^2, is returned in chisq. The function
+returns the following values in this order : 0 if the operation succeeded, 1
+otherwise, c1, cov11 and sumsq.
+
+=item gsl_fit_mul_est($x, $c1, $cov11)
+
+This function uses the best-fit linear regression coefficient $c1 and its
+covariance $cov11 to compute the fitted function y and its standard deviation
+y_err for the model Y = c_1 X at the point $x. The function returns the
+following values in this order : 0 if the operation succeeded, 1 otherwise, y
+and y_err.
 
 =back
 
@@ -48,20 +107,23 @@ documentation: L<http://www.gnu.org/software/gsl/manual/html_node/>
 
 =head1 EXAMPLES
 
-This example shows how to use the function gsl_fit_linear. It's important to see that the array passed to to function must be an array reference, not a simple array. Also when you use strides, you need to initialize all the value in the range used, unless you will get warnings.
+This example shows how to use the function gsl_fit_linear. It's important to
+see that the array passed to to function must be an array reference, not a
+simple array. Also when you use strides, you need to initialize all the value
+in the range used, otherwise you will get warnings.
 
- my @norris_x = (0.2, 337.4, 118.2, 884.6, 10.1, 226.5, 666.3, 996.3,
+    my @norris_x = (0.2, 337.4, 118.2, 884.6, 10.1, 226.5, 666.3, 996.3,
                         448.6, 777.0, 558.2, 0.4, 0.6, 775.5, 666.9, 338.0, 
                         447.5, 11.6, 556.0, 228.1, 995.8, 887.6, 120.2, 0.3, 
                         0.3, 556.8, 339.1, 887.2, 999.0, 779.0, 11.1, 118.3,
                         229.2, 669.1, 448.9, 0.5 ) ;
- my @norris_y = ( 0.1, 338.8, 118.1, 888.0, 9.2, 228.1, 668.5, 998.5,
+    my @norris_y = ( 0.1, 338.8, 118.1, 888.0, 9.2, 228.1, 668.5, 998.5,
                         449.1, 778.9, 559.2, 0.3, 0.1, 778.1, 668.8, 339.3, 
                         448.9, 10.8, 557.7, 228.3, 998.0, 888.8, 119.6, 0.3, 
                         0.6, 557.6, 339.3, 888.0, 998.5, 778.9, 10.2, 117.6,
                         228.9, 668.4, 449.2, 0.2);
-    my $xstride = 2; 
-    my $wstride = 3; 
+    my $xstride = 2;
+    my $wstride = 3;
     my $ystride = 5;
     my ($x, $w, $y);
     for my $i (0 .. 175)