Personal tools
You are here: Home / COSMOS / extract-2dspec


Back to Programs


extract-2dspec uses a map file to extract 2-dimensional spectra from a set of image files. Spectra are extracted onto a rectangular array of wavelength and slit position. 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. extract-2dspec automatically handles nod&shuffle; data. extract-2dspec can, optionally, search for and correct for offsets in the positions of spectra caused by misalignment of the slitmask on the sky, or by errors in object positions.

USAGEextract-2dspec -f framename -m mapfile
framename is a set of image files from which the spectra are extracted
mapfile is the map file which applies
deltalambdawavelength interval of extracted spectrum
deltaslitslit position interval of extracted spectrum, in arc sec
minlambdaminimum wavelength of extracted spectrum
maxlambdamaximum wavelength of extracted spectrum
telscaletelescope scale arc sec/mm
searchhalf-width of spectrum search region, in pixels
tracetrace method: "star" "object" or "none"
trace_orderorder of fit to star spectrum trace
alignalignment method: "none", "star_ave", "obj_ave", or "obj_each"
obj_fracbrightest fraction of objects used in obj_ave alignment method
init_offinitial spectrum offset
sub_nssubtract shuffled region of N&S; data?
samplingsampling interval type; "linear" or "log"
use_holesextract alignment stars as well as objects?
edgewidth, in pixels, of edge of spectrum excluded when extracting


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:

CRVAL1   = wavelength of first pixel
CDELT1   = wavelength interval of pixels
CD1_1    = wavelength interval of pixels 
CRPIX1   = starting pixel
SLITLEN  = slit length, in pixels
CNTRLINE = the line in the 2-d spectrum centered on the object
OBJECT   = object name, as defined in the SMF file for the mask
SLITNUM  = slit number in SMF file for the mask

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.

Correcting for positional errors:

The 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, (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.

Back to Programs