.help msresp1d Feb92 noao.imred.specred
.ih
NAME
msresp1d -- Create 1D aperture response from flat and throughput data
.ih
USAGE
msresp1d flat throughput apreference response
.ih
PARAMETERS
.ls 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.
.le
.ls 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.
.le
.ls 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.
.le
.ls response
Response spectrum to be created.
.le

.ls recenter = no
Recenter throughput image apertures?
.le
.ls edit = yes
Edit and review apertures?
.le
.ls trace = no
Trace spectra?
.le
.ls clean = no
Detect and replace bad pixels?
.le
.ls fitflat = yes
Fit and ratio flat field spectrum?
.le
.ls interactive = yes
Interactive flat field fit?
.le
.ls 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.
.le
.ih
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 \fIcl.gcur\fR.

Aperture extraction is done using the task \fBapall\fR and any parameters
not overridden by task parameters will be used; for example the detector
noise parameters.
.ih
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 \fBmsresp1d\fR 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 \fIfitflat\fR 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 \fBfit1d\fR
task based on the \fBicfit\fR function fitting routines.  When the
\fIinteractive\fR 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 \fBapall\fR 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.
.ih
EXAMPLES
1.  To make a flat field response and apply it to an extracted object:

.nf
    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
.fi

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

2.  To make only a throughput correction:

.nf
    ms> msresp1d "" obj005 "" resp005
.fi
.ih
SEE ALSO
icfit, fit1d, apflatten, apnormalize, dofibers
.endhelp
