Back to Programs

extract-spec

extract-spec uses a map file to extract 1 or 2-dimensional spectra from a set of 1 or 8 image files. In either case, spectra are first resampled onto a rectangular array of wavelength and slit position. The output data are stored as a set of image extensions in a  3- dimensional fits file, one spectrum per extension. The 3-d file consists of two planes, the first of which is the spectrum, and the second of which contains the 1-sigma errors of the spectrum, pixel by pixel. The output flux units are counts per angstrom-arc sec (along slit). If 1-d extraction is specified, an optimal extraction is performed on each 2-d spectrum, and the resulting spectra- cleaned of cosmic rays- are also stored as a set of 3-d image extensions, one per spectrum. Each plane- for spectrum and errors- is one pixel wide. The output flux units are counts per angstrom.

 extract-spec automatically handles nod&shuffle data. extract-spec can, optionally, search for and correct for offsets in the positions of spectra caused by misalignment of the slitmask on the sky, errors in object positions, and atmospheric dispersion.

 

USAGE	extract-spec -f framename -m mapfile
INPUT	framename is a set of image files from which the spectra are extracted mapfile is the map file which applies
OUTPUT	framename_1spec.fits or framename_2spec.fits
PARAMETERS	dimension dimension of extraction (1 or 2) deltalambda wavelength interval of extracted spectrum deltaslit slit position interval of extracted spectrum, in arc sec minlambda minimum wavelength of extracted spectrum maxlambda maximum wavelength of extracted spectrum search half-width of spectrum search region, in pixels trace trace method: "star" "object" or "none" trace_order order of fit to star spectrum trace align alignment method: "none", "star_ave", "obj_ave", or "obj_each" obj_frac brightest fraction of objects used in obj_ave alignment method init_off initial spectrum offset sub_ns subtract shuffled region of N&S data? sampling sampling interval type; "linear" or "log" use_holes extract alignment stars as well as objects? edge width, in pixels, of edge of spectrum excluded when extracting hwidth for 1-d extraction, half width, in pixels, of extraction region gain For 1-d extraction, CCD gain, in e-/adu

Details:

Data can be extracted in either linear or logarithmic intervals, depending on the value of the parameter sampling. If logarithmic, deltalambda is automatically converted to the sampling interval of base 10 logarithm in wavelength.

If minlambda and maxlambda are both set to 0, extract-2dspec uses the values from the map file.

If edge is set to a positive value, the spectrum is trimmed by edge pixels at the top and bottom of the slit. If edge is negative, extra pixels are extracted beyond the nominal ends of the slit.

The header of the first spectrum contains the following parameters:

SHUFFLED = does data included shuffled region?

NOD      = nod distance, in pixels (for N&S data)

D_SLIT   = interval along slit, in arc seconds

N_SLITS  = number of slits extracted

EXPTIME  = total exposure time of the spectrum

The headers of all spectra contain the following parameters:

DISPAXIS

CTYPE1

CTYPE2

WAT0_001

WAT1_001

WAT2_001

CRVAL1   = wavelength of first pixel

CDELT1   = wavelength interval of pixels

CD1_1    = wavelength interval of pixels 

CRPIX1   = starting pixel

DC-FLAG 

SLITTYPE

OBJECT   = object name, as defined in the SMF file for the mask

SLITNUM  = slit number in SMF file for the mask

2-d spectra contain the following additional lines

SLITLEN  = slit length, in pixels

CNTRLINE = the line in the 2-d spectrum centered on the object

 

Nod & shuffle data:

The shuffle region is extracted along with the primary slit region. If sub_ns is set to yes, it is then subtracted from the primary slit data. This should be done if multiple 2-d spectra are to be combined later, with cosmic ray removal, using sumspec, and is done by default if 1-d extraction is specified.

 

Correcting for positional errors:

A properly adjusted spectral map accurately predicts the loci of slit position and wavelength, but there may still be errors in the positions of objects along the slits, due to (1) errors in the alignment of the slitmask with the sky (2) errors in the positions of objects in the SMF catalog,  or (3) displacement of the spectrum along the slit with wavelength, due to atmospheric refraction. extract-2dsepec can, optionally, correct for some or all of these errors if the parameter search has a non-zero value.

• if trace is set to "star" or "object", an interval of search pixels above and below the expected spectrum location of all objects of the specified type plus the value of init_off is searched for the peak of the spectrum trace, the slit position as a function of wavelength is fit to a polynomial of order trace_order, and the data and fit plotted to the screen. Each trace fit can be accepted or rejected; all accepted traces are used to determine a mean curve of slit displacement vs wavelength, which is used to correct all spectra. Note that this curve is normalized to zero offset: only the shape of the trace is altered by this step, not its mean location along the slit.
• if align is not set to "none", an offset of the spectra along the slit is calculated (after correcting for spectrum curvature) and applied to each object, using a method which depends on the value of the parameter align:
• align = "star_ave": the average offset of the alignment stars is used
• align = "obj_ave": the average offset of the brightest obj_frac fraction of the objects is used.
• align = "both_ave": the average offset of the alignment stars and the brightest obj_frac fraction of the objects is used.
• align = "obj_each": the offset of each object is calculated individually and applied.
• if either the "star_ave" or "obj_ave" method is used:
• a plot is presented of the offsets of the objects used. Alignment stars are plotted in red, and objects in black. The user can either accept or reject application of the calculated offset; if the offset is accepted, it is applied to all objects and the data replotted.
• after the mean offset is applied, a mean rotation angle is calculated. Again, the user can either accept or reject application of the calculated rotation; if accepted,it is applied to all objects and the data replotted.
• if the "obj_each" method is used:
• a plot is presented of the offsets, ranked in order of their brightness (faint to left, bright to right). If the offsets appear to deteriorate fainter than some ranked value, that value can be specified; fainter objects are offset by the mean offset of the brighter objects.
• Note that you must have included the alignment stars in the map when you ran map-spectra if you want to use them in the alignment process.

 

It is recommended that the star trace method at least be tried for all data unless the alignment star data is inadequate; if there is no clear mean curvature of the spectra, application of the trace correction can be rejected. It is also recommended that at least the star_ave or obj_ave displacement correction be used. Particularly if many exposures are later to be added together using sumspec with cosmic ray rejection, it is important the the spectra be well-aligned. The use of the obj_obj_each method depends on adequate signal for each spectrum. Although the method used is fairly robust, it cannot align spectra with insufficient signal. Using objects for the spectrum curvature determination is recommended only if there are insufficient alignment stars and the objects are few and adequately bright.

1-d extraction

1-d extraction uses the optimal extraction method described in Horne (1986). Cosmic rays are automatically removed. One may use the entire length of the slit, but- if the total size of the objects is much smaller than the slit length, or if one is not interested in preserving the spectrophotometric information in the spectrum- noise can be somewhat reduced by setting a smaller extraction region using the parameter hwidth. If the spectra are bad near the slit ends, it is recommended to either use a smaller value of hwidth, or set the edge parameter to exclude the bad ends. If this entry is left blank, or set to a size larger than the half-length of the longest slit, the entire slit length is used. Positional error correction, as described above, is not needed if the entire slit length is used, but is advisable if a narrow extraction region is used.

If the spectra are quite weak on a single exposure, but multiple exposures are available, it may be preferable to first combine and CR-clean the 2-d spectra with sumspec, then do the 1-d extraction using the routine 1dspec.

 

Back to Programs