sddspfit

**description:**`sddspfit`does ordinary and Chebyshev polynomial fits to column data, including error analysis. It will do fits to with specified number of terms, with specific terms only, and with specific symmetry only. It will also eliminate spurious terms.**synopsis:**`sddspfit [-pipe=[input][,output]] [`*inputFile*] [*outputFile*] [-evaluate=*filename*[,begin=*value*][,end=*value*][,number=*integer*]] -columns=*xName*,*yName*[,xSigma=*name*][,ySigma=*name*] -terms=*number*[-symmetry={none | odd | even}] | -orders=*number*[,*number*...] [-reviseOrders[=threshold=*chiValue*][,verbose][,complete=<chiThreshold>][,goodEnough=<chiValue>]] [-chebyshev[=convert]] [-xOffset=*value*] [-xFactor=*value*] [-sigmas={absolute=*value*| fractional=*value*}] [-modifySigmas] [-generateSigmas[=keepLargest | keepSmallest]] [-sparse=*interval*] [-range=*lower*,*upper*] [-normalize[=*termNumber*]] [-verbose] [-fitLabelFormat=*sprintfString*]**files:***inputFile*is an SDDS file containing columns of data to be fit. If it contains multiple pages, they are processed separately.*outputFile*is an SDDS file containing one page for each page of*inputFile*. It contains columns of the independent and dependent variable data, plus columns for error bars (``sigmas'') as appropriate. The values of the fit and of the residuals are in a columns named*yName*`Fit`and*yName*`Residual`.*outputFile*also contains the following one-dimensional arrays:`Order`: a long integer array of the polynomial orders used in the fit.`Coefficient`: a double-precision array of fit coefficients.`CoefficientSigma`: a double-precision array of fit coefficient errors. Present only if errors are present for data.`CoefficientUnits`: a string array of fit coefficient units.

*outputFile also contains the following parameters*:`Basis`: a string identifying the type of polynomials use.`ReducedChiSquared`: the reduced chi-squared of the fit:

, where is the number of degrees of freedom for a fit of N points with T terms.`rmsResidual`*xName*`Offset`,*xName*`Factor``FitIsValid`: a character having values`y`and`n`if the page contains a valid fit or not.`Terms`: the number of terms in the fit.`sddspfitLabel`: a string containing an equation showing the fit, suitable for use with`sddsplot`.`Intercept`,`Slope`,`Curvature`: the three lowest order coefficients for ordinary polynomial fits. These are present only if orders 0, 1, and 2 respectively are requested in fitting. If error analysis is valid, then the errors for these quantities appear as*quantityName*`Sigma`.

**switches:**`-pipe[=input][,output]`-- The standard SDDS Toolkit pipe option.`-evaluate=`-- Specifies creation of an SDDS file called*filename*[,begin=*value*][,end=*value*][,number=*integer*]*filename*containing points from evaluation of the fit. The fit is normally evaluated over the range of the input data; this may be changed using the`begin`and`end`qualifiers. Normally, the number of points at which the fit is evaluated is the number of points in the input data; this may be changed using the`number`qualifier.`-columns=`-- Specifies the names of the columns to use for the independent and dependent data, respectively.*xName*,*yName*[,xSigma=*name*][,ySigma=*name*]`xSigma`and`ySigma`can be used to specify the errors for the independent and dependent data, respectively.- By default, an ordinary polynomial fit is done using a constant and linear term. Control of what fit terms are used is
provided by the following switches:
`-terms=`-- Specifies the number of terms to be used in fitting. 2 terms is linear fit, 3 is quadratic, etc.*number*`-symmetry={none | odd | even}`-- When used with`-terms`, allows specifying the symmetry of the N terms used.`none`is the default.`odd`implies using linear, cubic, etc., while`even`implies using constant, quadratic, etc.`-orders=`-- Specifies the polynomial orders to be used in fitting. The default is equivalent to*number*[,*number*...]*-orders=0,1*.`-reviseOrders[=threshold=`*chiValue1*][,verbose]`[,complete=`-- Specifies adaptive fitting to eliminate spurious terms. When invoked, this switch causes*chiThreshold*][,goodEnough=*chiValue2*]`sddspfit`to repeatedly fit the first page of data with different numbers of terms in an attempt to find a minimal number of terms that gives an acceptable fit. This is done in up to three stages:- The process starts by making a fit with all terms. Then, each term is eliminated individually
and a new fit is made. If the new fit has a smaller reduced chi-squared by an amount of at least
*chiValue1*, then the term is permanently eliminated and the process is repeated for each remaining term. By default, the criterion for an improvement is a change of 0.1 in the reduced chi-squared. This step eliminates terms that result in a bad fit due to numerical problems. If the`goodEnough=`qualifier is given, then the first fit that has reduced chi-squared less than*chiValue2**chiValue2*is used. - Next, the individual terms are tested for how well they improve reduced chi-squared. Any term
that does not improve the reduced chi-squared by at least
*chiValue1*is eliminated. This stage eliminates terms that do not sufficiently improve the fit to merit inclusion. Again, if the`goodEnough=`qualifier is given, then the first fit that has reduced chi-squared less than*chiValue2**chiValue2*is used. - Finally, if
`complete=`is given, then next stage involves repeating the above procedure with the remaining terms, but instead of eliminating one term at a time, the program tests each possible combination of terms. This can be very time consuming, especially if the*chiThreshold*`goodEnough=`qualifier is not given.*chiValue2*

- The process starts by making a fit with all terms. Then, each term is eliminated individually
and a new fit is made. If the new fit has a smaller reduced chi-squared by an amount of at least
`[-chebyshev[=convert]]`-- Asks that Chebyshev T polynomials be used in fitting. If`convert`is given, the output contains the coeffients for the equivalent ordinary polynomials.

`-xOffset=`,*value*`-xFactor=`-- Specify offseting and scaling of the independent data prior to fitting. The transformation is . This feature can be used to make a fit about a point other than x=0, or to scale the data to make high-order fits more accurate.*value*`sddspfit`will compute error bars (``sigmas'') for fit coefficients if it has knowledge of the sigmas for the data points. These can be supplied using the`-columns`switch, or generated internally in several ways:`-sigmas=absolute=`-- Specifies that independent-variable errors be generated using a specified value for all points, or a specified fraction for all points.*value*| fractional=*value*`-modifySigmas`-- Specifies that independent-variable sigmas be modified to include the effect of uncertainty in the dependent variable values. If this option is not given, any x sigmas specified with`-columns`are ignored.`-generateSigmas[={keepLargest | keepSmallest}]`-- Specifies that independent-variable errors be generated from the variance of an initial equal-weights fit. If errors are already given (via*-column*), one may request that for every point`sddspfit`retain the larger or smaller of the sigma in the data and the one given by the variance.

`-sparse=`-- Specifies sparsing of the input data prior to fitting. This can greatly speed computations when the number of data points is large.*interval*`-range=`-- Specifies the range of independent variable over which to do fitting.*lower*,*upper*`-normalize[=`-- Specifies that coefficients be normalized so that the coefficient for the indicated order is unity. By default, the 0-order term (i.e., the constant term) is normalized to unity.*termNumber*]`-verbose`-- Specifies that the results of the fit be printed to the standard error output.`-fitLabelFormat=`-- Specifies the format to use for printing numbers in the fit label. The default is ``%g''.*sprintfString*

**see also:****author:**M. Borland, ANL/APS.