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 one- or 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.

Deletes numbered spectra in an input image.

Input parameters:

	inspec		A two-dimensional array of decimal type.
	rownum		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.

Resamples spectra from pixel units to wavelength-calibrated units.

This routine contains an algorithm that applies a dispersion correction on a stacked spectrum image, given a wavelength template, which is an image of the same size as the input image.

By default, the routine uses a one-dimensional drizzling algorithm. The one-dimensional drizzle algorithm is implemented using the approach of Fruchter & Hook (2002; eqs. 4 & 5).

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.

References

Bevington, P.R., Robinson, D.K. 1992 (2002), "Data reduction and error analysis for the physical sciences", 2nd (3rd) Ed. (McGraw Hill)

Fruchter, A.S., Hook, R.N. 2002, PASP, 114, 144, "Drizzle: A Method for the Linear Reconstruction of Undersampled Images"

Taylor, J.R. 1997, "An introduction to error analysis, the study of uncertainties in physical measurements", 2nd Ed. (University Science Books)

Input parameters:

	stack		A three- (or two-)dimensional array of stacked image data.
	waves		A two-dimensional array of floating point type, that specifies a value on the wavelength for every pixel.

Keyword parameters:

	dstack		If present, this is the error in STACK. The dimensions of DSTACK must be the same as those of STACK.
	incdelt		A decimal scalar (USE_IFU set) or an array of decimal values (USE_IFU unset) that specifies the wavelength bin width (dispersion) [Å/pixel].
	incrval		A decimal scalar (USE_IFU set) or an array of decimal values (USE_IFU unset) that specifies the the wavelength of the first pixel [Å].
	npix		A scalar integer (USE_IFU set) or an array of integers (USE_IFU unset) that specifies the number of wavelength bins.
	drizzle		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 starting pixel in the calculation of the output wavelength array when resampling pixel values to wavelength values. The value can be set to 'first', 'middle' [default], or 'last', to use of the first, the middle, or the last output pixel as a starting point. Alternatively, it can be set to an integer within the same range. Negative values, and values that are higher than the maximum number of pixels, short of one, are truncated. The default value is: 'middle'
	combined__out		A one-dimensional array with the combined wavelength calibrated spectrum (only calculated when USE_IFU is unset).
	combined__dout		The resulting error of the extraction spectrum COMBINED__OUT; this variable is only calculated when USE_IFU is unset and DSTACK is set.
	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.
	combined__oobpmask		If USE_IFU is unset and OBPMASK is set, this keyword contains the converted output bad-pixels mask image of the combined spectrum upon exit. The dimensions are the same as those of COMBINED__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.
	combined__osatmask		If USE_IFU is unset and OSATMASK is set, this keyword contains the converted output saturated-pixels mask image of the combined spectrum upon exit. The dimensions are the same as those of COMBINED__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 the pixel dispersion (CDELT) specifies the maximum allowed offset of the sky-emission lines, from the location provided in the dispersion mask. The unit is Angstrom. A higher value than the default of 2.0 * CDELT could be used in case the expected offset due to flexure is higher. (Otherwise such lines 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
	use_ifu		All spectra in STACK use the same dispersion solution when this keyword is set. Otherwise, they use different solutions.
	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 contents of the GUI are described in detail in the documentation of the tool p3d_cdmask. Here is a brief summary of what this routine does.

The GUI layout displays this input RSS image in the top panel. A "reference spectrum" plot is shown below that. The currently viewed wavelength range is shown between the two panels.

The initial dispersion mask is a set of straight lines given by the input line list. 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 it is 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 data of the RSS image is satisfactory, create the output dispersion mask and save it to a FITS file.

Format of files with lists of arc lines:

• Lines that begin with the character ';' are comments.

• Individual lines are specified with the wavelength and an optional relative intensity (the two values are separated by whitespace). The wavelength unit is by default Angstrom [Å]. The unit can be set by prefixing a line in the file header with the string "; wavelength unit: ". These are the available options:

  + "µm", "micrometer", "micron": Micro meter (1e-4 cm).

  + "nm", "nanometer": Nano meter (1e-7 cm).

  + "Angstrom", "Å" [default]: Ångström (1e-8 cm).

• All arc line entries are kept unless the intensity is lower than a limit value that is set with the keyword LINELISTILIMIT.

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 ARCLxxx 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 ARCLxxx 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: -4 Loads the cubehelix color table. -3 Loads the Califa project intensity color table, as defined September 2012. -2 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]].
	ch_start		This scalar decimal value defines the color when colortable = -4. The default value is: 0.5
	ch_rots		This scalar decimal value defines the rotation in color when colortable = -4. The default value is: -1.5
	ch_hue		This scalar decimal value defines the hue intensity scaling when colortable = -4. The default value is: 1.2
	ch_gamma		This scalar decimal value defines the gamma correction factor when colortable = -4. The default value is: 1.0
	residualcut		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
	linelistilimit		A scalar decimal value that sets the upper limit used when reading the arc line-list file.
	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).
	compactview		Set this keyword to use the lower spectrum plot region when showing quality plots; this is useful when there are very few spectra, in which case the upper draw widget will be too small to show plots in. The default value is: 0
	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
	use_ifu		Unset this keyword to work with spectrum orders instead of an IFU. In this case, it is necessary to create a dispersion function for each order separately. The default value is: 1
	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.
	cdebug		A keyword as DEBUG used with the called C routines.
	help		Set this keyword to show this routine documentation and then exit.

