gfreduce

gfreduce (July2009)

gemini.gmos

gfreduce (July2009)

gfreduce

NAME

gfreduce -- Apply processing steps to GMOS IFU data

PARAMETERS

Other tasks within the Gemini IRAF package which are affected by a given parameter are given in ().

inimages: List of raw GMOS IFU images to process. Can be a list of images. Wild cards are supported. The image names may include the directory path. The images must be in multi-extension FITS (MEF) format.

outimages = "": Output MEF images. The parameter can be one single image name, a list of images or a list file; as long as the number of output images matches the number of input images. outimages has precedence over outpref.

outpref = "default": Prefix added to inimages to make output image name if outimage not given. Setting this to "default" will cause each processing step to use its default output prefix.

slits = "header" (red|blue|both|header): The IFU slit(s) used during the observations. This is used for selecting the proper MDF file if mdffile="default". If slits="header", the MDF file is selected automatically based on the IFU configuration indicated in newer headers. For older data with MASKNAME="IFU" in the header, the slit must still be specified explicitly.

exslits = "*" (red|blue|*): Slit(s) to extract (* for the slit(s) defined in the MDF). For 2-slit mode, this option allows each slit to be extracted separately over its full, clean spectral range, instead of just the range common to both slits. This splits the IFU field in two, but allows for non-standard grating and filter configurations. Any overlap between slits is still removed unless fl_novlap=no. This parameter should only be used when center of filter does not match desired central wavelength. This only occurs in extreme cases.

fl_nodshuffle = no: Set to yes if using one of the nod&shuffle output slit masks. Help helps determine the proper MDF to use if mdffile="default".

fl_inter = yes: Flag for interactive use.

fl_vardq = no: Create or propagate the variance and data quality planes? If fl_vardq=no, no variance and data quality planes will be created or propagated. If the images are raw, these planes will be created first with GIREDUCE only if bias subtracting.

fl_addmdf = yes: Add mask definition file. Required for further processing with the GMOS IFU tasks. (GPREPARE)

fl_over = no: Apply overscan correction (GIREDUCE).

fl_trim = yes: Trim the overscan region (GIREDUCE).

fl_bias = yes: Subtract bias image (GIREDUCE).

fl_gscrrej = yes: Clean the images for cosmic rays by calling GSCRREJ.

fl_gnsskysub = no: Subtract sky from nod&shuffle images using GNSSKYSUB.

fl_extract = yes: Extract the spectra by calling GFEXTRACT.

fl_gsappwave = yes: Run GSAPPWAVE after the extraction (GFEXTRACT).

fl_wavtran = yes: Apply a wavelength calibration solution by calling GFTRANSFORM.

fl_skysub = yes: Compute and subtract a mean sky spectrum by calling GFSKYSUB. Do not set this if subtracting sky with fl_gnsskysub.

fl_fluxcal = yes: Apply a flux calibration by calling GSCALIBRATE.

rawpath = "": Path for the directory containing the raw GMOS images (GPREPARE).

key_mdf = "": Header keyword containing the name of the MDF file. If key_mdf="" and fl_addmdf=yes, then the MDF file given by mdffile will be written to the keyword MASKNAME (GPREPARE).

mdffile = "default": The name of the MDF to add to the MEF. If "default", then GFREDUCE uses slits to pick the standard MDF file for that configuration. Using the default is highly recommended unless the observations use nod&shuffle (GPREPARE).

mdfdir = "gmos$data/": Directory containing mdffile (GPREPARE).

key_biassec = "BIASSEC": Header keyword for the overscan section (GIREDUCE).

key_datasec = "DATASEC": Header keyword for the usable, data section (GIREDUCE).

bpmfile = "gmos$data/chipgaps.dat": Bad pixel mask used by GMOSAIC to interpolate across the chip gaps (GFEXTRACT).

bias = "": Bias image to be subtracted (GIREDUCE). The bias image bias should be created using the GBIAS task.

reference = "": Name of the reference file to use for defining apertures and traces (GFEXTRACT).

response = "": Name of the lenslet/fiber throughput file generated by GFRESPONSE (GFEXTRACT).

wavtraname = "": List of lamp image root names (do not include .fits in the name) that were used to establish the wavelength calibration with GSWAVELENGTH (GFTRANSFORM).

sfunction = "": Name of the sensitivity function (flux calibration) generated by GSCALIBRATE (GSCALIBRATE).

extinction = "": Name of the file containing the atmospheric extinction curve. If this file exists and fl_fluxcal=yes, then it is used by GSCALIBRATE.

fl_fixnc = no: Auto-correct for nod count mismatch in nod&shuffle observations (GNSSKYSUB).

fl_novlap = yes: In two-slit mode, extract only non-overlapping sections of spectra from each slit (no overlap). If fl_novlap=no then the entire length of each slit allowed by the filter is extracted, regardless of overlap (GFEXTRACT).

perovlap = 10.: If fl_novlap=yes, then the calculated lengths of the spectra are shortened by this percentage to minimize any remaining overlap (GFEXTRACT).

