diff options
Diffstat (limited to 'pkg/utilities/doc/surfit.hlp')
| -rw-r--r-- | pkg/utilities/doc/surfit.hlp | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/pkg/utilities/doc/surfit.hlp b/pkg/utilities/doc/surfit.hlp new file mode 100644 index 00000000..36b70803 --- /dev/null +++ b/pkg/utilities/doc/surfit.hlp @@ -0,0 +1,257 @@ +.help surfit Jun93 utilities +.ih +NAME +surfit -- fit a surface, z=f(x,y), to a set of x, y, z points +.ih +USAGE +surfit input +.ih +PARAMETERS +.ls input +Input text file containing the data to be fit. The file consists of lines +with three or four whitespace separated values giving x, y, z, and +optionally a weight. +.le +.ls image = "" +Optional image name in which to create an evenly sampled image of the +fitted surface. If no name is specified a image is not created. If an +image name is specified then the x range in the input is evenly divided by +the specified number of image columns, the y range is evenly divided by the +specified number of lines, and the fitted surface values evaluated at the +sampled x and y points are written as the pixel values of the image. A +linear world coordinate system based on the x and y values is also created +for the image. +.le +.ls coordinates = "", fit = "" +The first two columns of the text file specified by the coordinates parameter +are use to supply x and y values which are evaluated by the surface and +the resulting x, y, and z values are appended to the specified fit file. +If either parameter is not specified then this surface evaluation is +not done. Note that the input data points are evaluated as part of +the standard output but one may, if desired, specify the input file +as the coordinate file to create a separate output. +.le + +.ls function = "polynomial" (chebyshev|legendre|polynomial) +Surface function type to fit. The choices are a chebyshev, legendre, +or simple power series bi-dimensional polynomial. +.le +.ls xorder = 2, yorder = 2 +The polynomial orders in x and y. +.le +.ls xterms = "full" +The options are: +.ls none +The individual polynomial terms contain powers of x or powers of y but not +powers of both. +.le +.ls half +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is max (xorder - 1, yorder - 1). +.le +.ls full +The individual polynomial terms contain powers of x and powers of y, whose +maximum combined power is max (xorder - 1 + yorder - 1). +.le +.le +.ls weighting = "user" (uniform|user|statistical|instrumental) +The type of weighting for the fit. The options are: +.ls uniform +All weights are 1. Any input weights are ignored. +.le +.ls user +The weights in the fourth input column are used. If no weight is given +a weight of 1 is supplied. +.le +.ls statistical +The reciprocal of the absolute value of z input data is used as the weight. +Any input weights are ignored. Z values less than 1e-20 are set to 1e-20. +.le +.ls instrumental +The fourth input column is taken as a sigma and the weight is the +reciprocal of the sigma squared. If no sigma is given a sigma of +1 is supplied. Sigma values less than 1e-10 are set to 1e-10. +.le +.le +.ls xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF +These parameters define the range of input x and y data to be used and +also define the range over which the surface function is defined. If +INDEF then the appropriate limit from the input data points is used. +If input data points lie outside these limits they are discarded. The +range may be given larger than the range of the input data in order +to all evaluating coordinates outside input data; i.e. to +allow extrapolation. +.le +.ls zmin = INDEF, zmax = INDEF +These parameters apply threshold limits to the input data. If INDEF +the appropriate limit from the input data points is used. Input +data points with z values outside this range are discarded. +.le +.ls ncols = 100, nlines = 100 +The number of columns and lines for the optional surface image. These +parameters determine the size of the image and how finely the x and +y input data range is subdivided. +.le +.ih +DESCRIPTION +This task fits a surface, a function of two coordinates, to a set of +possibly irregularly sampled data points specified in a text file. +The input consists of a file with three or four columns. The first +two columns define the two coordinates, called x and y, the third +column gives the value the function is supposed to fit, called z, +and the optional fourth column is a weight or sigma. If a weight or +sigma is not specified it will have a unit weight or sigma. The type +of weighting is selected by a task parameter. + +The input data points may be restricted by use of the \fIxmin, xmax, +ymin, ymax, zmin, zmax\fR parameters. If these parameters are INDEF +(the default) the full range of the input is used. The surface function +is only defined within the specified x and y range. In order to +extrapolate outside the range of the input data these limits must +be specified explicitly. + +The functions which may be fit are legendre, chebyshev, or simple +power series bi-dimensional polynomials. The user selects the +function type, the order in x and y, and whether to include +cross terms. The orders are the number of coefficients which +is the highest polynomial power plus 1. For example the default +values of 2 in each coordinate define a linear sloped plane. +All computations are done in double precision. + +Several polynomial cross terms options are available. Options "none", +"half", and "full" are illustrated below for a quadratic polynomial in +x and y. + +.nf +xterms = "none" +xorder = 3, yorder = 3 + + z = a11 + a21 * x + a12 * y + a31 * x ** 2 + a13 * y ** 2 + +xterms = "half" +xorder = 3, yorder = 3 + + z = a11 + a21 * x + a12 * y + a31 * x ** 2 + a22 * x * y + a13 * y ** 2 + +xterms = "full" +xorder = 3, yorder = 3 + + z = a11 + a21 * x + a31 * x ** 2 + + a12 * y + a22 * x * y + a32 * x ** 2 * y + + a13 * y ** 2 + a23 * x * y ** 2 + + a33 * x ** 2 * y ** 2 +.fi + + +The fit results are written to the standard output; the terminal unless +redirected. It consists of the input parameters, the coefficients and +errors, and the input data plus the fitted values and residuals. The +coefficient lines contain four columns. The first two columns are the x +and y polynomial powers and then the coefficient and error in the +coefficient are given. The coefficients are determined based on a +normalized coordinate; the range of input x and y values, which is shown in +the output as xmin, xmax, ymin, and ymax, is mapped to the range -1 to 1. +The data portion gives the x, y, and z input values followed by the fitted +value and the residual (z - fit) and finally the weight. + +There are two types of additional output which may be selected if desired. +One is a two dimensional image of the surface evenly sampled over the x and +y data range set by the xmin, xmax, ymin, ymax parameters. This type of +output is selected by specifying an image name and the number of columns +and lines. The number of columns and lines defines the size of the image +and also the sampling of the x and y values. The first pixel in each +dimension is the minimum x or y value and the sample interval per pixel is +given by: + +.nf + dx = (xmax - xmin) / (ncols - 1) + dy = (ymax - ymin) / (nlines - 1) +.fi + +The fitted surface is evaluated at each pixel and written to the image. +The linear world coordinate system defining the x and y pixel sampling is +written to the image header. This allows tasks such as \fBimplot\fR and +\fBlistpixels\fR to show the fitted values in the input x and y units. + +The second type of output allows the surface to be evaluated at an +arbitrary set of x and y coordinates. The coordinates are input +as a text file. The first two columns are taken as the x and y values +and any other columns are ignored. The x and y values and the fitted +values are appended to a specified text file. This output is +optional and only occurs if both an input coordinate and output +fit file are specified. Note that the input data points are +always evaluated as part of the standard output but the input +data file may also be used as a coordinate file if desired. +Also the output data file may be specified as "STDOUT" to merge +this output with the basic results output. +.ih +EXAMPLES +1. The following example shows use of all the output options using some +random numbers. + +.nf + cl> urand 50 3 scale=100. >sf1 + cl> head sf1 nl=5 + 70.87 42.5 99.06 + 51.49 42.19 64.86 + 70.75 83.34 80.39 + 57.1 67.79 30.24 + 60.91 49.76 53.32 + + cl> urand 5 2 scale=100. seed=2 >sf2 + cl> head sf2 + 20.62 17.86 + 66.39 86.26 + 48.08 35.07 + 70.39 95.8 + 53.64 15.51 + + cl> surfit sf1 image=sf coord=sf2 fit=sf3 ncols=20 nlines=20 + Surface parameters: + function = polynomial + xorder = 2 + yorder = 2 + xterms = full + weighting = user + xmin = 0.684 + xmax = 89.74 + ymin = 1.051 + ymax = 95.36 + zmin = 1.217 + zmax = 99.14 + + + Surface coefficients: + x y coeff error + 0 0 75.7125 17.2504 + 1 0 -0.37273 0.356014 + 0 1 -0.77194 0.336627 + 1 1 0.009884 0.006295 + + Fitted points: + x y z fit residual weight + 70.87 42.5 99.06 46.2611 52.7989 1. + 51.49 42.19 64.86 45.4249 19.4351 1. + 70.75 83.34 80.39 43.2899 37.1001 1. + 57.1 67.79 30.24 40.3604 -10.1204 1. + 60.91 49.76 53.32 44.5562 8.76384 1. + ... + + chisqr = 903.797 + + cl> head sf3 + 20.62 17.86 57.8802 + 66.39 86.26 40.9855 + 48.08 35.07 47.3864 + 53.64 15.51 51.9697 + + cl> listpix sf[*:10,*:10] wcs=world formats="%5.2f %5.2f" + 0.68 1.05 74.65366 + 47.56 1.05 57.66973 + 0.68 50.69 36.67273 + 47.56 50.69 42.6855 +.fi +.ih +SEE ALSO +apphot.fitsky, apphot.txdump, imsurfit +.endhelp |