This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, see <http://www.gnu.org/licenses>.

Additional permission under GNU GPL version 3 section 7

If you modify this Program, or any covered work, by linking or
combining it with IDL (or a modified version of that library),
containing parts covered by the terms of the IDL license, the
licensors of this Program grant you additional permission to convey
the resulting work.

Given an input image, a spectrum bin (SPECBIN) and a spectrum number
(SPECNUM), this routine first locates the maximum position of an
emission line on the dispersion axis. Thereafter the same line is
searched for in all other spectra in the image; these positions are
compared to that of the first determined position using a cross-
correlation method.

Input parameters:

image

A two-dimensional emission line image.

specbin

Initial spectrum bin to look for an emission line
in (in the dispersion direction).

specnum

Initial spectrum to look for an emission line in
(in the cross-dispersion direction).

Keyword parameters:

deadfibers

A one-dimensional array of integers specifying
which fiber positions are to be interpolated
instead of fitted.

sdeadfibers

A one-dimensional array of strings containing the
type of the dead fibers. If this input is not used
then all elements of DEADFIBERS are considered to
be 'dead'. If it is set then the low-transmission
fibers, which are indicated with the prefix 'low'
(lower case) are sorted out, and are thereby
considered to be normal fibers.

linewidth

[specbin-linewidth,specbin+linewidth] defines the
interval, where the line will be searched for
initialization.
The default value is:
5

crosswidth

The width of an interval around the emission line
that is defined for cross-correlating the spectra.
The default value is:
3 * linewidth

topwid

If set, then error messages are displayed using
DIALOG_MESSAGE, using this widget id as
DIALOG_PARENT, instead of MESSAGE.

logunit

Messages are saved to the file pointed to by this
logical file unit, if it is defined.

verbose

Set this parameter to a positive scalar integer to
make p3d write some information on STDOUT about
what is going on. The following four values are
acknowledged:

0

Writes no information at all. This is the
default.

1

Writes the more important information;
regarding subroutine configurations, mostly.

2

Writes most information; includes a more
verbose output than 1.

3

Writes all information, including
information on the execution state of GUI
subroutines. This may be a useful mode when
debugging the code.

error

This scalar integer returns an error code if set.
Any value different from zero means that an error
has occurred.

debug

No error handler is setup if this keyword is set.
The default is otherwise to setup an error handler
(using the routine CATCH), which makes each
subroutine exit quietly in case a bug is
encountered. Use this keyword when debugging p3d.

help

Set this keyword to show this routine
documentation, and then exit.

Output parameters:

out

An array containing the line geometry (x-positions
of the emission line) for every spectrum.

This routine calculates corrected positions for a list of calibration
lines in every spectrum of a supplied spectrum image. The method is
either 'Gaussian' (the default), or 'Weighted'. The results should be
much more accurate using Gaussian line centering than using a data-
weighted centering. The approach using Gaussian fitting is, however,
much more time-consuming.

Input parameters:

refimage

A two-dimensional array; of floating point type. It
is assumed that the dispersion axis is the first
dimension in REFIMAGE.

linepos

A one-dimensional array.

lwid

The width of the region, which is used to integrate
over the emission lines; given in pixels.

Keyword parameters:

niterat

The maximum number of iterations; a scalar
integer <= 100. Only used with METHOD = 'Weighted'.
The default value is:
5

offsets

Specifies an array of offsets between the different
spectra.

dooffsets

Calculates the offset array between the different
spectra anew.

refrow