Handles widget events for p3d_wavecal_dispmask_gui.

.

Input parameters:

state

The state structure of p3d_wavecal_dispmask_gui.

Handles plot events of the dispersion-mask GUI.

Input parameters:

state

The state structure of p3d_wavecal_dispmask_gui.

Combines images for p3d_wavecal_dispmask_gui.

This is the routine where the actual wavelength calibration takes place. The wavelengths in the arc line 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 (IFU data) or a one-dimensional array (non-IFU data with separate spectra specified in LINEPOS). The value specify the number of calibration lines.
	linepos		A pointer array that either contains a two-dimensional array in the first index or a one-dimensional array for each spectrum order. The data hold the positions of each matched calibration line for all spectra; given in pixels.
	wavelength		A pointer array where each element contains a one-dimensional array with the corresponding wavelength of each emission line specified in the data of 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 cross-dispersion (spatial) axis. 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.
	orders		When NLINES is set to an array and the data in IMAGE are of multiple spectrum orders, this array specifies he order number of 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.

Computes various parameters using the grating equation.

Input parameters:

	lpmm		Groove density [lines per mm].
	blaze		Blaze angle [degrees].
	alpha		Grating angle normal to the incident beam.
	npixdisp		Number of pixels on CCD in the dispersion direction.
	m		Spectrum order. Note! -1 is FORWARD diffraction.

Keyword parameters:

	eta		Collimator/camera angle [degrees]. The default value is: 42°
	view		Plots the lambda and grating geometry.
	pixsize		The pixel size. The default value is: 0.015mm
	psf		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.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

	pix		An array with NPIXDISP elements: pixel number.
	lambda		An array with NPIXDISP elements; corresponding Lambda values [Å].
	lam_min		lambda_min, the minimum wavelength [Å].
	lam_cen		lambda_cen, the center wavelength [Å].
	lam_max		lambda_max, the maximum wavelength [Å].
	rdisp		The reciprocal linear dispersion [Å/mm].
	pdisp		The reciprocal linear dispersion [Å/pix].
	dlam		The spectrum resolution [Å].
	R		The resolving power; Lambda/d_Lambda.

Examples:

p3d_wavecal_grating_eq, 1200, 17.5, 2, 2048, 1, pix, lam, lmin, lcen, lmax, ldisp, rdisp, dlam, r, /v, /i, /flip

p3d_wavecal_grating_eq, 1200, 17.5, -48, 2048, 1, pix, lam, lmin, lcen, lmax, ld, rd, dl, r, /v, /i, /flip, /gr

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 for the emission lines given in REFWAVE(REFPIXL); given 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.
	identwave		An array with the wavelength of the positively matched lines.

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 five 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 final filename becomes: !p3d_path/data/tables/{filename}

Here follows a description of the five 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.

2b. The filename is read from the instrument keywords file

The third method is used when the three kewyords DETECTOR, FILTERNAME, and GRATNAME are unavailable in the instrument keywords file, but instead the keyword ARCFILE must be present and set to one of the existing files in the data/linelists directory.

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

The fourth 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.

4. Manual selection of one or several line-list files

In the fifth and final method, line-list files are selected manually, using a graphical user interface. Among the options these line-list <filenames> are found: HG (Mercury), NE (Neon), CD (Cadmium), AR (Argon), ThAr (Thorium Argon), user defined.

Input parameters:

	filename		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.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

	linelists		Filenames of emission line lists.
	lamp		Used emission line lamps.

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 that specifies 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
	npix_out		Returns the actually used NPIX; useful with non-IFU data.
	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.