# 
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++
#.COPYRIGHT   (C) 1993 European Southern Observatory
#.IDENT       irspec_extended.hlp
#.AUTHOR      Cristian Levin   (ESO/La Silla)
#.KEYWORDS    Infrared spectroscopy, Irspec
#.PURPOSE     This is the help file for the extended help
#             feature of XIrspec.
#
#.VERSION     1.0  Package Creation  17-MAR-1994
#-------------------------------------------------------
#

~HELP_CONTEXT
This is the context Irspec.
~HELP_HELP
You can get an extended help for each button of the interface by pressing 
the right mouse button when the cursor is over the interface button.

~HELP_TUTORIAL
Not available for the moment. 
~HELP_VERSION
  This is the version 1.0 of the Graphical User Interface for the context 
  Irspec.

  comments about the interface can be sent to : clevin@eso.org (Cristian Levin)
  comments about the commands can be sent to: midas@eso.org (MIDAS support)

~MAIN_BADPIX
To create a table containing the position of bad pixels.

The IRSPEC array has a fixed pattern of bad pixels which, which can
be cleaned by by substituting the values of the bad pixels with the 
average of the neighboring good pixels. A default table of bad pixels 
(irsbadpix.tbl) is automatically created when starting the IRSPEC context. 
If the default table is going to be used, cleaning of frames is done 
implicitly when reducing the standard star or object, and BADPIX
is not explicitly required.

~MAIN_FLAT
To create a normalized flat from an halogen frame. The flat will be
used in the reduction of the standard star and the object.

The normalization procedure consists of dividing the original frame,
cleaned of the bad pixels, by the average value of the central 6 rows.
Hence, the normalized output image contains also the detector response
at low spatial frequencies. Use the explicit MIDAS commands FIT/FLAT
if you need a more normalized flat. 

The vignetted rows are set to large values in order to make them 
vanishing after division by the flat.

For applications up to 2.5 microns the input, flat image is usually
a measurement of the halogen lamp with counts level as close as possible
to those in the astronomical frames. 


~MAIN_FLUX
First step for flux calibration of IRSPEC data. 

The user must provide an ASCII file with his/her favorite
guesses of the star fluxes at a number of wavelengths, e.g. the
values of F(lambda) at the effective wavelengths of photometric
filters in case of photometric standard stars. The file must
contain, in columns 1 and 2, the wavelength and corresponding
flux, respectively. Columns 3 and higher may contain comments.

Example
1.25   1.04e-3   J=6.12, flux in 1e-11 erg cm-2 s-1 mu-1
2.20   196       K=5.73, same units
1.65   4.34e-2   H=5.99, same units

The command will then create a MIDAS table containing a properly
sampled F(lambda) vs. lambda interpolation within the wavelength
limits given in the input ascii file.

~MAIN_STANDARD
Open the window for standard star reduction.

To create a 1-D response frame which contains the conversion from
counts/sec to flux units for the measurements taken at a given central
wavelength. 

~MAIN_OBJECT
Open the window for object reduction.

~MAIN_EXTRACT
Open the window for spectrum extraction.

~MAIN_MERGE
Open the window for the merge of overlapping 1D spectra into a table.
The command also allows optimizing the connection on the overlapping
parts and excluding a given number of pixels at both edges of the
spectrum.

~BADPIX_DEFINE

~BADPIX_APPLY

~FLUX_APPLY

Interpolation of the flux values provided in the ASCII table 
'Broad band flux table', to create a MIDAS table 'Output flux table'.

The 'Broad band flux table' must contain, in columns 1 and 2, 
the wavelength and corresponding flux, respectively, of the 
standard star used to calibrate the spectra.

The 'Output flux table' contains wavelengths (column :wl) and
fluxes (column :flux) interpolated over the input values according
to the Interpolation method. The star flux is sampled at wavelength
intervals specified in 'Wavelength step', default = 0.01. 
'Fit degree' is the degree of the polynomial/spline, default = 2. 

For the transformation from magnitudes to fluxes you may use e.g.
Wilson et al. 1972, ApJ 177, 533
Bessel        1979, PASP 91, 589


~STANDARD_REDUCE

To create a 1-D response frame which contains the conversion from
counts/sec to flux units for the measurements taken at a given 
central wavelength.  'Flux table' is a previously created MIDAS
table with properly sampled flux values of the standard star.
'Response frame' is the output 1-D frame containing the instrumental
response (counts per second per unit flux). 'Y-positions' are the
positions of the lower and upper standard star continua in the
sky-subtracted frame.

Wavelength calibration
----------------------
The wavelength dispersion on the IRSPEC array is linear within a small 
fraction of the pixel size. Hence, wavelength calibration simply means
to modify the x-start and x-step descriptor values of the image. 

Standard: A quite precise - usually within one pixel - estimate of
	  the wavelength scale is available directly from the 
	  IRSPEC descriptors. 
          The standard wavelength calibration works automatically.


High acc: A more accurate wavelength calibration can be reached if
	  the frame contains emission lines with known wavelengths.
	  Up to 2.3 microns the OH lines in the sky frames are a very
	  convenient calibrator (Oliva & Origlia 1992, A&A 254, 466). 

	  If High accuracy is selected, specify a 'Reference frame'
	  which will contain the precise wavelength parameters. 
	  The 'High accuracy' method works interactively.


