msresp1d: Create 1D response spectra from flat field and sky spectra

Package: hydra

Usage

msresp1d flat throughput apreference response

Parameters

flat: Flat field image to extract and normalize to create a one dimensional aperture response image. If no flat field is specified then a throughput image or file must be specified and only a throughput correction will be created. Note that the two dimensional unextracted image is specified. If an extracted image of the same name with the ".ms" extension is present it is used without reextraction though the unextracted image must also be present.

throughput: Throughput file or image. If an image is specified, typically a blank sky observation, the total flux through each aperture is used to correct for the aperture throughput. If a file consisting of lines with the aperture number and relative throughput is specified then the aperture throughput will be generated by those values. If neither is specified but a flat field image is given the flat field is used to compute the throughput. Note that the image is a two dimensional unextracted image. If an extracted image of the same name with the ".ms" extension is present it is used without reextraction though the unextracted image must also be present.

apreference: Aperture reference spectrum. If not specified the apertures are defined using the flat field or throughput images. If only a throughput file is used then an aperture reference spectrum must be specified to define the apertures and dimensions of the final response image.

response: Response spectrum to be created.

recenter = no: Recenter throughput image apertures?

edit = yes: Edit and review apertures?

trace = no: Trace spectra?

clean = no: Detect and replace bad pixels?

fitflat = yes: Fit and ratio flat field spectrum?

interactive = yes: Interactive flat field fit?

function = "spline3", order = 20: Flat field fitting function and order. The functions may be one of "chebyshev", "legendre", "spline1" (linear spline), or "spline3" (cubic spline). The order is either the number of polynomial terms or the number of spline pieces.

Other parameters

The package parameters control logging of the operations performed and the verbose option allows printing of some progress information. The graphics use the device defined by the STDGRAPH variable and cursor input is with the parameter cl.gcur.

Aperture extraction is done using the task apall and any parameters not overridden by task parameters will be used; for example the detector noise parameters.

Description

For multiaperture or multifiber spectra a throughput aperture correction must be applied to extracted object spectra. Also it is often better to divide by a one dimensional flat field than a two dimensional one. This is valid provided the pixels sampled by the flat field and object are essentially the same. The advantages are that interspectrum pixels where there is little signal are not used and small shifts (fractions of a pixel) can be tolerated. The task msresp1d creates a multiaperture image containing one dimensional flat field and throughput corrections which can be directly divided into extracted object spectra.

If a one dimensional flat field is to be determined the flat field spectra are extracted unless an extracted image having the specified flat field name with the ".ms" extension is present. If the fitflat parameter is set then all the spectra are averaged and a smooth function is fit to this composite flat field spectrum. The smooth fit is divided into the individual flat field spectra. This removes the mean flat field spectrum shape, thus avoiding introducing the inverse of the flat field spectrum into the object spectra and changing the approximate count levels in the object. This procedure is recommended. Note that it does not matter if the individual fibers have differing spectral shapes (such as might happen with a combination of fibers with differing spectral throughput) because only a common function is used. The fitting is done using the fit1d task based on the icfit function fitting routines. When the interactive flag is set the fitting may be done interactively allowing iteration on the fitting function and other fitting parameters. Note that the function fit should follow the overall shape using a fairly high order.

If no throughput image or file is specified the relative strengths of the flat field spectra define a throughput correction. If a separate throughput image or file is given then the individual flat field spectra are normalized to unity and then scaled by the throughput determined from the image or file.

If a throughput image, such as a blank sky observation, is specified it is extracted if needed. The extracted sky spectra are divided by the flat field which is not yet corrected for throughput variations. The total flux through each aperture is then found to define the relative throughputs of the apertures. If a flat field was also specified the throughput values are multiplied into the normalized flat field otherwise the response image will consist of constant spectra with the relative throughputs derived from the image.

If a throughput file is specified the throughput values for each aperture are defined from this file. The file consists of lines with two columns, the aperture number and the relative throughput. All apertures should be represented. If a flat field was also specified the throughput values are multiplied into the normalized flat field. If no flat field is given then the aperture reference image must be specified and it will be extracted, if necessary, to provide the template for the response image having constant values for each aperture spectrum.

It is an error unless one or both of the flat field and throughput are specified.

The last stage is to normalize of the response spectra over all apertures to a global unit mean. Because of this step the throughput values derived from the flat field, throughput image, or throughput file need only be relative. Log information is recorded and printed which includes the final relative throughputs values.

Aperture extraction is done using the task apall and any parameters not overridden by task parameters will be used; for example the detector noise parameters. Task parmeters control whether recentering, aperture review, and tracing are done. If no aperture reference is specified the apertures will be defined as the task is run. The aperture reference, if defined, is often the same as the flat field.

Examples

1. To make a flat field response and apply it to an extracted object:

ms> msred.verbose=yes
ms> msresp1d flat005 "" "" resp005.ms
Extract flat field flat005
Searching aperture database ...
Sep  7 14:36: DATABASE  - 44 apertures read for flat005.
Resize apertures for flat005?  (yes): n
Edit apertures for flat005?  (yes): n
Extract aperture spectra for flat005?  (yes):
Review extracted spectra from flat005?  (yes): n
Extracting apertures ...
Sep  7 14:37: EXTRACT - Aperture 1 from flat005 --> flat005.ms
Sep  7 14:37: EXTRACT - Aperture 2 from flat005 --> flat005.ms
Sep  7 14:37: EXTRACT - Aperture 3 from flat005 --> flat005.ms
Sep  7 14:37: EXTRACT - Aperture 4 from flat005 --> flat005.ms
Sep  7 14:37: EXTRACT - Aperture 5 from flat005 --> flat005.ms
<etc>
Fit and ratio flat field flat005
<Interactive fitting of average extracted flat field>
Create the normalized response resp005.ms
Sep  7 14:38 BSCALE: image = resp005.ms
  bzero=0.  bscale=1.0  mean=1.0  median=1.02386  mode=1.07141
Average fiber response:
  1  0.8049859
  2  0.6428247
  3  0.9014022
  4  0.7955039
  5  0.9898984
  <etc>
ms> imarith obj006.ms / resp005.ms obj006.ms

Of course the extracted object spectra must be the same in terms of apertures, wavelength coverage, etc.

2. To make only a throughput correction:

ms> msresp1d "" obj005 "" resp005