STScI Logo

echscript stsdas.hst_calib.stis


NAME · USAGE_ · DESCRIPTION · PARAMETERS · EXAMPLES · BUGS
REVISIONS · REFERENCES · HELP · SEE_ALSO

NAME

echscript -- Generate an igi script for selected STIS extracted data

USAGE

echscript input output plotstyle

DESCRIPTION

The echscript task generates an igi plotting script based upon the rows selected from the input STIS extracted spectral data table. This script can then be used to generate a plot on a selected output device by invoking the igi package. Alternatively, the echplot task generates an igi script and sends the output plot to the specified device in one streamlined task. The echplot task is actually an IRAF script which acts as a driver for this task and the igi package.

The input is a STIS 3D FITS binary table. The rows are selected by appending the appropriate row selector syntax to the table name. Type 'help selectors' to get more information on row selector syntax.

The output is the name of the igi script. If the "viewonly" parameter is set to "yes", then the output igi script will contain commands which are meant for use ONLY with graphics sent to the user's screen. When "viewonly = yes", the output igi script should ONLY be used for viewing the plots on the screen. If this script is sent to another device (i.e., a printer), a jam or error may occur. "Viewonly = yes" will invoke the cursor mode which allows the user some level of interaction with the graphics. Please see the help page on cursor for details on the available functionality.

There are four plot styles implemented: s(ingle) - one plot per page for each spectral order, m(ultiple) - all the selected spectral orders on one plot on a page, and p(anel) - a plot for each selected spectral order, four plots to a page, and d(iagnostic) - all the data arrays (gross, background, net, flux, error, and dq) for a specified order are plotted in a multi-panel plot on one page.

The parameter "flux_col" can be used to specify by name the particular STIS data array to be plotted. The tlcol task can be used to identify the names of the table columns. By default, the calibrated flux is plotted. The columns which are assumed to be present in the STIS 3D FITS binary table and which are utilized by this task are: SPORDER, NELEM, WAVELENGTH, GROSS, BACKGROUND, NET, FLUX, ERROR, and DQ.

The optional parameter "title" can be used to specify a title for the plots. The default title consists of the instrument name, rootname of the observation, detector, central wavelength, optical element, and aperture. For "single" and "panel" plotting modes, the spectral order number is also included in the title.

For "single" and "multiple" plotting modes only, the minimum and/or maximum wavelength can be specified via the "minwave" and "maxwave" parameters. If the parameter value is zero, the particular wavelength limit is computed in realtime.

The DQ spectrum is an array of bit-encoded values. Each value is the unique sum of individual bit settings, and each bit represents a particular data quality condition. In the "diagnostic" plot style, the composite DQ value is decomposed for each wavelength bin into its constituent error conditions (bit settings) and displayed as discrete symbols. In this way, all the data quality conditions which are appropriate to a single wavelength bin can be displayed. The y-axis of the DQ plot is the bit position. The following table illustrates the correspondence of the DQ bit position, bit setting, flag value, and a description. Please see the HST Data Handbook - Volume 1: Current Instruments, Version 3, October 1997 for details on the STIS DQ flags.

 Bit       Bit                   Flag    Condition
 Position  Setting               Value
    0      0000 0000 0000 0001       1   Reed Solomon decoding error
    1      0000 0000 0000 0010       2   Lost data replaced by fill 
                                           values
    2      0000 0000 0000 0100       4   Bad detector pixel
    3      0000 0000 0000 1000       8   Data masked by occulting bar
    4      0000 0000 0001 0000      16   Pixel dark rate > 5 sigma 
                                           times median dark level
    5      0000 0000 0010 0000      32   Large blemish
    6      0000 0000 0100 0000      64   Reserved
    7      0000 0000 1000 0000     128   Reserved
    8      0000 0001 0000 0000     256   Saturated pixel
    9      0000 0010 0000 0000     512   Bad pixel in reference file
   10      0000 0100 0000 0000    1024   Small blemish
   11      0000 1000 0000 0000    2048   >30% background pixels 
                                           rejected
   12      0001 0000 0000 0000    4096   Extracted flux affected by 
                                           bad data
   13      0010 0000 0000 0000    8192   Data rejected by cosmic ray 
                                           rejection
   14      0100 0000 0000 0000   16384   Reserved