Sky subtraction
---------------
In most of the infrared the sky emission contains bright emission
lines, OH transitions up to 2.3 microns and molecular bands (CO2, CH4)
at longer wavelengths. The intensity of the OH transitions varies on
short time scales, so the 'object - sky' difference frames may contain
residual sky lines. It also happens that the grating moves by tiny
amounts between object and sky frames, which deteriorates the sky
subtraction considerably.
If such occurs, the sky frame may be multiplied by a factor different 
from 1.0 and shifted by an amount different from 0. Factors and
shifts can be entered or obtained interactively by specifying 
factor = 0

~OBJECT_REDUCE

Wavelength calibration
----------------------
The wavelength dispersion on the IRSPEC array is linear within a small
fraction of the pixel size. Hence, wavelength calibration simply means
to modify the x-start and x-step descriptor values of the image.

Standard: A quite precise - usually within one pixel - estimate of
	  the wavelength scale is available directly from the
	  IRSPEC descriptors. The standard wavelength calibration works
          automatically.


High acc: A more accurate wavelength calibration can be reached if
          the frame contains emission lines with known wavelengths.
	  Up to 2.3 microns the OH lines in the sky frames are a very
          convenient calibrator (Oliva & Origlia 1992, A&A 254, 466).

          If High accuracy is selected, specify a 'Reference frame'
          which will contain the precise wavelength parameters.
	  The 'High accuracy' method works interactively.

Sky subtraction
---------------
In most of the infrared the sky emission contains bright emission
lines, OH transitions up to 2.3 microns and molecular bands (CO2, CH4)
at longer wavelengths. The intensity of the OH transitions varies on
short time scales, so the 'object - sky' difference frames may contain
residual sky lines. It also happens that the grating moves by tiny
amounts between object and sky frames, which deteriorates the sky
subtraction considerably.
If such occurs, the sky frame may be multiplied by a factor different
from 1.0 and shifted by an amount different from 0. Factors and
shifts can be entered or obtained interactively by specifying
factor = 0


~OBJECT_FLUX

To flux calibrate a spectrum which could either be a 2-D long-slit
image or a 1-D spectrum. A 'Response frame' must have been previously
created using the 'Std star...' command. 

~MERGE_APPLY

Merge overlapping 1-D spectra (images) into a table. The spectra
must be ordered in wavelength and must be overlapping.
The 1-D spectra to be connected must be named with a prefix and
a number, eg spec0001, spec0002, spec0003, etc.

Prefix:   The files prefix, i.e. "spec" in the above example

Interval: Give here the first and last number of the files 
	  to be merged.

Step:     Increment of file-ID numbers, default = 1.

ref#:     In the process of forcing the connection of the overlapping
	  regions, one of the 1-D images (the reference image) is
	  left untouched. If ref=0 (default) the reference image is
	  the central 1D frame of frames specified. 

Example
-------
prefix:   spec
interval: 4, 12
step:     3
ref#:     8

will cause the 1-D spectra, contained in files
spec0004, spec0008, spec0012, to be merged, with file spec0008
taken as the reference. 

NOTE
----
The connection between the spectra is optimized by applying a 
multiplicative factor to the spectra (NB the input spectra are
left untouched). This implies that the command works properly only
with spectra with strong and well defined continua while it may produce
totally unreliable results with spectra with faint continua affected by
variable offsets.


~EXTRACT_SKY
 Asks the user for the sky windows using the cursor over the display
 window. The coordinates are then displayed in the input form.

~EXTRACT_OBJECT
 Asks the user for the object limits using the cursor over the display
 window. The coordinates are then displayed in the input form.

~EXTRACT_FIT
 Fit a polynomial to the data in two windows along the Y-axis.
 Two modes can be selected:

Same spatial profile -- Here it is assumed that the normalized spatial
                        profile is the same for all columns and only one
                        polynomial is fitted to the mean spatial profile.

Independent profile  -- In this case an independent polynomial is fitted
                        for every row of the spectrum, filtering also the
                        cosmic rays.

PARAMETERS: The following parameters must be set in the input form:

a) Sky limits (pixels)   -- starting and ending Y coordinates of the sky
                            windows

b) Polynomial fit degree -- degree of the fit to be used.

c) Radius                -- used for cosmics rays rejection.


~EXTRACT_AVERAGE
The standard method. The sky is taken from the sky limits values of 
the input window. The result is summed or averaged depending on the
extraction method parameter.

~EXTRACT_WEIGHT
 Extract spectrum from CCD frame. The rows of the spectrum are
 added with weights which are chosen for optimal S/N-ratio of
 the resulting spectrum. Cosmic ray hits are removed by
 analyzing the profile perpendicular to the dispersion (assumed
 to be along the X-axis). The method is only suited for
 spectra of (spatially) unresolved sources. The method is very
 similar to the one described by Horne (1986, PASP 98, 609).

PARAMETERS:  The extraction algorithm uses the following parameters:

a) Object limits (pixels)    -- Approximate Y coordinates of the object
                                (starting and ending).

b) Extraction iterations     -- Number of iterations in the extraction
                                process.

c) Read-out-noise (e-)       -- Read out noise of the CCD in electrons.

d) Inverse gain factor       -- Conversion factor from ADU to electrons.
                                (e-/ADU)

e) Threshold for cosmic rays -- Threshold used for the rejection of
                                cosmic ray hits.
