----------
X-Sun-Data-Type: default
X-Sun-Data-Name: x1d.hlp
X-Sun-Charset: us-ascii
X-Sun-Content-Lines: 415
 
.help x1d Dec00 stis
.ih
NAME
x1d -- Extract collections of 1-D spectra from calibrated 2-D ACCUM images.
.ih
USAGE
.nf
x1d input output
.fi
.ih
PARAMETERS
.ls input [file name]
.ls input [file name]
Input calibrated file to be processed through x1d. A file name template
or "@"list can be supplied as well.
.le
.ls output [file name]
Name of output FITS file to contain binary table with extracted spectra.
If omitted, the name is constructed by replacing an existing suffix by,
or appending, the suffix "_x1d" to the input file name. If a list is
supplied for the 'input' parameter, 'output' can be a empty string
("") a matching "@"list or an IRAF name template that uses string
substitution.
.le
.ls (backcorr = "perform") [string]
Subtract background from the extracted spectrum ? This parameter is
ignored if optimal extraction is used.
.le
.ls (dispcorr = "perform") [string]
Assign wavelengths using dispersion coefficients from reference table ?
.le
.ls (helcorr = "perform") [string]
Correct wavelengths to a heliocentric reference frame ?  If set to PERFORM,
then 'dispcorr' should be set to PERFORM too in order for the correction to
take effect.
.le
.ls (fluxcorr = "perform") [string]
Convert raw counts to absolute flux units (erg /(cm^2 s A)) ?
.le
.ls (sporder = INDEF) [int]
Spectral order number to extract.
The default means that all orders should be extracted.
.le
.ls (a2center = INDEF) [real]
If 'sporder' is not INDEF, extract that order from line number 'center'.
This parameter is expressed in image coordinates.
.le
.ls (maxsrch = INDEF) [int]
Cross correlation range (in reference pixels), when searching in the
cross dispersion direction for the actual location of the spectrum.
If set to zero, this effectively turns off the cross correlation search.
The spectrum will then be extracted at the exact position defined by either
the A2CENTER value read from the XTRACTAB reference file, or the
'a2center' task parameter.
.le
.ls (globalx = no) [boolean]
Use global crosscor offset in all orders ?
.le
.ls (extrsize = INDEF) [real]
Size of extraction box, in reference pixels. This parameter is ignored
if optimal extraction is used.
.le
.ls (bk1size = INDEF) [real]
Size of first background region, in reference pixels.
.le
.ls (bk2size = INDEF) [real]
Size of second background region, in reference pixels.
.le
.ls (bk1offst = INDEF) [real]
Offset (center to center) of first background region, in reference pixels.
.le
.ls (bk2offst = INDEF) [real]
Offset (center to center) of second background region, in reference pixels.
.le
.ls (bktilt = INDEF) [real]
Background tilt, in degrees.
.le
.ls (backord = INDEF) [int]
Background order.
.le
.ls (algorithm = "unweighted") [string]
Extraction algorithm.
Possible values: "unweighted",
"sc2d" (IDT's deconvolution algorithm).
.le
.ls (verbose = no) [boolean]
Print additional verbose messages and time stamps.
.le
.ih
DESCRIPTION
Task 'x1d' performs 1-D spectral extraction on ACCUM spectroscopic
calibrated data. The task is most appropriate for echelle data and for a
long-slit obseravtion of a point source. A spectrum is extracted along a
narrow band, summing in the cross-dispersion direction and subtracting nearby
background values to produce a 1-D array of fluxes for each spectral order.
The data is not resampled in the dispersion direction; instead, an array of
wavelengths is generated. Each output spectrum is written to a separate row of
a FITS binary table, together with the wavelength and background arrays.
The task supports both unweighted and optimal extractions.
 
INPUT IMAGES AND OUTPUT TABLES/IMAGES
 
The input image to this task should be a full calibrated spectroscopic image
(i.e. flatfielded and cosmic-ray rejected if applicable) that has been
proccessed through BASIC2D and/or CRREJECT. The input file should consist
of one or more STIS IMSETs. Each IMSET is comprised of: science
(EXTNAME=SCI), error (ERR), and data  quality (DQ) FITS extensions.
 
The main output file is a FITS binary table, with a primary header
(with no data) and one FITS table extension for each IMSET in the input
file.
 
The output table format consists of 17 columns that
store information for a complete extracted spectral order at each row. Some
columns store a single scalar quantity at each row, other columns store a
full 1-dimensional array at each row. All image coordinate values are 
expressed in image pixels. The columns of the output table are:

.ls SPORDER
Spectral order for the spectrum corresponding to the current row.
.le
.ls NELEM
Number of array elements for the array columns in the table.
Each array column store at each row an array of size NELEM.
.le
.ls WAVELENGTH
Array with wavelength values corresponding to each pixel position
along the dispersion axis. If 'dispcorr' and 'helcorr' were set to
PERFORM in the input parameters, then these wavelengths will be
heliocentric corrected.
.le
.ls GROSS
Array with gross count rate at each pixel position along the dispersion
axis.
.le
.ls BACKGROUND
Array with background count rate at each pixel position along the
dispersion axis.
.le
.ls NET
Array with net count rate at each pixel position along the dispersion axis.
.le
.ls FLUX
Array with absolute fluxes at each pixel position along the dispersion
axis. Will have actual values if 'fluxcorr' was set to PERFORM in the
input parameters.
.le
.ls ERROR
Array with errors associated with the absolute flux values. If 'fluxcorr'
was set to OMIT, the errors will be associated with the NET or GROSS count
rates instead, depending if background subtraction was performed or not.
.le
.ls DQ
Array with data quality flags. The data quality value for any pixel in an
extracted 1-D spectrum is the "or-ed" value of all data quality values
that were used to produce the given pixel.
.le
.ls A2CENTER
Default or user specified y extraction location.
.le
.ls EXTRSIZE
Size of extraction aperture.
.le
.ls MAXSRCH
Search radius for cross correlation location of extracted spectrum.
.le
.ls BK1SIZE
Size of background box 1.
.le
.ls BK2SIZE
Size of background box 2.
.le
.ls BK1OFFST
Offset of background box 1 (center to center).
.le
.ls BK2OFFST
Offset of background box 2 (center to center).
.le
.ls EXTRLOCY
Array with pixel position where the spectrum was extracted (the center
of the extraction box).
.le
.ls OFFSET
Offset (in the cross-dispersion direction) from the nominal extraction
position, where the extraction actually took place. This is reported
in image (not reference) pixel units.
.le
 
REFERENCE FILES and PROCESSING STEPS
 
The names of the reference files (images and tables) to be used by X1D
have to be specified in the primary header of the input image, under the
section CALIBRATION REFRENCE FILES.
 
When an environment variable is used as part of a reference file name
(e.g. "oref" in PFLTFILE = "oref$h230851ao_pfl.fits"),
the variable must have been set (in Unix)
before logging into IRAF,
and the directory name must include the trailing "/".
Setting an IRAF environment variable will not work,
nor will using ! to escape from the cl.
For example,
 
.nf
    setenv oref /data/reffiles/stdata/
 
    # if the reference files are in the default directory, use
    setenv oref ./
.fi
 
The following files are needed to perform
1-D spectral extraction:
.ls One-D Spectrum Trace Table (1DT)
Consists of displacements of spectra along Axis 2 for determining the location
of a spectrum prior to extracting the 1-D spectrum. The name of the 1-D
spectrum table file must be provided in the keyword SPTRCTAB.
.le
.ls 1-D Extraction Parameter Table (1DX)
Describes the extraction apertures (or `boxes') and methods used in the
extraction of 1-D spectra. The name of the 1-D extraction table must be
provided in the keyword XTRACTAB.
.le
.ls Dispersion Coefficients Table (DSP)
Consists of the coefficients to the nominal dispersion solution to be applied
to extracted 1-D spectra. The name of the dispersion table must be provided
in the keyword DISPTAB.
.le
.ls Incidence Angle Correction Table (IAC)
Contains coefficients to fits of the change in two dispersion coefficients
(the zero-point and the first-order terms) as a function of angular offset
from the reference position. These corrections are applied to the default
dispersion coefficients. The name of the incidence angle table file must be
provided in the keyword INANGTAB.
.le
.ls Aperture Description Table (APD)
Contains the geometric description of the apertures, and their offsets (in
arcseconds) from a reference aperture. The name of the aperture description
table file must be provided in the keyword APDESTAB.
.le
.ls MAMA Offset Correction Table (MOC)
Ccontains coefficients to fits of the change in the dispersion coefficients as
a function of commanded offset from the reference position. These corrections
are applied to the default dispersion coefficients. This is valid for MAMA
observations only.
.le
.ls Aperture Throughput Table (APT)
Consists of wavelength dependent transmissions for each aperture with respect
to a reference aperture. This table is used in conjunction with PHOTTAB to
convert observed counts to absolute flux. The name of the aperture throughput
table file must be provided in the keyword APERTAB.
.le
.ls Photometric Conversion Table (PHT)
Contains the throughput of the instrument configuration as a function of
wavelength assuming an infinite aperture centered on the detector. The table
contains the photometric correction for a point source. Effects such as
vignetting and echelle blaze function are folded into this table. The name of
the photometric table must be provided in the keyword PHOTTAB.
.le
 
If all the input switches are set to OMIT, then only a spectral extraction
will be performed without any of the corrections/conversions that apply to
each input parameter. For a complete explanation of the algorithm behind
X1D refer to STIS ISR 97-02 'The STScI STIS Pipeline VII: Extraction of 1-D
Spectra', by S. Hulbert et al, February 1997. Note that since this ISR document
was written, slightly modifications have been made to X1D. However, the
algorithm and the input parameters explanations are still valid.
 
.ih
EXAMPLES
 
1. To extract the spectra on an echelle FUV MAMA observation in the data set
with rootname "o3s41301o" that has been previously 2-D calibrated.
Apply all the corrections/conversions available.
The reference files are in the directory "/data/reffiles/stdata/".
Note that we must have assigned oref as an environment variable in Unix
before starting the cl, and the value must include the trailing "/".
.nf
 
      cl> show oref
      /data/reffiles/stdata/
      cl> x1d o3s41301o_flt.fits o3s41301o_x1d.fits backcorr="perform" \
          dispcorr="perform" helcorr="perform"  fluxcorr="perform"
 
.fi
 
2. Example of use of the columns with extraction information:
one extracts the spectra as above, and then uses task 'sgraph' to read the
appropriate column and overplot the extraction box center positions on the
image display. Notice that the image size (2048X2048) must be explictly
entered into 'sgraph' parameters for the overplotting to work.
 
.nf
     st> x1d o3s41301o_flt.fits o3s41301o_x1d.fits
     st> imheader o3s41301o_flt.fits[SCI,1]
     o3s41301o_flt.fits[SCI,1][2048,2048][real]
     st> display o3s41301o_flt.fits[SCI,1] 1 fill+
     st> sgraph "o3s41301o_x1d.fits[r:row=1] EXTRLOCY" \
         dvpar.device="imdr" pltpar.pointmode+ pltpar.marker="point" \
         axispar.wl=1 axispar.wr=2048 \
         axispar.wb=1 axispar.wt=2048 axispar.box-
.fi
.ih
BUGS
.ih
REFERENCES
.nf
STIS ISR 97-02, Hulbert et al., February 1997.
ICD47, R. Shaw, April 1997.
P. Hodge, March 1997, short memo.
Iraf task written by R. Katsanis.
X1D routines written by I. Busko.
.fi
.ih
SEE ALSO
 calstis
.endhelp