STScI Logo

fweight ctools


NAME · USAGE · DESCRIPTION · PARAMETERS · EXAMPLES · BUGS · REFERENCES
SEE_ALSO

NAME

fweight -- compute weights for use by the splice task

USAGE

fweight intable1 intable2 outtable

DESCRIPTION

This is an IRAF task to compute weights and include them as a column in spectral data, for use with the splice task.

There are two input tables. intable1 contains spectra for which weights are to be assigned, e.g. an "_x1d.fits" or "_sx1.fits" file. intable2 is supplied by the user; this table contains wavelengths and fluxes, but the fluxes should have been smoothed, for example by the continuum task.

The output table outtable will be a copy of intable1 (or intable1 can be operated on in-place). A weight column will be added, if it doesn't already exist, and the weights will be assigned.

The weights assigned by this task are suitable for combining the spectral fluxes using splice. No scalar weight should need to be specified, since the weights assigned by fweight include the exposure time.

The weights will be computed as follows:

The weight is the signal to noise squared, (S/N)**2, divided by the dispersion. Dividing by the dispersion is appropriate because splice adds up fluxes within each output bin. If an input bin contains a lot of counts in a small wavelength interval, it should get higher weight than an input bin with the same counts in a wide wavelength interval.

The signal at a pixel is the net number of electrons included in the extraction box. The noise is estimated as the square root of the gross number of electrons in the extraction box. The net and gross column values in intable1 are not used directly, however, because they fluctuate, and the high-valued pixels are no more significant than the low-valued pixels if the difference is just due to noise. Furthermore, the weight should not go up or down significantly within emission or absorption lines, because when the input tables don't have the same resolution the relative weights in the wings of the lines will not be correct.

The signal is therefore computed from the smoothed flux from intable2, rather than being taken from the observed values in intable1. These fluxes have to be converted to the equivalent number of electrons, and this is done by multiplying the flux by the instrumental sensitivity and the exposure time. We get the sensitivity from intable1 just by dividing the net count rate by the flux. The gross counts are gotten by adding the background to the number of detected electrons (as computed from the smoothed flux).

    sensitivity = net[i] * gain / flux[i]
    Back_e = background[i] * gain * exptime

    signal = smoothed_flux[i] * sensitivity * exptime
    noise = sqrt (signal + Back_e)
    (S/N)**2 = signal**2 / (signal + Back_e)
             = signal / (1 + (Back_e / signal))

    weight[i] = signal / (1 + average (Back_e / signal)) / dispersion

In the above, i is an array index in a spectral order in intable1 (or a row number, if intable1 contains scalar columns). flux, net and background are columns in intable1; note that net is a count rate. Back_e is from the intable1 background column, but it has been converted to electrons by multiplying by gain and exposure time. The average of (Back_e / signal) is taken over all pixels, and the factor dividing into the signal is formed from that average: 1 + average (Back_e / signal). smoothed_flux is from the flux column of intable2, but it has been interpolated at the wavelength of array index i in intable1. The gain is from the ATODGAIN primary header keyword, and the exposure time is from the EXPTIME table (extension) header keyword.

In deep absorption lines or regions of low signal to noise, there can be points where the net count rate (the true net, not scaled from the smoothed flux) will be zero. At these points, we can't compute the sensitivity from the data, so the weight is temporarily set to zero. After computing all the weights, zero or negative weights will be replaced by linearly interpolated values from adjacent weights that are greater than zero. At the endpoints, zero or negative weights will be replaced by the nearest positive weight.

The input table columns can contain arrays (as in x1d output), or they can be scalar columns. The array size of the WAVELENGTH column is used to distinguish between these two cases. If the columns contain arrays, the NELEM column is assumed to contain the array length for the WAVELENGTH, NET, FLUX, BACKGROUND and wgt_name columns, and this value can change from row to row. If the NELEM column is not found, however, the length of the WAVELENGTH column will be used instead, and this value is constant for all rows.

PARAMETERS

intable[file name template]
A list of tables containing spectra for which weights are to be assigned. Normally, the the input table will be copied to outtable, and then the copy will be modified. However, intable1 can be modified in-place; see the description of outtable.

