centerflux

centerflux

stsdas.hst_calib.hrs.z_calib

centerflux

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

NAME

centerflux -- Compute the flux values for the center of a spectrum.

DESCRIPTION

This task will compute the average flux, between pixels specified by the start_pixel, end_pixel or center, size parameters, for each input spectrum.

For GHRS data, the input data must consist of count rates which have been previously corrected for all pipeline reduction steps---except for vignetting removal, which is optional, and absolute sensitivity correction. If vignetting is not removed, start_pixel and end_pixel should be set to limit the average to the central portion of the pixel array, where vignetting effects are minimal.

Though this task was designed for GHRS calibration needs, there is nothing GHRS specific about the task.

ALGORITHM

The mean is calculated in an iterative method, to help minimize effects of features in the area of the spectra to be averaged. The parameters low_reject, high_reject, and iterations control this behavior. A mean and standard deviation is calculated for the range of pixels as specified by the start_pixel, end_pixel, center, and size parameters. Then, if low_reject and high_reject are defined and iterations is greater than 0, only those pixels whose flux satisfies the following condition are included in subsequent mean calculations:

	flux >= mean - (low_reject * deviation) AND
	flux <= mean + (high_reject * deviation)

A successful calculation is when a mean is determined which does not exclude any further pixels. If all iterations are executed and there were pixels removed in the last iteration, a warning is issued but the last calculated mean is output to the output table.

OUTPUT TABLE

The output table contains the following columns. The actual names of the columns are defined in the cfcolnames pset. The names used below are the suggested column names:

	'CARPOS' - Carrousel position.
	'ORDER'  - Spectral order, ("1" for first order
        	   gratings).
	'WLOW'   - First wavelength in the range averaged.
	'WHIGH'  - Last wavelength in the range averaged.
	'FLUX'   - Average count rate over the specified pixel range.
	'ERROR'  - The standard deviation of the mean.
	'NPTS'   - Number of data points averaged to obtain the
		   flux value.  This is a reference value, it is 
	           not used by any other task.

There are two header parameters added to the table:

	'GRATING'  - The grating represented by the contents of the
		     table.
	'APERTURE' - The aperture represetned by the contents of the
		     table.

The header parameters enforce that a table contain data relevant only to a specific grating and aperture. The values of these parameters come from the image header keywords GRATING and APERTURE. If these header keywords are not present in the input data, no check is made for consistency and a warning is issued.

INTERACTIVE MODE

In interactive mode, the user can graphically view the results of the mean calculation. There are two views available. The default view covers just the region of the spectrum that is averaged together. The mean is indicated by a solid line drawn across the graph. The standard deviation is indicated by the vertical error bar around the mean in the center of the graph. If points in this region have been rejected, those points are indicated by small crosses.

The second view, invoked by the f command, is the "full" view. Here, the whole spectrum is displayed. Again, the mean and standard deviation are indicated as above. Also, a horizontal bar, towards the bottom of the graph, indicates the region that is included in the average. No rejected pixels are indicated in this view.

The following single key stroke commands are available:

:: See below

?: The help file for the interactive mode of centerflux.

I: Discontinue interactive mode. The result for the current spectrum is used. If there are any more spectra to be processed, they will be calculated, using whatever modifications were made to the parameters up to this point. There is no way of getting back to interactive mode once left in this manner.

c: Redefine the center of the pixel region to be averaged to where the graphics cursor is located. Also see the "center" colon command below.

f: Toggle between the "full" view of the spectrum and the "restricted" view of just the region that is averaged.

p: Redefine the region which is averaged. To define a new region, move the graphics cursor to wherever the region should begin and hit p. To define the end of the region, move the cursor to where the region should end and hit p again. See also the "start" and "end" colon commands below.

q: Indicate that the current result is fine and continue on to the next spectrum.

r: Redraw the graph.

w: Toggle between wavelength and pixel coordinates. By default, the x-axis is plotted using the wavelength information from the wavelength file. Hitting w will switch to a pixel coordinate system and back.

The following colon commands available are:

center value: Display or set the center pixel. If no value is specified, the current center is displayed. If there is a value, it is taken as the pixel which to place the center of the region to be averaged. By default, center is INDEF, indicating to use whatever the center pixel of the current spectrum is. This value is written back to the "center" task parameter when the task is finished.

end value: Display or set the end pixel of the region. If no value is specified, this displays the current end pixel of the region. Note that both start and end positions must be specified in order for them to take effect. If not, the center and size parameters define the pixel region to be averaged. This value is written back to the "end_pixel" parameter when the task completes.

low_reject value: Display or set the low_reject sigma. This value is written back to the "low_reject" parameter when the task completes.

high_reject value: Display or set the high_reject sigma. This value is written back to the "high_reject" parameter when the task completes.

iterations value: Display or set the number of rejection iterations to perform. This value is written back to the "iterations" parameter when the task completes.

