Initial commit

1 files changed, 191 insertions, 0 deletions

diff --git a/noao/imred/specred/doc/msresp1d.hlp b/noao/imred/specred/doc/msresp1d.hlp
new file mode 100644
index 00000000..cc3dfed2
--- /dev/null
+++ b/noao/imred/specred/doc/msresp1d.hlp
@@ -0,0 +1,191 @@
+.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