The following columns are required in intable1: WAVELENGTH, FLUX, NET. If the BACKGROUND column is present, it will also be read, but it is not required. The EXPTIME header keyword is required, for the exposure time in seconds; note that the TEXPTIME primary header keyword is NOT used, since this does not necessarily have any useful relationship with the exposure time. The ATODGAIN keyword will be used if it is found; the task looks for it first in the primary header and then in the table header.

If an input FITS file contains more than one table, each such table needs to be listed individually.

Note: If a row selector is specified, in order to assign weights to some but not all rows of a table, this should be done in-place, i.e. the output table should be null or the same name as the input. Otherwise, an output table will be created that has only the selected rows, and the other rows will not be copied to output.

intable[file name template]
A list of tables containing wavelengths and smoothed continuum (for example a continuum fit). intable2 can be a simple text file, with the wavelengths in the first column and the fluxes in the second column. If intable2 is a binary table (FITS or stsdas format), the wavelengths and fluxes must be in columns with the names "WAVELENGTH" and "FLUX" respectively. If the columns contain arrays, and there is more than one row in intable2, use a row selector (see "help selectors") to specify which row to use.

The flux scale for intable2 is arbitrary, to the extent that as long as the same scale is used for all tables to be spliced together, the relative weights will be the same. To first order, then, intable2 could be a text file containing just these two lines:

     1000.  1.e-15
    10000.  1.e-15

The number of names in intable2 must be the same as the number of names in intable1, except that if just one intable2 is specified it will be used for all the tables in intable1.

outtable [file name template]
A list of output tables. If outtable is blank, or if the file names are the same as intable1, then intable1 will be modified in-place. If outtable contains just one file name, while intable1 contains more than one table name, all those in intable1 will be copied to outtable, one table per extension. Otherwise, the number of names in outtable must be the same as the number in intable1.
(wgt_name = "weight") [string]
The name of the column to contain the weights. If a column by this name (case insensitive) doesn't exist, it will be created; if it does exist, the values will be overwritten.
(interpolant = "spline") [string, allowed values: linear | spline]
The continuum flux values in intable2 will be interpolated at the wavelengths in intable1. This parameter specifies whether linear interpolation or cubic spline interpolation will be used.
(verbose = yes) [boolean]
The default is to print the names of the input and output tables as they are processed.

EXAMPLES

1. Assign weights to o52z24010_x1d.fits, using continuum flux in smoothed_flux.txt, and writing the output to o52z24010.fits.

    st> fweight o52z24010_x1d.fits smoothed_flux.txt o52z24010.fits

2. Create the continuum fit file for example 1. This will create smoothed_flux.tab, with columns "wavelength" and "flux". See the help for sflux -- or the next example -- for further details.

    on> sflux o52z24010_x1d.fits smoothed_flux.tab

3. These are the steps that could be used to create the continuum fit file. The resulting fit will be in either smoothed_flux.txt or smoothed_flux.tab. smoothed_flux.txt will be a text table with columns "c1" and "c2", and smoothed_flux.tab will be an stsdas table with columns "wavelength" and "flux".

    st> splice o52z24010_x1d.fits qqtemp.fits wgt_name="" sw_name=""
    st> tomultispec qqtemp.fits qqtemp.imh
    on> continuum qqtemp.imh qqtemp_c.imh type="fit"

    im> listpixels qqtemp_c.imh wcs="world" > smoothed_flux.txt
or
    tt> imtab qqtemp_c.imh smoothed_flux.tab flux pname="wl" wcs="world"
    tt> tchcol smoothed_flux.tab wl1 wavelength "" ""

    # delete temporary files
    im> imdel qqtemp.fits,qqtemp.imh,qqtemp_c.imh

BUGS

The weights written by fweight and pweight use different normalization, since one is based on the data and the other on the throughput table. When running splice, the weights must be set consistently either by fweight or by pweight.

REFERENCES

This task was written by Phil Hodge based on an algorithm by Harry Ferguson and Tom Brown.

SEE ALSO

splice, sflux, pweight


Source Code · Package Help · Search Form · STSDAS