nbiascontam = 4: Number of columns removed from the overscan region before subtracting. Used when fl_over=yes. The overscan region of GMOS CCDS has some photon bleeding from science frame. nbiascontam is the number of pixels next to science frame that are not used as overscan.

biasrows = 'default': Rows to use in bias region. If biasrows = 'default, the entire length of overscan region is used. Value must be of the form "x1:x2" where x1 is the starting pixel row and x2 is the final pixel row. e.g. "3:64"

order = 1: Order of the overscan fitting function (GIREDUCE).

low_reject = 3.0, high_reject = 3.0: Low and high sigma rejection factor in overscan fitting.

niterate = 2: Maximum number of rejection iterations in overscan fitting.

line = INDEF: Column used for finding apertures. If INDEF then the center of the spectrum is used (GFEXTRACT).

nsum = 10: The number of columns summed for finding apertures (GFEXTRACT).

trace = yes: Trace spectra (GFEXTRACT).

recenter = yes: Recenter apertures (GFEXTRACT).

function = "chebyshev" (chebyshev|spline1|spline3|legendre): Function to be used for fitting the trace (GFEXTRACT).

t_order = 5: Order for the trace fit (GFEXTRACT).

t_nsum = 10: The number of dispersion lines to sum for the trace (GFEXTRACT).

thresh = 200.: Detection threshold for profile centering (GFEXTRACT).

weights = "variance" (variance|none): Weighting used during extraction (GFEXTRACT). It is recommended to use weights="variance" for science and flat fields, and weights="none" for arcs.

gratingdb = "gmos$data/GMOSgratings.dat": Database file with GMOS grating information (GFEXTRACT).

filterdb = "gmos$data/GMOSfilters.dat": Database file with GMOS filter information (GFEXTRACT).

xoffset = INDEF: The offset in the X (wavelength) direction between the theoretically predicted position of the spectra and the actual position. The units are nanometers. This overrides the offset value in gratingdb if it is not equal to INDEF.

expr = "default": Logical TSELECT expression for selecting sky lenslets. The default values assume that the entire small IFU field is used for determining sky: 'XINST > 10' for GMOS-N and 'XINST < 10' for GMOS-S (GFSKYSUB).

observatory = "default": The name of the Gemini telescope used for the observations based on the INSTRUME header keyword (GSCALIBRATE).

sci_ext = "SCI": Name of the MEF extension containing the science data.

var_ext = "VAR": Name of the MEF extensions containing the variance frame.

dq_ext = "DQ": Name of the MEF extensions containing the data quality array.

logfile = "": Name of the logfile. The default value makes the task use the logfile defined by gmos.logfile.

verbose = yes: Print actions to the screen or run quietly.

status = 0: Exit status will be non-zero if the procedure halted with an error. This parameter is always set by the task, and should not be modified by the user.

GFREDUCE is a meta script for applying basic reduction steps to GMOS IFU data. Depending on the flags set, GFREDUCE will call the following scripts in sequence: GPREPARE, GIREDUCE, GSCRREJ, GNSSKYSUB, GFEXTRACT, GFTRANSFORM, GFSKYSUB, and GSCALIBRATE. The most important of the parameters of these tasks, especially the names of calibration files, are provided as inputs to GFREDUCE. If a parameter for one of the called tasks is not in the GFREDUCE parameter list and does not involve file names, then in general it can be set directly before GFREDUCE is run (see the examples). The intermediate results are named using the default outpref where possible. Output from GSCRREJ is given a "x" prefix. While it is best to use the standard prefixes for the output file names, the final result can be renamed according to the list given in outimages or a specfic prefix given by outpref.

Intermediate steps are not deleted - the output images may therefore take up significant disk space. The intermediate steps can only be reused if the flags that were set to "yes" to create them are set to "no" and the names of the output image(s) from the intermediate step is given as the input image(s). For example to start at the cosmic ray rejection step, set fl_addmdf=no and all the flats for GIREDUCE to "no". Then give the output image from those steps as the input image. This image is named "rg*" if the default naming was used. This behavior of GFREDUCE will be improved in a future release.

GFREDUCE does provide some functionality in addition to that of the scripts that it links together. If slits is set to the correct slit(s), fl_nodshuffle reflects whether a nod&shuffle slit mask was used, and mdffile="default" (or if slits="header" for newer data), the proper MDF file for that configuration is determined automatically. In this case, mdfdir should be set to the default value of "gmos$data/". Also, GFREDUCE puts loops around GSCRREJ and GFEXTRACT, allowing those tasks to be used on lists of images. Finally, it makes sure that database files are renamed and updated properly if the output images do not use the standard prefixes.

