STScI Logo

echplot stsdas.hst_calib.stis



echplot -- Generate plots of STIS extracted spectral orders


echplot input output plotstyle


This task is an IRAF script which drives the echscript task. The echscript task generates an igi plotting script based upon the rows selected from the input STIS extracted spectral data table. Echplot will automatically invoke the generated igi script and plot the data to the chosen output device.

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 or a null (e.g., ""). If "output" is a null, this will trigger the "view only" mode and the graphics are automatically sent to the screen only. In this instance, the "device" parameter is forced to be "stdgraph" internally by the task. "View only" mode allows the user not only to view each plot, but also allows the user to have minimal interaction with each plot. In this mode if more than one page of graphics has been chosen, a graphics cursor is invoked. The main purpose of the graphics cursor for this task is to allow the user to "tab" through a series of requested graphics at their own pace. The added advantages of the "view only" mode are the capabilities offered; some of the available functions are (please note the case sensitivity):

    0 (zero)     reset and redraw
    =            same as for ":.snap" 
    P            zoom out (restore previous expansion)
    R            redraw the screen
    X            zoom in, X only
    Y            zoom in, Y only
    Z            zoom in, both X and Y       to obtain help on all the cursor functions
    q            "quit" this plot

Using the "q" key will effectively allow the tabbing through all of the requested orders. Please see the help page on cursor for more details on the functions available in cursor mode.

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, 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 "device" parameter allows the user to specify the output device for the plot. Please be aware this task flushes the graphics buffer for all devices except "stdgraph" after each "plotstyle" has completed.

The best looking plots are generated by setting "device" to PostScript output. The "single" and "multiple" plot styles were intended to be plotted in landscape mode; the "panel" and "diagnostic" plot styles are designed for portrait mode.

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 
    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 
   12      0001 0000 0000 0000    4096   Extracted flux affected by 
                                           bad data
   13      0010 0000 0000 0000    8192   Data rejected by cosmic ray 
   14      0100 0000 0000 0000   16384   Reserved


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. Alternatively, if this parameter is equal to a null (e.g., ""), then the task will enter "view only" mode, and all the graphics will be sent to the screen only. This mode allows the user a minimal level of interaction with each plot generated. No permanent output igi script will be written in this mode.
plotstyle [string, allowed values: s(ingle) | m(ultiple) | p(anel) |

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.
(device = "stdgraph") [string]
The output graphics device to use for the plot. If the "output" parameter is null, this parameter is forced to be "stdgraph" by the task.


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. Therefore, the full wavelength range of row 10 will plotted to the screen with a default title.

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

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", and the plot will be sent to "stdgraph" (screen).

   cl> echplot "input_x1d.fits[r:row=(3:4)]" out.igi m \
   >>> minwave=3010.0

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", and the plot is to be written to "stdplot".

   cl> echplot "input_x1d.fits[r:sporder=302]" m302.script single \
   >>> flux_col=net 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", and the plot is to be written as a PostScript file in portrait mode.

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

5. Select the "flux" data array (which is the default) from rows 2-4 and row 8 from the FITS table, "input_x1d.fits", to be plotted in "single" plot style in "view only" mode. Use "q" to "tab" through the plots on the screen.

   cl> echplot "input_x1d.fits[r:row=(2:4,8)]" "" s 


In "view only" mode, a temporary file is written to the user's tmp$ directory. If the task should fail prematurely, this file will not be deleted upon completion of the task. This file can be identified with the prefix "echView".


ECHPLOT V2.1 - Added "view only" mode. No permanent output igi script is generated. All graphics appear on the screen, and the user has some interactive capabilities.

ECHPLOT 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. Overwriting of the output igi script is allowed if the IRAF environment variable "clobber" is set to "yes".

ECHPLOT V1.0 - Original Implementation.


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


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


echscript, selectors, tlcol, igi, cursor

Search Form · STSDAS