gnirsinfoxd -- Description of reduction scripts for cross-dispersed GNIRS spectroscopic data




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 cross-dispersed (XD) 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.

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. Processing with NSCUT will generate extensions for each cross-dispersed order. Each extension header contains information specific to that extension; for example, after running NSFITCOORDS on XD data the wavelength dispersion information is unique in each extension header.

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 cross-dispersed images

NSREDUCE is used for basic reduction of raw cross-dispersed images - it provides a single, unified interface for cutting (via nscut), flatfielding and sky-subtracting images. It also optionally calls nsappwave (fl_nsappwave+) and allows for the subtraction of dark frames.

For XD data, NSCUT will separate each XD order into a separate extension.

Note that NSREDUCE will not call NSPREPARE.

NSFLAT - Produce a normalized spectral flatfield

NSFLAT is used to produce a normalized spectral flatfield image. For XD data it is used after calling NSREDUCE or NSCUT. NSFLAT will not work properly on un-cut XD data; it requires each order to be in a separate extension.

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.

Note that gnirs$data/nsappwave.fits has a fixed central wavelength for each order of XD data. See NSAPPWAVE help.

For XD data the order parameter is usually defined in the MDF (the specorder column).

NSWAVELENGTH - Establish an accurate wavelength calibration

NSWAVELENGTH determines the wavelength solution for GNIRS 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 traces the location of the orders on the detector using standard star or pinhole data.

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.

For XD data the fl_stripe parameter is used to produce a reference wavelength image. This replaces all pixels at the same wavelength with the median value, generating a spatially-wide arc observation.

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.


For typical reductions the user will need appropriate flat fields, arc or sky calibration images, and science images. Observations of spectrophotometric standard stars or pinholes may also be required.

In addition to reading this description, the user is pointed to the GNIRSEXAMPLES for XD data. These are actual .cl files that contain typical calls to the tasks described here, with extensive comments.

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).

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 flats or pinhole data to the size specified by the MDF. Specify fl_corner+ so that overlapping orders are blanked out (this simplifies identifying apertures and removes confusing emission).

3. Use NSFLAT to generate a flatfields for all orders. A bad pixel mask (BPM) will also be generated - this can be used to flag bad pixels in other data. A star spectrum or pinhole data can be supplied via the trace parameter to help identify the curved aperture.

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 timeframe (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. Measure the spatial location of the orders using a pinhole observation or a stellar spectrum (NSREDUCE and then NSSDIST). The cross-dispersed orders in GNIRS do have curvature that varies by order, so s-distortion correction is important.

8. Use NSWAVELENGTH to calibrate arc data (after cutting and optionally applying a flatfield with NSREDUCE), supplying the spatial reference data from step 7 via the sdist parameter.

9. Use NSFITCOORDS to calculate coordinate maps using the wavelength calibration from NSWAVELENGTH and the spatial distortion from NSSDIST.

10. Use NSTRANSFORM to resample the combined object data to a uniform wavelength and spatial scale.

11. Use NSEXTRACT to extract 1D spectra from the rectified data, if required.

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 but it is difficult to use on cross-dispersed data. See the comment in the NSTELLURIC help page, under BUGS AND LIMITATIONS. NSCALIBRATE is not yet available. As an alternative, one can use the TELLURIC and CALIBRATE IRAF tasks directly on each 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) or NPREPARE (NIRI data).

For more information regarding the GNIRS data structure and for generic GNIRS package information, see GNIRSINFO. For more information about reducing longslit data, GNIRSINFOLS. For more information about the IFU tasks, see GNIRSINFOIFU.


gnirsinfo, gnirsinfols, gnirsinfoifu, gnirsexamples, nsflat, nsreduce, nsappwave, nswavelength, nstransform, nsextract, nsprepare, nssdist, gemlist.