The starting spectrum.
The default value is:
s[2

fwhm

A scalar decimal value with the instrumental line
width in the dispersion dimension. Only used with
METHOD=='Gaussian'.

method

A scalar string that defines the method to be used
when calculating more precise line center
positions: ['Gaussian'] or 'Weighted'.

monitor

If set to 1, Gaussian fits are shown for the
reference spectrum. If MONITOR = 2, the fit is
shown for all spectra. If MONITOR = 3, all fits are
shown for the arc line MONK.

monk

An integer scalar, set to a value between 0 and the
number of elements in LINEPOS – 1; this variable is
only used if MONITOR = 3.

deadfibers

A one-dimensional array of integers specifying
which fiber positions are to be interpolated
instead of fitted.

sdeadfibers

A one-dimensional array of strings containing the
type of the dead fibers. If this input is not used
then all elements of DEADFIBERS are considered to
be 'dead'. If it is set then the low-transmission
fibers, which are indicated with the prefix 'low'
(lower case) are sorted out, and are thereby
considered to be normal fibers.

colorbg

This scalar integer contains the background color
index.

colorfg

This scalar integer contains the foreground color
index.

colorxb

This scalar integer contains the additional
foreground color index.

stawid

If set to a valid ID then a log message is written
using this ID for relevant actions.

topwid

If set, then error messages are displayed using
DIALOG_MESSAGE, using this widget id as
DIALOG_PARENT, instead of MESSAGE.

logunit

Messages are saved to the file pointed to by this
logical file unit, if it is defined.

verbose

Set this parameter to a positive scalar integer to
make p3d write some information on STDOUT about
what is going on. The following four values are
acknowledged:

0

Writes no information at all. This is the
default.

1

Writes the more important information;
regarding subroutine configurations, mostly.

2

Writes most information; includes a more
verbose output than 1.

3

Writes all information, including
information on the execution state of GUI
subroutines. This may be a useful mode when
debugging the code.

error

This scalar integer returns an error code if set.
Any value different from zero means that an error
has occurred.

debug

No error handler is setup if this keyword is set.
The default is otherwise to setup an error handler
(using the routine CATCH), which makes each
subroutine exit quietly in case a bug is
encountered. Use this keyword when debugging p3d.

help

Set this keyword to show this routine
documentation, and then exit.

Output parameters:

out

A two-dimensional array of corrected positions for
every calibration line in every spectrum.

inlines

A one-dimensional array specifying for which lines
in LINEPOS that corrected positions could be
calculated. If none, INLINES = – 1L.

A one-dimensional array of integer indices
indicating which rows of INSPEC are to be removed.

Keyword parameters:

daxis

Specifies the dispersion axis of INSPEC.
The default value is:
1

topwid

If set, then error messages are displayed using
DIALOG_MESSAGE, using this widget id as
DIALOG_PARENT, instead of MESSAGE.

logunit

Messages are saved to the file pointed to by this
logical file unit, if it is defined.

verbose

Set this parameter to a positive scalar integer to
make p3d write some information on STDOUT about
what is going on. The following four values are
acknowledged:

0

Writes no information at all. This is the
default.

1

Writes the more important information;
regarding subroutine configurations, mostly.

2

Writes most information; includes a more
verbose output than 1.

3

Writes all information, including
information on the execution state of GUI
subroutines. This may be a useful mode when
debugging the code.

error

This scalar integer returns an error code if set.
Any value different from zero means that an error
has occurred.

debug

No error handler is setup if this keyword is set.
The default is otherwise to setup an error handler
(using the routine CATCH), which makes each
subroutine exit quietly in case a bug is
encountered. Use this keyword when debugging p3d.

help

Set this keyword to show this routine
documentation, and then exit.

Output parameters:

outspec

A two-dimensional array with the spectra indicated
by ROWNUM removed from INSPEC.

The second option is a linear interpolation; when DRIZZLE is unset,
or the error image is missing. The errors were earlier calculated
using an erroneuous approach – set the ORIGINALERRORS keyword to
force the use of this approach. Now the errors are calculated using
the approach as presented by Bevington (1992 or 2002; chapter 4
[Estimates of mean and errors], and the sub-sections "Weighting the
Data – Nonuniform Uncertainties" and "Error in the Weighted Mean",
specifically Eq. 4.19) or Taylor (1997; chapter 7 [Weighted
averages]). The approach of Fruchter & Hook (2002) differs slightly,
as it contains additional weighting of the data with the used pixel
fraction and relative input/output pixel size.

Comments

This routine will produce several hundreds of megabytes and more of
log-file output when LOGLEVEL>=3, which might cause problems if there
is little free diskspace.

Set this keyword to use a one-dimensional drizzling
algorithm instead of the standard linear
interpolation.
The default value is:
1

resample_startpx

A scalar value that specifies the
el in the calculation of the output
rray when resampling pixel values to
alues. The value can be set to 'first',
fault], or 'last', to use of the first,
or the last output pixel as a starting
natively, it can be set to an integer
ame range. Negative values, and values
her than the maximum number of pixels,
, are truncated.
The default value is:
'middle'

obpmask

A two-dimensional array of the same size as STACK,
containing an output bad-pixels mask. If this
keyword is set, the contents are also converted
to wavelength coordinates; the output is stored in
OOBPMASK.

oobpmask

If OBPMASK is set, this keyword contains the
converted output bad-pixels mask image upon exit.
The dimensions are the same as those of OUT.

satmask

A two-dimensional array of the same size as STACK,
containing a saturated-pixels mask. If this keyword
is set, the contents are also converted to
wavelength coordinates; the output is stored in
OSATMASK.

osatmask

If SATMASK is set, this keyword contains the
converted saturated-pixels mask image upon exit.
The dimensions are the same as those of OUT.

originalerrors

Set this keyword to use the original version of the
calculated errors (with the linear interpolation
scheme).

skyalign

This keyword can be used in two ways:

Set it to a scalar string with the name of an
existing file with a list of telluric
(sky-emission) lines.

Set it to a floating-point value array with
pre-selected telluric-line wavelengths.

This way the wavelength solution is aligned with
the median of the telluric-line offset positions.
Only the fylly working spectra/fibers are used when
calculating the offset if DEADFIBERSMASK is
specified. Also see the ONESKYOFFSET and the
MAXSKYOFFSET keywords.

oneskyoffset

Set this keyword to use one median offset value on
all wavelength arrays in the dispersion mask.
Otherwise, each wavelength array in the dispersion
mask is offset individually. Additionally, when
this parameter is unset the offset at each
wavelength bin is weighted with the wavelength
extent of the pixel relative to the corresponding
extent at the selected sky-emission line (since
uncalibrated wavelength arrays generally deviate
from a linear function).

maxskyoffset

A scalar decimal value that when multiplied with
pixel dispersion (CDELT) specifies the maximum
owed offset of the sky-emission lines, from the
ation provided in the dispersion mask. The unit
Angstrom. A higher value than the default of
* CDELT could be used in case the expected
set due to flexure is higher. (Otherwise such
es are ignored.)
The default value is:
2.0

