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 yNameFit and yNameResidual. 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:
    
    $$\chi 2_\nu = \frac{\chi 2}{\nu} = \frac{1}{N-T}\Sigma_{i=0} {N-1} \left(\frac{y_i - y(x_i)}{\sigma_i}\right) 2$$
    
    
    , where $\nu = N-T$ is the number of degrees of freedom for a fit of N points with T terms.
  • rmsResidual
  • xNameOffset, xNameFactor
  • 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 quantityNameSigma.

• switches:
  • -pipe[=input][,output] -- The standard SDDS Toolkit pipe option.
  • -evaluate=filename[,begin=value][,end=value][,number=integer] -- Specifies creation of an SDDS file called 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=xName,yName[,xSigma=name][,ySigma=name] -- Specifies the names of the columns to use for the independent and dependent data, respectively. 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=number -- Specifies the number of terms to be used in fitting. 2 terms is linear fit, 3 is quadratic, etc.
    • -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=number[,number...] -- Specifies the polynomial orders to be used in fitting. The default is equivalent to -orders=0,1.
    • -reviseOrders[=threshold=chiValue1][,verbose] [,complete=chiThreshold][,goodEnough=chiValue2] -- Specifies adaptive fitting to eliminate spurious terms. When invoked, this switch causes 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:
      1. 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=chiValue2 qualifier is given, then the first fit that has reduced chi-squared less than chiValue2 is used.
      2. 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=chiValue2 qualifier is given, then the first fit that has reduced chi-squared less than chiValue2 is used.
      3. Finally, if complete=chiThreshold 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 goodEnough=chiValue2 qualifier is not given.
    • [-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=value -- Specify offseting and scaling of the independent data prior to fitting. The transformation is ${\rm x \rightarrow (x - Offset)/Factor}$. 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.
  • 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=value | fractional=value -- Specifies that independent-variable errors be generated using a specified value for all points, or a specified fraction for all points.
    • -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=interval -- Specifies sparsing of the input data prior to fitting. This can greatly speed computations when the number of data points is large.
  • -range=lower,upper -- Specifies the range of independent variable over which to do fitting.
  • -normalize[=termNumber] -- 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.
  • -verbose -- Specifies that the results of the fit be printed to the standard error output.
  • -fitLabelFormat=sprintfString -- Specifies the format to use for printing numbers in the fit label. The default is ``%g''.
• see also:
  • Data for Examples
  • sddsexpfit
  • sddsgfit
  • sddsplot
  • sddsoutlier
• author: M. Borland, ANL/APS.