PARAMETERS

input [file name]
The STIS 3D binary FITS table which contains extracted spectral data.
output [file name]
Ascii output file which contains the igi commands to generate a plot. If "viewonly = yes", then the output igi file will contain commands which are designed to be used only when plotting to the screen.
plotstyle [string, allowed values: s(ingle) | m(ultiple) | p(anel) |
d(iagnostic)]

The selected output plot style. The "single" style generates one plot per page for each spectral order; "multiple" style plots all the selected spectral orders in one plot on a page; the "panel" style generates a plot for each selected spectral order, four plots to a page; the "diagnostic" style plots all data arrays associated with a specified order in a multi-panel plot on one page.

(flux_col = "flux") [string]
The name of the table column containing the intensity data to be plotted. The default is "flux".
(title = "") [string]
An optional input title. If this parameter is empty, the default title will be applied.
(minwave = 0.) [real, min = 0.]
For "single" and "multiple" plot styles only, the minimum wavelength to plot.
(maxwave = 0.) [real, min = 0.]
For "single" and "multiple" plot styles only, the maximum wavelength to plot.
(viewonly = no) [boolean]
If the "viewonly" parameter is set to "yes", this will cause the output igi script to contain commands which are designed for use only with the user's screen. "Viewonly = yes" will invoke cursor mode which allows the user some level of interaction with the graphics.

EXAMPLES

1. Select the "flux" data array from row 10 of the FITS table, "input_x1d.fits", to be plotted in "single" plot style. The output igi script is named "s10.igi". In this example, the default values are being used for all of the hidden parameters. Once the script is generated, plot the script to the screen.

   cl> echscript "input_x1d.fits[r:row=10]" s10.igi s
   cl> igi < s10.igi

2. Select the "flux" data array from rows 3 & 4 of the FITS table, "input_x1d.fits", to be plotted in "multiple" plot style with a user specified minimum wavelength. The output igi script is called "out.igi". Once the script is generated, plot the script to a PostScript file in landscape mode.

   cl> echscript "input_x1d.fits[r:row=(3:4)]" out.igi m \
   >>> minwave=3010.0
   cl> igi < out.igi device=psi_land
   cl> gflush

3. Select the "net" data array from the row containing the spectral order 302 from the FITS table, "input_x1d.fits", to be plotted in "single" plot style. The output igi script is called "m302.script". Once the script is generated, plot the script to "stdplot".

   cl> echplot "input_x1d.fits[r:sporder=302]" m302.script single \
   >>> flux_col=net
   cl> igi < m302.single device=stdplot

4. Select the "gross" data array from rows 2-4, and 8 from the FITS table, "input_x1d.fits", to be plotted in "panel" plot style with a user specified "title". The output igi script is called "out.igi". Once the script is generated, plot the script to a PostScript file in landscape mode.

   cl> echplot "input_x1d.fits[r:row=(2:4,8)]" out.igi p \
   >>> flux_col=gross title="My Title"
   cl> igi < out.igi device=psi_land
   cl> gflush

5. Select the "flux" data array from rows 10 through 20 of the FITS table, "input_x1d.fits", to be plotted in "single" plot style. The output igi script is named "s10.igi" and is to be used for plotting to the screen only.

   cl> echscript "input_x1d.fits[r:row=(10:20)]" s10.igi s viewonly+

BUGS

REVISIONS

ECHSCRIPT V2.2 - Added "viewonly" mode.

ECHSCRIPT V2.1 - Cleaned up C-binding interface.

ECHSCRIPT V2.0 - Added the "diagnostic" plot style. Default values for minwave/maxwave are INDEF; for backwards compatibility, the main program treats INDEF and 0.0 in the same manner. The "single" plot mode now allows setting of the minwave/maxwave. The STScI address has been removed from the plots. The plot annotation has been corrected to be singular (i.e., count s-1 rather than counts s-1). Annotation has been added to the output IGI scripts for readability.

ECHSCRIPT V1.0 - Original Implementation.

REFERENCES

This task was written by M.D. De La Pena, SSG.

HELP

For assistance using this or any other tasks, please contact help@stsci.edu or call the help desk at 410-338-1082.

SEE ALSO

echplot, selectors, tlcol, igi, cursor


Search Form · STSDAS