dpath

If this keyword is set, SKYALIGN is passed through
p3d_misc_pathify with dpath set.

daxis

Specifies the dispersion axis of STACK; 1 is the
x-axis, 2 is the y-axis.
The default value is:
1

deadfibersmask

An integer array with as many elements as there are
spectra in STACK. The elements must each have the
value 0 (the fiber is dead, should not be used, is
a low-transmission fiber) or 1 (the fiber can be
used). This mask is used when fitting telluric
emission lines.

psfilename

Set this scalar string to the name of the
postscript file that will be created to show the
fits of the telluric lines (when using SKYALIGN).

a2

Set this keyword to use the A2 paper format with
PostScript and PDF output instead of A4.

a3

Set this keyword to use the A3 paper format with
PostScript and PDF output instead of A4.

a5

Set this keyword to use the A5 paper format with
PostScript and PDF output instead of A4.

letter

Set this keyword to use the US Letter paper format
with PostScript and PDF output instead of A4.

legal

Set this keyword to use the US Legal paper format
with PostScript and PDF output instead of A4.

tabloid

Set this keyword to use the US Tabloid paper format
with PostScript and PDF output instead of A4.
(see p3d_misc_plotallspectra.)

nthreads

A scalar integer that specifies how many threads to
use in the parallelized dispersion correction
calculation.
The default value is:
1

topwid

If set, error messages are displayed using
DIALOG_MESSAGE, using this widget id as
DIALOG_PARENT, instead of MESSAGE.

logunit

Messages are saved to the file pointed to by this
logical file unit, if it is defined.

verbose

Set this parameter to a positive scalar integer to
make p3d write some information on STDOUT about
what is going on. The following four values are
acknowledged:

0

Writes no information at all. This is the
default.

1

Writes the more important information;
regarding subroutine configurations, mostly.

2

Writes most information; includes a more
verbose output than 1.

3

Writes all information, including
information on the execution state of GUI
subroutines. This may be a useful mode when
debugging the code.

error

This scalar integer returns an error code if set.
Any value different from zero means that an error
has occurred.

debug

No error handler is setup if this keyword is set.
The default is otherwise to setup an error handler
(using the routine CATCH), which makes each
subroutine exit quietly in case a bug is
encountered. Use this keyword when debugging p3d.

cdebug

A keyword as DEBUG used with the called C routines.

help

Set this keyword to show this routine
documentation, and then exit.

Output parameters:

crval

A decimal scalar that specifies the wavelength of
the first pixel.

cdelt

A decimal scalar that specifies the dispersion per
pixel for output images, which are linearized in
wavelength.

out

A three- (or two-)dimensional array of stacked
images, which have been wavelength calibrated.

This routine adds numbered rows to a dispersion mask, that is given
in parameter form. Each added row holds the same parameters as the
preceeding row. A purpose of this routine is to add calibration
spectra for instance, which were not used in the creation of the
dispersion mask.

Input parameters:

inparams

A structure that contains a two-dimensional array
(c) with parameters of the polynomial fit (2nd
dimension) of the wavelength array. Different
spectra are stacked in the first dimension.
Additionally, another array (m) holds the minimum
and the maximum pixel values that were used to
scale the pixel array before calling poly_fit.

rownum

A one-dimensional array of integer indices
indicating where to add lines.

Keyword parameters:

topwid

If set, then error messages are displayed using
DIALOG_MESSAGE, using this widget id as
DIALOG_PARENT, instead of MESSAGE.

logunit

Messages are saved to the file pointed to by this
logical file unit, if it is defined.

verbose

Set this parameter to a positive scalar integer to
make p3d write some information on STDOUT about
what is going on. The following four values are
acknowledged:

0

Writes no information at all. This is the
default.

1

Writes the more important information;
regarding subroutine configurations, mostly.

2

Writes most information; includes a more
verbose output than 1.

3

Writes all information, including
information on the execution state of GUI
subroutines. This may be a useful mode when
debugging the code.

error

This scalar integer returns an error code if set.
Any value different from zero means that an error
has occurred.

debug

No error handler is setup if this keyword is set.
The default is otherwise to setup an error handler
(using the routine CATCH), which makes each
subroutine exit quietly in case a bug is
encountered. Use this keyword when debugging p3d.

help

Set this keyword to show this routine
documentation, and then exit.

Output parameters:

outparams

A two-dimensional array with the parameters of the
polynomial fits – with added rows (according to
ROWNUM).

This is an interactive program for creating a dispersion mask. That
is, a file listing the best-fit dispersion solution parameters for
each spectrum in the input image. The GUI layout displays this input
RSS image in the top panel. Below that a plot of an individual
spectrum ("reference spectrum") is shown.

The initial dispersion mask is a set of straight lines given by the
input linelist. This mask is overlaid on the RSS image. The user can
modify the initial mask as follows:

Match the shape of the mask lines to the curvature of the emission
lines in the RSS image.

Shift and centroid the mask so that its spatially aligned with the
emission lines in the RSS image.

Optionally delete mask lines from the input line list.

Inspect the best-fit dispersion solution for the reference spectrum
and change the order of the best-fit polynomial if necessary.

When the match between the mask and the RSS image is satisfactory
the output dispersion mask is created and saved as a FITS file.

