gnirsinfols -- Description of reduction scripts for longslit GNIRS spectroscopic data
gnirsinfols
The GNIRS package contains tasks for processing GNIRS long-slit, cross-dispersed and integral field spectroscopy data. Detailed descriptions of the individual tasks can be found in their help files. This document summarises the tasks and describes how they can be used to reduce longslit data.
The GNIRS package is also used by the NIRI and MIDIR packages to process long-slit NIRI, Michelle, and T-ReCS spectroscopy data.
The tasks produce logfiles of the performed processing steps. The name of the logfile may be set in each individual task, or at the package level by setting gnirs.logfile (niri.logfile or midir.logfile for NIRI or mid-IR data, respectively).
The tasks add header keywords to the output images. These header keywords contain valuable information about the performed processing steps and the values of the critical parameters that were used.
All GNIRS images are written as multi-extension FITS (MEF) files. Raw data have two unnamed extensions. Most of the header information is written to the primary header unit [0] (PHU). The detector array data is in extension [1]. After being processed with NSPREPARE, GNIRS data extensions will be named as described in GNIRSINFO.
It is recommended to use imtype="fits". This is set automatically when loading the GEMINI package.
- NSHEADERS - Prepare the GNIRS package for a particular instrument
This task is described in more detail in GNIRSINFO. It should be called before starting to work on data from a particular instrument.
- NSPREPARE - Prepare GNIRS data for reduction
This task is described in more detail in GNIRSINFO. It must be called before the other tasks listed below.
- NSREDUCE - Process GNIRS longslit images
NSREDUCE is used for basic reduction of raw longslit images - it provides a single interface for trimming (via nscut), flatfielding and sky-subtracting images. It also optionally calls nsappwave (fl_nsappwave+) and allows for the subtraction of dark frames.
Note that NSREDUCE will not call NSPREPARE.
- NSFLAT - Produce a normalized spectral flatfield
NSFLAT is used to produce a normalized spectral flatfield image. It is either used directly after NSPREPARE or, if the data are to be cut, after calling NSREDUCE or NSCUT on the nsprepare-d flat images. See the discussion on cutting data below.
- NSAPPWAVE - Determines a simple wavelength calibration
NSAPPWAVE provides a quick wavelength solution for GNIRS spectroscopic images. The wavelength solution is based on the header information and (by default) information in the table gnirs$data/nsappwave.fits (use the ttools package to examine this - ttools.tprint will display the contents - but add/delete entries or create a new table with the dedicated NSWEDIT task).
The task is for quick reduction purposes and to provide a starting point for the wavelength calibration derived by NSWAVELENGTH.
For longslit data the central wavelength will normally be calculated from the values of nsheaders.key_wave and nsheaders.key_waveorder so the entry in nsappwave.fits will be INDEF (although the dispersion will be defined in the table and used).
- NSWAVELENGTH - Establish an accurate wavelength calibration
NSWAVELENGTH is used to determine the wavelength solution for calibration lamp (or sky) images starting with the initial value supplied by NSAPPWAVE. This task can be run non-interactively, but often requires human intervention to get a sensible answer (see nswavelength help).
This task does not calibrate the data directly, but provides a database entry that can be used by NSFITCOORDS (described below).
- NSSDIST
NSSDIST measures the spatial distortion of the data on the detector using standard star or pinhole data. This is less critical for longslit data than for cross-dispersed, but it can be done if desired.
Like NSWAVELENGTH, this task does not calibrate the data directly, but provides a database entry that can be used by NSFITCOORDS(described below).
- NSFITCOORDS - Compute 2D dispersion and distortion maps
NSFITCOORDS uses the wavelength solution found by NSWAVELENGTH and/or the spatial correction found by NSSDIST to create coordinate fitting maps and adds them to the database directory and the output headers of each science extension.
- NSTRANSFORM - Rectify spectra
NSTRANSFORM applies the coordinate fitting maps calculated with NSFITCOORDS to images. The data are rectified and interpolated.
- NSEXTRACT - Extract GNIRS longslit or cross-dispersed spectra
NSEXTRACT extracts spectral images into one dimensional spectra, with a separate spectrum created for each input science extension. NSEXTRACT can be run either interactively or in batch mode, and it is possible to specify a reference spectrum whose trace is used to define the extraction aperture for faint objects.
NSPREPARE associates an MDF table with each data file. This table defines one or more areas on the detector which are expected to be illuminated for a given mode. For longslit observations this will be a single region defined by the slit length (for cross-dispersed and IFU data several regions are defined, one for each spectral order or image slice).
The extraction of these regions into separate extensions is done by the NSCUT task. Typically this is called from NSREDUCE, rather than directly, by setting the fl_cut parameter.
Most GNIRS package tasks have been written so that data can be processed before or after cutting the data into regions: NSREDUCE may be run more than once, so that some processing steps can be made before cutting and other after; and data can be processed uncut. However, cross-dispersed and IFU data are usually reduced as separate regions - neither the flat field generation nor the wavelength calibration are expected to work correctly for uncut data. Longslit data are usually processed cut, too, as it reduces the number of bad pixels in the frame.
In this document we give typical reduction procedures that cut the data as soon as possible. An actual .cl file with typical calls to the tasks is available from GNIRSEXAMPLES.
For typical reductions the user will need appropriate flat fields, arc (or sky) calibration images, and science images. Observations of spectrophotometric standard stars may also be required.
0. Use GEMTOOLS.GEMLIST to make separate lists of the files associated with different observation types. Typically these will be called obj.lis, arc.lis, star.lis. dark.lis, lamps.lis etc. Tasks can then be invoked on all the data of one type using iraf's "@" syntax. For example, NSPREPARE might be called with inimages=@obj.lis,@star.lis and then NSREDUCE with inimages=n@obj.lis (which prepends the letter "n" - nsprepare.outprefix - to each filename).
1. Use NSPREPARE to update the raw data headers and attach the mask definition file (MDF) as a binary table on all files. Note that dark frames will not have an MDF attached by default. Instead, the appropriate MDF is added in NSREDUCE or NSFLAT to match the data being reduced (the darks may be taken with a different telescope configuration, so the MDF from NSPREPARE, based on header information, would be incorrect).
If data are prepared in several separate calls to NSPREPARE, do not shift each batch separately. See the section "Using NSOFFSET to align the MDF" in the NSPREPARE help page for more details.
NSPREPARE can check (and correct) the WCS in the header, and apply a linearity correction to the data. Both of these steps are recommended.
NSPREPARE also creates variance and data quality planes that are maintained and updated throughout the processing (if fl_vardq=yes).
2. Use NSREDUCE or NSCUT to cut the lamps-on data to the size specified by the MDF (this assumes that we are going to process cut data and so need a flatfield that is also cut to the appropriate size - see the discussion on cutting data above).
3. Use NSFLAT to generate a flatfield from a stack of raw flat images. A bad pixel mask (BPM) will also be generated - this can be used to flag bad pixels in other data (in which case only process the lamps-on and dark frames in step 1 above and run NSPREPARE on all other data after this step).
4. If needed, check the object observation headers/images to determine the appropriate sky frames (e.g., for obj-sky dithering), or to find the desired time frame (skyrange) between observations. If the data are evenly spaced and one wants only the closest neighboring frame to be used for sky (e.g., for ABBA dithers), the default mode of NSREDUCE can be used. (See GNIRSINFO for more about sky subtraction.)
5. Use NSREDUCE to process the object data-- trim, flatfield, sky-subtract and apply an approximate wavelength solution, if desired. The default (skyrange = INDEF) is set to 50% larger than the time between observations, so that only immediately neighbouring frames are used for sky.
6. Either group by spatial offset and combine object observations using NSSTACK, or combine all object observations with shifting as required using NSCOMBINE.
7. Use NSWAVELENGTH to calibrate arc data (optionally they can be processed by NSREDUCE beforehand to apply the flatfield).
8. Optionally, measure spatial distortion using standard star or pinhole observations (NSREDUCE and then NSSDIST). This step may not be needed for long-slit data.
9. Use NSFITCOORDS to calculate coordinate maps using the wavelength calibration from NSWAVELENGTH and/or the spatial distortion from NSSDIST.
10. Use NSTRANSFORM to resample the combined object data to a uniform wavelength (and spatial, if step 8 was taken) scale.
11. Use NSEXTRACT to extract 1D spectra from the rectified data, if desired.
12. After the 2-D data are reduced (before or after NSEXTRACT), one will want to apply a telluric correction and, possibly a flux calibration. For the telluric correction NSTELLURIC can be used. For flux calibration, NSCALIBRATE is not yet available. However, the CALIBRATE IRAF task can be used directly on the science extension.
Example reduction scripts are available, see GNIRSEXAMPLES.
Support for variance and data quality handling is somewhat limited. This is partly due to poor support for variance and quality propagation in IRAF tasks. If error handling is required, please read the documentation for individual help tasks carefully and check results.
The tasks in the GNIRS package are designed to operate on MEF FITS images that have been processed using NSPREPARE (for GNIRS data), NPREPARE (NIRI data), MPREPARE (Michelle data) or TPREPARE (T-ReCS data).
For more information regarding the GNIRS data structure and for generic GNIRS package information, see GNIRSINFO. For more information about reducing cross-dispersed data, GNIRSINFOXD. For more information about the IFU tasks, see GNIRSINFOIFU.
gnirsinfo, gnirsinfoxd, gnirsinfoifu, gnirsexamples, nsflat, nsreduce, nsappwave, nswavelength, nstransform, nsextract, nprepare, nsprepare, nssdist, gemlist, mprepare, tprepare.