The field-to-slit mapping of the GMOS-S IFU allows the use of the nod&shuffle (N&S) observing mode for improved sky subtraction, especially in the red. One difference when using this mode is the loss of the small IFU field normally used for a sky measurement. Sky subtraction for N&S data can be done in two ways. GNSSKYSUB can be called by setting fl_gnsskysub="yes" (fl_skysub is set to "no" automatically if a N&S output mask was used). If data were taken at multiple DTA X positions but the same spatial position then images can be combined and the sky can be subtracted using GNSCOMBINE. In this case the spectra should be gprepared, bias-subtracted, and processed by GNSCOMBINE before running GFREDUCE to do the extraction.

After processing with GFREDUCE the data format will have changed according to the processing steps chosen. The tables below give the processing flags and the output data format in terms of the number of science extensions (SCI) and the MDF extension. The MDF extension contains the binary MDF. The flags are listed in the order the reflects the reduction steps. The output format of one step is the input format to the next step. The first table is for data taken with the IFU in 1-slit mode, while the second table is for data taken with the IFU in 2-slit mode. For N&S reductions there is no SKY extension since the sky is subtracted using GNSSKYSUB or GNSCOMBINE before the extraction step and no mean sky spectrum is produced.

IFU 1-slit data -------------------------------------------------- Processing flag Output format -------------------------------------------------- none Raw data: 3 image extensions fl_addmdf+ 3 SCI 1 MDF fl_over+ 3 SCI 1 MDF fl_bias+ 3 SCI 1 MDF fl_crrej+ 3 SCI 1 MDF fl_extract+ 1 SCI 1 MDF fl_gsappwave+ 1 SCI 1 MDF fl_wavtran+ 1 SCI 1 MDF fl_skysub+ 1 SCI 1 MDF 1 SKY fl_fluxcal+ 1 SCI 1 MDF 1 SKY --------------------------------------------------

IFU 2-slit data -------------------------------------------------- Processing flag Output format -------------------------------------------------- none Raw data: 3 image extensions fl_addmdf+ 3 SCI 1 MDF fl_over+ 3 SCI 1 MDF fl_bias+ 3 SCI 1 MDF fl_crrej+ 3 SCI 1 MDF fl_extract+ 2 SCI 1 MDF fl_gsappwave+ 2 SCI 1 MDF fl_wavtran+ 1 SCI 1 MDF fl_skysub+ 1 SCI 1 MDF 1 SKY fl_fluxcal+ 1 SCI 1 MDF 1 SKY --------------------------------------------------

After processing with GFREDUCE, science images may be reconstructed using GFDISPLAY, or resampled onto a 3-D datacube using GFCUBE.

EXAMPLES

1. Do all steps through extraction for a GCAL flat.

	cl> set rdata=/net/mapu/staging/gmos/
	cl> set gcalib=/net/mapu/staging/dataproc/gmos/CommCalib/
	cl> gfreduce.rawpath="rdata$2001sep09/"
	cl> gfreduce.bias="gcalib$rgN20010825S129_bias.fits"
        cl> gfreduce N20010908S092 verb+ fl_over- fl_bias+ fl_trim+ \

        >>> fl_extract+ fl_wavtran- fl_skysub- fl_flux- fl_inter-

2. Apply all reduction steps except flux calibration to a standard star while setting some of the GFSKYSUB parameters beforehand.

	cl> gfskysub.combine="median"
	cl> gfskysub.reject="minmax"
	cl> gfskysub.nlow=0
	cl> gfskysub.nkeep=1
	cl> gfreduce N20010908S091 verb+ fl_over- fl_bias+ fl_trim+ \

	>>> fl_extract+ fl_wavtran+ fl_skysub+ fl_flux- fl_inter- \

	>>> refer=exrgN20010908S092 trace- \

	>>> response=exrgN20010908S092_resp112 wavtran=ergN20010908S093

3. After determining the flux calibration using GFAPSUM and
   GSSTANDARD, apply the flux calibration to the standard star to
   check the results.

	cl> gfreduce astexrgN20010908S091 rawpath="" verb+ \

	>>> fl_addmdf- fl_over- fl_bias- fl_trim- fl_gscrrej- \

	>>> fl_extract- fl_wavtran- fl_skysub- fl_flux+  fl_inter- \

	>>> sfunc=sens.fits extinct=extinct.dat

4. Sky-subtract and extract a N&S observation using a reference flat
   to define the apertures.
        cl> gfreduce.bias="gcalib$gS20040228S0001_bias.fits"
        cl> gfreduce.fl_gscrrej=no
        cl> gfreduce.fl_wavtran=no
        cl> gfreduce.fl_fluxcal=no
        cl> gfreduce S20040229S0050.fits fl_gnssky+ fl_skysub-
        >>> fl_extract+ fl_gsappwave+ mdffile="gsifu_ns_slits_mdf.fits" \

        >>> trace- recenter- reference=ergS20040229S0049

BUGS AND LIMITATIONS

Improvements to the (previously semi-functional) variance and data quality propagation in the GMOS package have undergone limited testing; the accuracy of the results should still be verified at each step by the scientist, particularly for spectroscopic data reduction tasks.

NAME

USAGE

PARAMETERS

DESCRIPTION

EXAMPLES

BUGS AND LIMITATIONS

SEE ALSO