Format of files with line lists:

Lines which begin with the character ';' are comments.

Individual lines are specified with the wavelength (given in
Ångström [Å]) in the first column of the file. Columns are
separated with white space.

Only data in the first column is read. The data must be of
floating point type, as it subsequently is converted to doubles.

Input parameters:

imagefile

One, or two, filename(s) of an exposure, which was
taken using one, or several, arc lamps. If
IMAGEFILE is actually two image files, they are
combined using the values of IMAGEORDER and
IMAGESPLITBIN:

IMAGEORDER = 0

The used image uses the
wavelength bins 0:IMAGESPLITBIN – 2 from
IMAGEFILE[0] and IMAGESPLITBIN: from
IMAGEFILE[1].

IMAGEORDER = 1

The used image uses the
wavelength bins 0:IMAGESPLITBIN – 2 from
IMAGEFILE[1] and IMAGESPLITBIN: from
IMAGEFILE[0].

The lowermost value of IMAGESPLITBIN is 1.

linelist

The filename of a file specifying which wavelengths
are emission lines of the arc lamp.
Note! This variable is not used if DISPMASKIN is
set and that file also contains the ARCLNNUM and
the ARCLNxxx header keywords. The routine
must still be called with this keyword present!

gratingfile

The filename of an instrument-specific file that
provides grating-related parameters.

ofilename

The filename of the output dispersion mask.

Keyword parameters:

dispmaskin

A scalar string with the name of a dispersion-mask
input file. When present this file is used to
create the first-guess wavelength solution.
Note! If DISPMASKIN is set, this routine attempts
to read the line list from the header keywords in
this file; specifically, the required information
is contained in the ARCLNNUM and the ARCLNxxx
header keywords. (These are available in any
dispersion-mask image created using revision
>= 1004 of this routine.)

linewidth

A scalar integer that specifies the half-pixel-
width used when searching for maxima of emission
lines in the spectrum image (of IMAGEFILE).
The default value is:
4

refdist

A scalar integer specifying if any spectrum is to
be skipped. If REFDIST = 1, all spectra are used,
if REFDIST = 2, every second spectrum is used, etc.
(cf. REFDIST in p3d_wavecal_fit_maskwd).
The default value is:
1

nrows

A scalar integer specifying how many adjacent
spectra should be used in the fitting procedure
(the actual number is 2 * NROWS + 1).
The default value is:
0

kwrdlist

The name of a file, which contains a two-column
list of parameters to use with p3d for the
instrument in question.

cdelt

The dispersion (only used when PMAS = 0).

xdeg

The degree of the polynomial used to fit
emission-line wavelengths to the full spectrum.
The default value is:
3

ydeg

The degree of the polynomial used to fit
emission-line wavelengths on the cross-dispersion
(spatial) axis; YDEG = – 1 skips this fitting.
The default value is:
-1

colortable

A scalar string or integer that specifies which
color table should be loaded. If COLORTABLE is a
string, the string must contain two parts separated
by a comma, without any whitespace between. The
first part before the comma specifies the
color-table number in the file name specified after
the comma; the file must be formatted as described
in the documentation for MODIFYCT. As an example,
COLORTABLE='25,brewer.tbl'. Components in the
ColorBrewer color-table file "brewer.tbl" found in
the resource directory can be specified explicitly
by preceeding the string with "CB"; for example,
COLORTABLE='CB25'. If COLORTABLE is an integer, the
integer must be given in the range -4, -3, -2, -1,
0, ..., up to the maximum number of available
tables in IDL, plus the available tables in the
ColorBrewer file (resource/) "brewer.tbl". Select
-4, -3, -2, or -1 to load the cubehelix,
2 * Califa, and the Sauron color tables, the other
values use the respective color map as defined by
LOADCT. These are the permitted values:

Loads the Califa project velocity field
color table, as defined September 2012.

-1

Loads the Sauron color table (default).

0-74 (IDL version >= 8.3)

Loads the
corresponding color table with LOADCT.

0-40 (IDL version < 8.3)

Loads the
corresponding color table with LOADCT.

'CB0'-'CB85'

Loads the corresponding
ColorBrewer color table; the color tables
are defined in the file
"resource/brewer.tbl"

75-159 (IDL version >= 8.3)

Loads the
ColorBrewer color table corresponding to
this number after 75 is subtracted; the
color tables are defined in the file
"resource/brewer.tbl"

41-125 (IDL version < 8.3)

Loads the
ColorBrewer color table corresponding to
this number after 41 is subtracted; the
color tables are defined in the file
"resource/brewer.tbl"

'x,ctfile'

Loads the x:th entry ('x' must be
an integer) in the color-table file
'ctfile.

The default value is:
-1

invert

Set this keyword to invert the loaded color table.

cinv

Set this keyword to plot white lines on a black
background instead of the default, which is to plot
black lines on a white background.

bottom

A scalar integer that specifies the bottom
color map index to use with the data;
0 <= BOTTOM <= !d.table_size – 1.

cindex

An array of integers specifying the color indices
used as reserved colors. CINDEX ideally has 7
elements, P3D_SV uses 7 reserved colors. If the
number of elements is smaller, the upper range of
reserved colors will use the largest index
available (also see CINDV).

cindv