size value: Display or set the size of the region to average. This value is written back to the "size" parameter when the task completes.

start value: Display or set the start pixel of the region. If no value is specified, this displays the current start pixel of the region. Note that both start and end positions must be specified in order for them to take effect. If not, the center and size parameters define the pixel region to be averaged. This value is written back to the "start_pixel" parameter when the task completes.

PARAMETERS

input [file name template]: Names of the input data. If the input is in GEIS or multigroup format, each group will be operated on, unless a group specification is used.

output [file name]: Name of the output flux table produced by this task.

(wave = "") [file name template]: List of wavelength images corresponding to the images specified in input. If blank, the default extension, specified in the cfdefext pset, will be put on the current input file to find the wavelength file. If both the "wave" parameter and the "cfdefext.wave" parameter are blank, no wavelength information will be recorded in the table.

(mask = "") [file name template]: Optional data mask images corresponding to each image specified in input. This parameter can be used to delete spectral lines or bad data elements from the average. If no mask is specified, then all data is used. If blank, the default extension, specified in the cfdefext pset, will be appended to the input file name to find a mask file. If both the "mask" and "cfdefext.mask" parameters are blank, no mask images will be used.

(cfdefext = "") [pset]

This pset defines the default extensions that will be placed on the input, wavelength, and mask file names, if an extension is necessary. If the default extension is blank, no attempt is made to put one on the input file. The parameters are as follows:

(input_ext = "c1h") [string]: If the input file does not have an extension, this extension will be placed on it.

(wave_ext = "c0h") [string]: If no wavelength files are specified, then this extension will be placed on the input file name to create a wavelength file name. If blank and no wavelength files are specified, no wavelength files will be used.

(mask_ext = "") [string]: If no mask files are specified, then this extension will be placed on the input file name to create a mask file name. If blank and no mask files are specified, no mask files will be used.

(newtable = "yes") [boolean]: Create a new output table for the results? If newtable is set to "no", the results will be appended to an existing table. When appending data to an existing table, the appended data must have been obtained using the same grating mode and aperture as the existing data.

(start_pixel = INDEF) [integer, min=1]: First pixel in the range to be averaged. If INDEF, then center and size will be used to determine the pixel range. If the start pixel is modified while in interactive mode, the new start pixel will be written to this parameter.

(end_pixel = INDEF) [integer, min=1]: Last pixel in the range to be averaged. If INDEF, then center and size will be used to determine the pixel range. If the end pixel is modified while in interactive mode, the new end pixel will be written to this parameter.

(center = INDEF) [integer, min=1]: If start_pixel or end_pixel are not defined, this defines the center pixel of the range whose size is defined in size. If INDEF, the center pixel will be the center of the input image. If the center is modified while in interactive mode, the new center will be written to this parameter.

(size = 100) [integer, min=1]: The number of pixels to average centered on the pixel specified by center. If modified in interactive mode, the new value will be written to this parameter.

(iterations = INDEF) [integer, min=0]: The number of rejection iterations to perform. If 0, no rejection will occur. If modified in interactive mode, the new value will be written to this parameter.

(low_reject = 2.) [real, min=0.]: The number of sigma below the mean that a flux has to be before it is rejected. If INDEF, no lower cutoff is used. If modified in interactive mode, the new value will be written to this parameter.

(high_reject = 2.) [real, min=0.]: The number of isgma above the mean that a flux has to be before it is rejected. If INDEF, no upper cutoff is used. If modified in interactive mode, the new value will be written to this parameter.

(interactive = no) [boolean]: If "yes", the mean and range is plotted, giving the user an opportunity to interactively modify the mean fitting parameters.

(dvpar = "") [pset]: The graphics device parameters pset. See the help of "dvpar" for more information.

(cfcolnames = "") [pset]

The parameters that define the column names in the output table. The parameters are:

(carpos = "carpos") [string]: Name of the column containing carrousel positions.

(order = "order") [string]: Name of the column containing the spectral orders.

(wlow = "wlow") [string]: The name of the column containing the low wavelength of the regions averaged together.

(whigh = "whigh") [string]: The name of the column containing the high wavelength of the regions averaged together.

(flux = "flux") [string]: The name of the column containing the average flux.

(error = "error") [string]: Name of the column containing the standard devioations of the means.

(npts = "npts") [string]: Name of the column containing the number of pixels included in the average calculation.

EXAMPLES

1. Compute the center flux means for observation z0x20108m.

	cl> centerflux z0x20108m fluxtable

2. Computer the flux from pixel 50 to pixel 150 for all observations in the current directory.

	cl> centerflux *.c1h fluxtable start_pixel=50 end_pixel=150

3. Compute the center flux for all observations in the current directory, but without any wavelength files.

	cl> centerflux *.c1h fluxtable wave_ext=""

4. Append a single observation to an already existing table.

	cl> centerflux z0x20108m fluxtable newtable-