An array of 7 integers specifying which of the
indices in CINDEX are used as the reserved colors:
If CINDEX has 7 elements, CINDV = CINDEX[0:6].
If CINDEX has 3 elements, CINDV = [CINDEX[0],
CINDEX[1], CINDEX[2], CINDEX[2], CINDEX[2],
CINDEX[2], CINDEX[2]].

A scalar floating-point type value. During the
polynomial fitting, to get the dispersion solution,
residuals > RESIDUALCUT will not be used in a
second fit.
The default value is:
-1

fwhm

A scalar floating-point type value with the
instrumental line width in the dispersion
dimension.

method

A scalar string with the name of the method used
when centering lines; ['Gaussian'] and 'Weighted'
are implemented, see p3d_wavecal_correct_maskpos.

postable

A scalar string that contains the name of a
position-table file; this file is, if present, used
to remove calibration elements in the data before
the tool is setup.

posreverse

The position-table arrays are reversed (x, y, and
lens size) when this keyword is set.

deadfibers

An array of integers specifying dead fibers, which
should not be considered. The values must be
1-based, and the maximum number must be smaller
than the maximum number of spectra in the input
image file.

sdeadfibers

A string array with as many elements as DEADFIBERS
specifying the type of fiber in DEADFIBER (dead,
low transmission, unused,...).

removecalfibers

n/a.
bration fibers are removed from the data before
ling the data if this keyword is set.
The default value is:
1

vignettedfile

A scalar string that contains the name of a
vignetted fibers file; the contents of this file
is used to remove arc lines in vignetted regions,
before a polynomial is fitted as wavelength(pixel).

userparfile

A scalar string specifying the name of an optional
user-parameter file, that could contain the keyword
'polynomialorder'. If it does, the value of that
keyword is used instead of XDEG.
If there are several 'polynomialorder'-lines in the
file, only the first is used.

imageorder

A scalar integer that is used if the number of
files specified in IMAGEFILE is equal to two. For
the use, see the description of the input parameter
IMAGEFILE.
The default value is:
0

imagesplitbin

A scalar integer used if the number of files
specified in IMAGEFILE is equal to two. For the
use, see the description of the input parameter
IMAGEFILE.
The default value is:
0.5*# pixels in dispersion direction of IMAGEFILE[0

dflip

Spectrum order; if dflip is set, it is assumed that
the wavelength range has been flipped.
The default value is:
0

compress

If this keyword is set, the output data file is
compressed (using gzip).
The default value is:
0

dbin

This parameter determines if the input data are re-
binned on the dispersion axis (DBIN = 2 || 3), or
if the data are kept as is (DBIN = 1). A good
reason to rebin the data is if all pixels should
fit on the screen. The different values allowed
are:
DBIN = 1: The data are not rebinned.
DBIN = 2: The data are rebinned by a factor 2.
DBIN = 3: The data are rebinned by a factor 2
until all pixels fit on the screen.
The default value is:
1

track

A keyword specifying if hints are to be shown about
what is being done and what the functions of the
various widgets are.

detector

A scalar integer specifying which detector (setup)
to use; this keyword should only be used if several
detectors are configured in the used
instrument-parameter file.

daxis

Defines the dispersion direction dimension
of the data of IMAGEFILE. The default, 1, is in
the x-direction.
The default value is:
1

eventwid

If this variable is set to the widget id of a
button widget, that widget will receive an event
once the GUI created here is closed.

topwid

If set, error messages are displayed using
DIALOG_MESSAGE, using this widget id as
DIALOG_PARENT, instead of MESSAGE.

logunit

Messages are saved to the file pointed to by this
logical file unit, if it is defined.

verbose

Set this parameter to a positive scalar integer to
make p3d write some information on STDOUT about
what is going on. The following four values are
acknowledged:

0

Writes no information at all. This is the
default.

1

Writes the more important information;
regarding subroutine configurations, mostly.

2

Writes most information; includes a more
verbose output than 1.

3

Writes all information, including
information on the execution state of GUI
subroutines. This may be a useful mode when
debugging the code.

font

Set this scalar string to the name of the font to
use with all widget components of this tool.

error

This scalar integer returns an error code if set;
any non-zero value indicates that an error has
occurred.

debug

No error handler is setup if this keyword is set.
The default is otherwise to setup an error handler
(using the routine CATCH), which makes each
subroutine exit quietly in case a bug is
encountered. Use this keyword when debugging p3d.

This is the routine where the actual wavelength calibration
takes place. The wavelengths in the mask are fitted with a
polynomial of order DISPDEG against the corrected positions of the
lines in the spectrum image, that is assumed to contain
these lines.

Additional parameters allow the procedure to be modified:
If REFDIST is set to any integer above 1 then the fitting is made
with REFDIST as the stride. I.e., with REFDIST==2 every second
spectrum is fitted. If NROWS > 0 then the 2 * NROWS + 1 most adjacent
spectra are used in the fitting of every spectrum (boundaries are
different). If CROSSDEG >= 0 then the fitted parameters are fitted
once again, across all spectra for each order in the fitted
parameters separately (use is not recommended).

In order to check the quality of the fit the maximum residual (or all
residuals if LOGLEVEL==2) is output to a logfile or the screen (if
VERBOSE is set). Additionally the Chi-square value and the status of
POLY_FIT are also shown.

The polynomial parameters are provided for each spectrum of the
image in an array upon completion.

Input parameters:

image

A two-dimensional image with emission lines of an
arc (calibration) lamp.

nlines

A scalar integer specifying the number of
calibration lines.

linepos

A two-dimensional array holding the positions of
each matched calibration line for all spectra;
given in pixels.

wavelength

A one-dimensional array with the corresponding
wavelength of each emission line specified in
LINEPOS.

refdist

A scalar integer specifying if any spectrum is to
be skipped. If REFDIST==1 1 then each spectrum is
used, if REFDIST==2 then each second, etc.

dispdeg

A scalar integer specifying the order of the
polynomial that is used to fit each spectrum on
the dispersion axis.

crossdeg

A scalar integer specifying the order of the
polynomial that is used to fit the separate
parameters of the dispersion-direction fit.
The default value is:
-1

Keyword parameters:

residualcut

Residuals are calculated between the polynomial fit
of the wavelength function and WAVELENGTH. If
RESIDUALCUT is set to a positive value then the
weights are set to zeros where the residual is
larger than RESIDUALCUT.
The default value is:
-1

chisq

A one-dimensional array that returns the chi²
values of the fits for each spectrum.

maxspecnum

Returns the index of the spectrum which has the
largest residual.

refrow

The starting spectrum.
The default value is:
s[2

deadfibers

A one-dimensional array of integers specifying
which fiber positions are to be interpolated
instead of fitted.

sdeadfibers

A string array with as many elements as DEADFIBERS
specifying the type of fiber in DEADFIBER (dead,
low transmission, unused,...). This array is used
in order to only skip [D]ead or [U]nused fibers.

vignetted

An optional two-dimensional array with two columns
and as many rows has LINEPOS has rows. Each value
pair specify the useful pixel range for each
spectrum, vignetted regions can thereby be excluded
to improve the accuracy of the polynomial fit. If
necessary the polynomial order is decremented to
allow a fit.

optlow

If this keyword is set then the wavelength at pixel
0 is at first calculated using a linear fit of the
existing entries of the line list. That wavelength
is thereafter added to the wavelength and pixel
arrays before the final fit is made. By this
procedure it is possible to constrain fits where
there are few emission lines at the lowe range of
pixels in the arc image.

Note: OPTLOW and OPTHIG can be used simultaneously.

opthig

If this keyword is set then the wavelength at the
last pixel is at first calculated using a linear
fit of the existing entries of the line list. That
wavelength is thereafter added to the wavelength
and pixel arrays before the final fit is made. By
this procedure it is possible to constrain fits
where there are few emission lines at the upper
range of pixels in the arc image.

Note: OPTLOW and OPTHIG can be used simultaneously.

fitline

Returns a two-dimensional integer array that
indicates which emission lines were fit for each
spectrum.

stawid

If set to a valid ID then a log message is written
using this ID for relevant actions.

topwid

If set, then error messages are displayed using
DIALOG_MESSAGE, using this widget id as
DIALOG_PARENT, instead of MESSAGE.

logunit

Messages are saved to the file pointed to by this
logical file unit, if it is defined.

verbose

Set this parameter to a positive scalar integer to
make p3d write some information on STDOUT about
what is going on. The following four values are
acknowledged:

0

Writes no information at all. This is the
default.

1

Writes the more important information;
regarding subroutine configurations, mostly.

2

Writes most information; includes a more
verbose output than 1.

3

Writes all information, including
information on the execution state of GUI
subroutines. This may be a useful mode when
debugging the code.

error

This scalar integer returns an error code if set.
Any value different from zero means that an error
has occurred.

debug

No error handler is setup if this keyword is set.
The default is otherwise to setup an error handler
(using the routine CATCH), which makes each
subroutine exit quietly in case a bug is
encountered. Use this keyword when debugging p3d.

help

Set this keyword to show this routine
documentation, and then exit.

Output parameters:

out

A structure with a two-dimensional array (c) that
contains the parameters of the polynomial fit
[2nd dim.] for each spectrum in IMAGE.
Additionally, another array (m) holds the minimum
and the maximum pixel values that were used to
scale the pixel array before calling poly_fit.

The width of the instrumental profile [pixels].
The default value is:
4.0

flip

Reverses the order of pixels.

grotpos

The grating rotator encoder position. A default
value of -58.9 is used if this keyword is set to
either GROTPOS==1b or GROTPOS==1 (i.e. byte or
integer type).

flen

The focal length [mm].
The default value is:
270mm

grotoffset

The grating rotator of PMAS was broke in 2008. The
new encoder values are offset compared to the
tabulated values. This offset value can be set in
order to calculate the actual grating rotator
position. The default value of -214.8 is used iff
GROTPOS>0.0, otherwise it is set to 0.0. This value
is added to GROTPOS.
The default value is:
-214.8||0.0

topwid

If set, then error messages are displayed using
DIALOG_MESSAGE, using this widget id as
DIALOG_PARENT, instead of MESSAGE.

logunit

Messages are saved to the file pointed to by this
logical file unit, if it is defined.

verbose

Set this parameter to a positive scalar integer to
make p3d write some information on STDOUT about
what is going on. The following four values are
acknowledged:

0

Writes no information at all. This is the
default.

1

Writes the more important information;
regarding subroutine configurations, mostly.

2

Writes most information; includes a more
verbose output than 1.

3

Writes all information, including
information on the execution state of GUI
subroutines. This may be a useful mode when
debugging the code.

error

This scalar integer returns an error code if set.
Any value different from zero means that an error
has occurred.

debug

No error handler is setup if this keyword is set.
The default is otherwise to setup an error handler
(using the routine CATCH), which makes each
subroutine exit quietly in case a bug is
encountered. Use this keyword when debugging p3d.

This routine finds out which lines in the calibration line list
(REFWAVE, at positions REFPIXL) are actually found in the spectrum
SPEC(WAVELEN).

Input parameters:

spec

A one-dimensional array containing the spectrum
against which the matching is done. It has to be
of floating point type.

wavelen

A one-dimensional wavelength array corresponding
to SPEC.

refpixl

A one-dimensional array that specifies the
location of every line given in REFWAVE in the
array WAVELEN.

refwave

A one-dimensional array that specifies the
wavelengths of known emission lines; used together
with REFPIXL.

fwhm

A scalar decimal value (integer is also ok)
specifying the full width at half maximum value
that is used when summing up the contribution at
the location of a potential emission line; given
in pixels.

Keyword parameters:

noise

A scalar value specifying the noise. If this
variable is not given then it is determined from
regions in SPEC where there are no calibration
lines specified.

poldeg

The degree of the polynomial, that is used to fit
REFWAVE(REFPIXL).
The default value is:
1

niterate

A scalar integer specifying how many times the
solution is iterated.
The default value is:
1

findwidth

The width of the region, that is used to search
or the emission lines given in REFWAVE(REFPIXL);
iven in pixels.
The default value is:
fwhm

topwid

If set, then error messages are displayed using
DIALOG_MESSAGE, using this widget id as
DIALOG_PARENT, instead of MESSAGE.

logunit

Messages are saved to the file pointed to by this
logical file unit, if it is defined.

verbose

Set this parameter to a positive scalar integer to
make p3d write some information on STDOUT about
what is going on. The following four values are
acknowledged:

0

Writes no information at all. This is the
default.

1

Writes the more important information;
regarding subroutine configurations, mostly.

2

Writes most information; includes a more
verbose output than 1.

3

Writes all information, including
information on the execution state of GUI
subroutines. This may be a useful mode when
debugging the code.

error

This scalar integer returns an error code if set.
Any value different from zero means that an error
has occurred.

debug

No error handler is setup if this keyword is set.
The default is otherwise to setup an error handler
(using the routine CATCH), which makes each
subroutine exit quietly in case a bug is
encountered. Use this keyword when debugging p3d.

help

Set this keyword to show this routine
documentation, and then exit.

Output parameters:

identline

Returns an array with the indices of those lines in
REFWAVE, which have been found in SPEC, based on
the input array WAVELEN. The array is the section
of WAVELEN which is completely bounded by REFWAVE.

identpixl

Returns an array with the pixel number of
the arrays returned in IDENTLINE.

The purpose of this routine is to provide line-list filenames for
wavelength calibration. Since different instruments have different
ways to setup calibration lines, this routine allows the use of four
different methods to accomodate the different approaches, see below.
If no line-list file is found, the routine returns with an error.

For the second and third method, the format of the lamps file is as
follows:

Lines that begin with the character ';' are considered comments.
Columns are separated by white space.

Format specific to method 2:
For every combination of grisms/gratings, filters, and
detector-id, the first column specifies such a string. The second
column contains the line-list filename to use with that
combination. It is assumed that the default path is used.

Format specific to method 3:
For every calibration line, the first column specifies the shutter
keyword. The second column specifies the power supply. The third,
and final, column specifies the name of the calibration lamp (and
this string is also used to create the filename). It is assumed
that the default path is used. All data are read as strings.

The already configured instruments tend to use the following setups:

Method 1

Any instrument

Method 2

VIMOS, FLAMES

Method 3

PMAS/LARR

Method 4

PMAS/PPAK, VIRUS-P, GMOS

In each case, the line-list file is searched for using four different
approaches. Here <filename> contains a path, if any, and {filename}
has been stripped of the path. If any one approach is successful, the
routine continues:

i.

The specified file is tested for its existence (using the
IDL internal routine FILE_TEST). If the file exists, as it is
specified (with or without the path) then the filename is used as
it is.

The final filename becomes: <filename>

ii.

The user-parameter file path is appended as a prefix. This
approach is only attempted if a user-parameter file has been
specified and the 'arclinefile' parameter is set.

The final filename becomes: path(userparfile)/<filename>

iii.

The user-parameter file path is appended as a prefix to a
path-stripped filename. This approach is only attempted if a
user-parameter file has been specified and the 'arclinefile'
parameter is set.

The final filename becomes: path(userparfile)/{filename}

iv.

The parent directory of the user-parameter file is appended
as a prefix. This approach is only attempted if a user-parameter
file has been specified and the 'arclinefile' parameter is set.

The final filename becomes: path(userparfile)/../{filename}

v.

Using the p3d default path for line-list files; i.e.,
${p3d_path}/data/tables/linelists/...

The final filename becomes: !p3d_path/data/tables/{filename}

Here follows a description of the four different methods:

1. Using the keyword ARCLINEFILE or the user-parameter file

In the first method, the line list file(s) are defined in the keyword
ARCLINEFILE or in the user-parameter file. Any number of files can be
specified. If the user-parameter file is used, the rows must begin
with the string 'arclinefile'. If no such filename is specified, the
routine attempts to use method 2 instead.

2. The filename is determined using the file header, explicitly

In the second method, the instrument data-keywords list is searched
for the three keywords DETECTOR, FILTERNAME, and GRATNAME. If all
these keywords are present (also see below), a string is created
according to:
GNAME = h[GRATNAME] + '_' + h[FILTERNAME] + '_' + h[DETECTOR],
where h[] denotes the value as is found in the data header. In a last
step GNAME is searched for in the instrument lamps file; the
line-list <filename> is extracted from the 2:nd column in that file.

Note: If FILTERNAME is set to "n/a", GNAME is created using only the
keyword GRATNAME.

3. The filename is determined using the file header, implicitly

The third method is fairly specific to PMAS. In this approach the
data header is searched for information on which shutters and power
supplies are used, the header keywords are taken from the instrument
lamps file. The line-list files, which will be used, depend on which
power supplies are switched on, and on which shutters are open
(several can be chosen). The last column in the instruments lamps
file (that relates each combination of power supply and shutter
to a line-list file) contains the <filename> that will be used.

If HEADER = 1, this parameter should be the
filename of the input PMAS fits file.
If HEADER = 0, this is a FITS header string array.

lfilename

This is a scalar string with the filename of a file
that contains the calibration lamp-header keywords
that are used with the current instrument and data.

Keyword parameters:

arclinefile

An array of strings with the names of line-list
files.

kwrdlist

A two-dimensional string array holding the
instrument-specific keywords for a defined set of
keywords which are used to determine the
grating/grism setup.
KWRDLIST must have two columns.

userparfile

A scalar string specifying the name of an optional
user-parameter file, which contains keywords, be-
ginning with the string 'arclinefile'. The keywords
must point at existing files which, if present,
will be used instead of any header keywords. As in
the other parameter files lines preceeded by ';'
are considered to be comments. Entries of multiple
files are concatenated to create one line-list.

prompt

Prompt the user for the lamps to use.

header

Set this keyword if FILENAME is actually a variable
that contains the header keywords.

no_header

Specified if the necessary information is
not contained in the FITS header. In this
case the information has to be entered at
the prompt.

continuum

A scalar string that specifies the name of the
ontinuum lamp of the current instrument.
The default value is:
'HL'

wsep

If this keyword is set, the directory pointed at by
this variable is used to load data.

font

Set this scalar string to the name of the font to
use with the widget tool of this routine.

topwid

If set, error messages are displayed using
DIALOG_MESSAGE, using this widget id as
DIALOG_PARENT, instead of MESSAGE.

logunit

Messages are saved to the file pointed to by this
logical file unit, if it is defined.

verbose

Set this parameter to a positive scalar integer to
make p3d write some information on STDOUT about
what is going on. The following four values are
acknowledged:

0

Writes no information at all. This is the
default.

1

Writes the more important information;
regarding subroutine configurations, mostly.

2

Writes most information; includes a more
verbose output than 1.

3

Writes all information, including
information on the execution state of GUI
subroutines. This may be a useful mode when
debugging the code.

error

This scalar integer returns an error code if set.
Any value different from zero means that an error
has occurred.

debug

No error handler is setup if this keyword is set.
The default is otherwise to setup an error handler
(using the routine CATCH), which makes each
subroutine exit quietly in case a bug is
encountered. Use this keyword when debugging p3d.

This routine reads a dispersion mask file, that contains the
polynomial fitting parameters, and sets up a matrix with a
wavelength array for every spectrum.

Input parameters:

filename

A string specifying the filename of the file that
holds the dispersion mask data.

npix

A scalar integer specifying the number of
wavelength bins on the dispersion axis.

Keyword parameters:

bin

A scalar integer specifying the detector pixel bin
size.

daxis

Defines the dispersion axis. The default, 1, is in
the x-direction.
The default value is:
1

topwid

If set, error messages are displayed using
DIALOG_MESSAGE, using this widget id as
DIALOG_PARENT, instead of MESSAGE.

logunit

Messages are saved to the file pointed to by this
logical file unit, if it is defined.

verbose

Set this parameter to a positive scalar integer to
make p3d write some information on STDOUT about
what is going on. The following four values are
acknowledged:

0

Writes no information at all. This is the
default.

1

Writes the more important information;
regarding subroutine configurations, mostly.

2

Writes most information; includes a more
verbose output than 1.

3

Writes all information, including
information on the execution state of GUI
subroutines. This may be a useful mode when
debugging the code.

error

This scalar integer returns an error code if set.
Any value different from zero means that an error
has occurred.

debug

No error handler is setup if this keyword is set.
The default is otherwise to setup an error handler
(using the routine CATCH), which makes each
subroutine exit quietly in case a bug is
encountered. Use this keyword when debugging p3d.

help

Set this keyword to show this routine
documentation, and then exit.

Output parameters:

out

A two-dimensional array holding a wavelength array
of NPIX elements for every spectrum.