Fits a two-dimensional Gaussian to an image using MPFIT.

Input parameters:

z

A two- or three-dimensional array with decimal values. The routine loops over the images Z[*, *, i] to find the best two-dimensional Gaussian fit.

Optional parameters:

dz

A two- or three-dimensional array of the exact same shape and type as Z. This value must contain the error of Z. If DZ is unpresent, then the error is calculated as: sqrt(abs(z)).

Keyword parameters:

	fwhm		A scalar decimal value that specifies the initial value on the FWHM. The default value is: 2.0
	x0		1. / 2] decimal value that specifies the initial the position on the x axis. The default value is: (n_elements(z[*, 0
	y0		1. / 2] decimal value that specifies the initial the position on the y axis. The default value is: (n_elements(z[0, *
	wav0		integer value that specifies the starting h bin for the fitting procedure when z is imensional array. The fitting first for incremented bins from wav0 to the end, after for decremented bins from wav0-1 to ning. The default value is: n_elements(z[0, 0L, *
	opar		Upon return this parameter contains a decimal value array with six columns and as many rows as Z has elements in its third dimension (==number of wavelengths). The six columns contain the following fitted values: opar[0] The background zero point opar[1] sigma on the x axis opar[2] sigma on the y axis opar[3] The normalization constant opar[4] The line center position, x0 opar[5] The line center position, y0
	valid		Upon return this variable contains an array with as many elements as there are rows as Z has elements in its third dimension (== number of wavelengths). Elements where a 2D fit were made are set to 1, the remaining elements are set to 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.

This routine sets up the application author information, which are the same for all tools of p3d, for use with APP_USER_DIR and APP_USER_DIR_QUERY.

Output parameters:

struc

A structure with the general information.

This routine extracts the CCD binning parameters XBIN and YBIN which must be present, in some form, in the input fits file header HDR. The name of the keywords in HDR are looked up in the instrument-keywords file KWRDLIST.

If XBIN and YBIN have the same keyword header, it is assumed that the keyword consists of three characters. XBIN is the first character of the header keyword field and YBIN the third character.

If both XBIN and YBIN are unavailable in the data header, the user-parameter is used; the corresponding parameters are ccdbinx and ccdbiny.

If either XBIN or YBIN is still zero, each value is set to 1.

Input parameters:

	kwrdlist		The name of a file, that contains a two-column list of parameters to use with p3d for the instrument in question.
	hdr		A string array with the fits file data keyword header.

Keyword parameters:

	xbin		A scalar integer that returns XBIN.
	ybin		A scalar integer that returns YBIN.
	althdr		An optional string array with a fits-file header.
	userparfile		A scalar string specifying the name of an optional user-parameter file; this file is only used if neither XBIN nor YBIN can be found in the data header.
	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.

Reads bin data from a plain-text or binary-table fits file; this routine reads all files written by p3d_misc_bins_file_write.

The plain-text or the fits file may be compressed using the tool gzip and the compression is identified through the then mandatory file suffix ".gz".

Plain-text file

The required format of a plain-text file is the following. The bin data may be preceded by comment lines identified using a doublet of one of the four following characters: "#", ";", "!", or "C"; for example, ";;". Thereafter, the file may contain up to three lines with auxiliary information; these lines are preceded with a single comment character followed by the parameter name and an equal sign. The three recognized auxiliary parameters are:

The remainder of the file is expected to contain three columns with as many lines as there are spatial elements in the considered row-stacked-spectrum or data cube file, i.e. NBINS lines: the //x// position, the //y// position, and the bin index. The columns must be separated with white space. The //x// and //y// positions are expected to be integers with positions of data cubes, but can in other cases assume any decimal value. A bin valued – 1 is non-existent and must not be present in the file, such elements are, however, added to the output.

Fits file

The required format of a binary-table fits file is the following. At first the routine attempts to read the extension containing the bin map. The default extension is 'BIN_TABLE' or 'VORONOI_TABLE', but it is possible to specify a different extension using the keyword EXTENSION. If the keyword EXTENSION is not used and no map data are found in the default extension, a second attempt is made to read data from the first extension. Three auxilary parameters are read from the header of the bin map extension:

The binary table is expected to contain three columns that each has NBINS rows; the names of the columns are by default assumed to be: BINIDX or BINNUM, X, and Y, which contain the bin index, and the //x// and //y// positions of each spatial element. Alternative names can be specified with the keywords COL_BINIDX, COL_X, and COL_Y, respectively. The //x// and //y// positions are expected to be integers with positions of data cubes, but can in other cases assume any decimal value. A bin valued – 1 is non-existent and must not be present in the file, such elements are, however, added to the output.

Input parameters:

filename

A scalar string with the name of the bins file to read.

Optional parameters:

nbins

A scalar integer with the expected number of bins.

Keyword parameters:

	extension		- A scalar string that specifies the name of the fits-file extension containing the bins map. The default value is 'VORONOI_TABLE.' The default value is: 'BIN_TABLE' || 'VORONOI_TABLE'
	col_binidx		- A scalar string that specifies the name of the column with the bin data. The default value is: 'BINIDX' || 'BINNUM'
	col_x		A scalar string that specifies the name of the column with the x positions. The default value is: 'X'
	col_y		A scalar string that specifies the name of the column with the y positions. The default value is: 'Y'
	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:

bindata

A scalar IDL structure with the contents of the read file. The eight tags include the following: binidx the bin index for each spatial element. x the //x// position for each spatial element. y the //y// position for each spatial element. binidx_uniq an sorted array with all bin indices used in binidx; negative entries are not considered. nbinidx_uniq a scalar integer with the number of elements in binidx_uniq. binlow see above. binupp see above. targetSN see above.

Writes bin map data to a plain-text or binary-table fits file.

Input parameters:

	filename		A scalar string with the name of the bins map file to write.
	binlow		A scalar integer with the lower bin used in the input file.
	binupp		A scalar integer with the higher bin used in the input file.
	targetSN		A scalar decimal value with the target signal-to-noise value used in the binning.
	bindata		An IDL structure with the bins and the //x// and //y// positions of each spatial element: bins, x, y.

Keyword parameters:

	source		A scalar string with the name of the used source cube or RSS file.
	revision		A scalar integer with the revision of TOOL.
	tool		A scalar string with the name of the tool, whose name is added to the output file.
	append		Set this keyword to append the Voronoi bin map to a new extension in an already existing fits file.
	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.

This routine checks whether the fits header in the supplied filename contains the required detector id. This is useful with instruments which have several detectors (such as VIMOS, GMOS-S/N and IMACS).

If the instrument keywords file does not contain the p3d keyword specifier 'DETECTOR' then the routine just exits (for all instruments that only have one detector).

Input parameters:

	file		The filename of the data fits file to check.
	ndetectors		A scalar integer that specifies the total number of detectors.
	detector		A scalar integer that specifies the id of the current detector.
	kwrdlist		A scalar string that specifies the name of a file that contains a list of instrument-specific keyword names.

Keyword parameters:

	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.

This routine checks whether all the fits headers of the supplied filenames contain the same observation block (OB) identification string. This routine is only used with VIMOS, and will prevent the accidental use files that belong to different OBs.

If the instrument keywords file does not contain the p3d keyword specifier 'OBID' then the routine exits immediately (for all non-VIMOS instruments).

Input parameters:

	files		A string array with the names of fits files. At least two files must be specified!
	type		A string array with the same number of elements as FILES. Each element of TYPE is a four-character string.
	kwrdlist		A scalar string that specifies the name of a file that contains a list of instrument-specific keyword names.

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.

This routine checks whether the zeroth extension FITS file header in supplied files contain a header keyword corresponding to RAWREQDTYPE (when RAW is set) or REQTYPE – as are listed in the instrument-specific keywords file – that equals the value of the variable TYPE_REQUIRED.

The routine just returns with no message if the instrument keywords file does not contain the p3d keyword specifiers 'RAWREQDTYPE' or 'REQTYPE'.

Input parameters:

	filenames		An array of strings with the names of files to check.
	type_required		A scalar string that is required in the FITS file header keyword corresponding to the entry REQTYPE in the instrument-specific keywords file.
	kwrdlist		A scalar string that specifies the name of a file that contains a list of instrument-specific keyword names.

Keyword parameters:

	raw		Set this keyword to use the instrument-specific keyword RAWREQDTYPE instead of REQDTYPE.
	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.

This routine provides a GUI for choosing an instrument, before launching the main panel GUI.

Input parameters:

defv

A structure containing default paths and additional parameters such as the window title for each instrument.

Keyword parameters:

	font		Set this scalar string to the name of the font to be used with all widget components of this tool.
	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.

Output parameters:

odata

A structure containing the chosen instrument parameters.

Side effects:

The default widget font is changed if the keyword FONT is used.

Loads a color table, according to the input, and also defines a set of pre-defined colors for use with the p3d suite of tools.

Originally, IDL included 40 color tables. More recent versions of IDL also include a set of the ColorBrewer color tables. Michael Galloy has since earlier created IDL versions of the ColorBrewer color tables. p3d includes the updated version of the ColorBrewer color tables; the file "brewer.tbl" is placed in the resource directory.

The ColorBrewer color tables, or any other similar table file, can be used with p3d by specifying the color table as a string containing the color-table index to use within the table file and the full table-file path. As an example:

p3d_misc_colortable, '25,brewer.tbl'

Links

The ColorBrewer color tables: http://colorbrewer2.org/ http://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_intro.html

The updated IDL Brewer table web site: http://michaelgalloy.com/2008/02/21/updated-brewer-color-tables.html

An earlier implementation of the Brewer color tables for IDL: http://michaelgalloy.com/2007/10/30/colorbrewer.html

Input parameters:

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

Keyword parameters:

	bottom		A scalar integer that specifies the lower index of the color table used in the scaling of the color map. The upper index is always the maximum value (!d.table_size); this value should be set >= 2 (7 is the optimum choice) to allow some room for the reserved colors of p3d. The default value is: max(index) + 1
	index		An array of integers specifying which color indices should be used for the reserved colors. It does not make sense to make index larger than five elements. Also note that the largest index is used to determine BOTTOM (in the default state). Try to choose the lowest number of indices possible. The default value is: 0, 1, 2, 3, 4, 5, 6
	indv		A seven-element array of integers that specifies which color indices should be used for the P3D reserved colors. If INDEX has >= 7 elements, then INDV is equal to INDEX[0:6]. If INDEX has fewer elements then all higher indices of INDV are set to the highest value of INDEX. For instance, with INDEX = [0, 1, 2] INDV = [0, 1, 2, 2, 2, 2, 2].
	define		If this keyword is set then a set of reserved colors are loaded into the color table. Up to five colors are loaded, if the number of elements in INDEX permits. The colors are: index[0] black index[1] white index[2] red index[3] green index[4] dark green index[5] blue index[6] dark blue
	name		This output keyword returns the name of the loaded color table.
	colors		This output keyword structure returns the loaded color arrays as: colors.red, colors.green, and colors.blue.
	offset		A scalar integer that returns an offset depending on how many additional color tables have been. defined. Currently OFFSET = 3.
	ch_start		Scalar decimal value (used if COLORTABLE = -4). The default value is: 0.5
	ch_rots		Scalar decimal value (used if COLORTABLE = -4). The default value is: -1.5
	ch_gamma		Scalar decimal value (used if COLORTABLE = -4). The default value is: 1.0
	ch_hue		Scalar decimal value (used if COLORTABLE = -4). The default value is: 1.2
	invert		Set this keyword to invert the color table.
	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.

Side effects:

Modifies the color table.

This routine extracts the CCD binning parameters XBIN and YBIN which must be present, in some form, in the input fits file header HDR. The name of the keywords in HDR are looked up in the instrument-keywords file KWRDLIST.

If XBIN and YBIN have the same keyword header then it is assumed that the keyword consists of three characters. XBIN is the first character of the header keyword field and YBIN the third character.

If both XBIN and YBIN are unavailable in the data header, then the user-parameter is used; the corresponding parameters are ccdbinx and ccdbiny.

If either XBIN or YBIN is still zero, then each value is set to 1.

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.

Returns a decomposed-colors value for the specified color name. Color names are taken from the X11 file: "/usr/share/X11/rgb.txt".

Input parameters:

str

A scalar string with the color name.

Output parameters:

value

A scalar long value with the color value. The value 0 is returned if the color name was unidentified.

Find the optimal offset of array VECA relative to array VECB. The optimal offset is calculated by maximizing the correlation function of the two arrays – using the NASA astro-lib functions CORREL_IMAGES and CORREL_OPTIMIZE.

Input parameters:

	veca		A one-dimensional array of decimal type.
	vecb		A one-dimensional array of decimal type.

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:

doffset

A scalar decimal value containing the optimal offset of VECB relative to VECA.

This routine converts a three-dimensional data cube into a two-dimensional row-stacked spectrum (RSS) data image.

Parts are implemented in C for improved performance with huge data sets, such as is the case with MUSE datacubes.

Input parameters:

cube

A three-dimensional data cube, which is formatted as: [nsn, nwe, # of wavelengths], where nsn is the number of elements in the South->North direction and nwe the number of elements in the West->East direction.

Optional parameters:

dcube

A three-dimensional error data cube. Formatted as CUBE.

Keyword parameters:

	angle		A scalar integer value that defines how the spatial axes are oriented in the cube. The unit is degrees [°]: ANGLE = 0 North is up and East left ANGLE = 90 North is left and East down ANGLE = 180 North is down and East right ANGLE = 270 North is right and East up If ANGLE assumes any other value, the ANGLE = 0 case is used. The default value is: 0
	daxis		Defines the dimension of the dispersion direction in the output spectrum image (and PREDATA); must be set to either 1 or 2. The default value is: 1
	predata		A two-dimensional array with the same dimensions as the output variable RSSDATA. This variable is used to copy calibration and sky spectra back to the output data image. This way the resulting array can be made to look exactly as the original RSS array.
	use		An integer array that specifies which elements to copy to the RSS image. Useful when doing the errors array immediately after the data array.
	posfile		A scalar string with the fiber-position table filename corresponding to the RSSDATA variable. Position-table data are calculated when POSFILE is unset, see POSDATA.
	posdata		This scalar structure is only set when POSFILE is unset. In this case, the spatial-elements positions are calculated automatically and row and id numbers are set as increasing numbers. The lens size is set to 1.0. All arrays are returned in a structure with the following tags: rownum, id, xpos, ypos, and lens_size. All constant spectra are removed from the returned RSS image; the id array refers to the pre-removal image.
	sifunum		This keyword is used with p3d_misc_read_postable.pro.
	noremove		If unset, then zero-arrays are removed before the POSDATA structure is returned. The default value is: 0
	crebuild
	noC
	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.
	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:

rssdata

A two-dimensional array with RSS-data. The data format is: DAXIS = 1: [# of wavel., # of spatial elements] DAXIS = 2: [# of spatial elements, # of wavel.]

This routine sets up a "Cubehelix" color table using the recipe of D. A. Green.

References

Green, D. A. 2011, "A colour scheme for the display of astronomical intensity images', Bulletin of the Astron. Soc. of India, 39, 289

Links

The Cubehelix color table has a web site: http://www.mrao.cam.ac.uk/~dag/CUBEHELIX/

The paper can be downloaded here: http://adsabs.harvard.edu/abs/2011arXiv1108.5083G

This routine is based on the IDL-version of cubehelix that was written by James R. A. Davenport: http://www.astro.washington.edu/users/jrad/idl.html

Keyword parameters:

	start		Color; 1=red, 2=green, 3=blue. For example, 0.5=purple. The default value is: 0.5
	rots		Rotations in colour; typically -1.5-1.5. The default value is: -1.5
	hue		Hue intensity scaling (in the range 0 (B+W) to 1 to be strictly correct, larger values may be OK with particular start/end colours). The default value is: 1.2
	gamma		The gamma correction for the intensity. The default value is: 1.0
	ncolors		A scalar integer specifying the number of colors to use. The default value is: !d.table_size
	bottom		A scalar integer that specifies the lower index of the colortable that is used in the scaling of the colormap. The upper index is always the maximum value (!d.table_size). This value should be set >=2 (5 is the optimum choice) to allow some room for the reserved colors of P3D. The default value is: max(index) + 1
	invert		Set this keyword to invert the color table.
	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.

Side effects:

Modifies the colortable.

This routine takes an input array and calculates a limited range of values using a histogram function and a percentage. For instance, if the percentage is 95.0 (95%) then the lowermost 2.5% and uppermost 2.5% of all pixel values are left outside the limit (RANGE).

Input parameters:

array

An array of decimal type. This is the data array that is used to calculate the range values. It can have any dimensions.

Keyword parameters:

	percentage		RANGE is calculated to embrace with many percent of all pixel values in ARRAY. The default value is: 95.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:

range

A two-element array returning the lower and upper limits calculated in this routine.

This routine retrieves a four-element array (DETSEC) that contains the array indices of the CCD data-area (i.e. to remove prescan- and overscan-regions). There are four ways to set DETSEC, in order of priority they are:

The format of DETSEC is: [x_start:x_end, y_start:y_end]

If the input parameter HDR contains headers of several files (number of rows > 1) or if HDR contains the keywords CETSECx (where x is the block number), DETSEC is an array with 4 columns and as many rows as there are file headers.

In the case that HDR contains several rows, DETSEC must be specified as DETSEC_1, DETSEC_2, ..., for each case described above.

Input parameters:

	hdr		An string array with the fits-file header of the file that should be parsed for the detector area.
	kwrdlist		A scalar string with the name of a file, that contains a two-column list of p3d-names and instrument-specific names for fits-header keywords.
	parfile		A scalar string with the name of a file, that contains a two-column list of instrument-specific parameters.

Keyword parameters:

	althdr		An optional string array with the fits-file header of the file that should be parsed for the detector area.
	detector		A scalar integer that specifies the currently selected detector; DETECTOR is a zero-based value. The default value is: 0
	userparfile		A scalar string specifying the name of an optional user-parameter file, that could contain the keyword 'detsec'. If it does then the value of that keyword is used to trim the data. If there are several 'detsec'-lines in the file then the first is used.
	blocknx		An nblocks-element integer array with the total number of pixels on the x axis. This array is only returned if the instrument parameter 'blockarecombined' is set.
	blockny		An nblocks-element integer array with the total number of pixels on the y axis. This array is only returned if the instrument parameter 'blockarecombined' is set.
	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:

	detsec		A four-element integer array that specifies the detector region to use on the CCD. If HDR contains several rows then DETSEC will have as many rows.
	odetsec		Like DETSEC, but this array has not been flipped on the dispersion axis.

Provides a support routine for p3d_misc_detsec.

Open a FITS file in E3D format and return an RSS array, and position table vectors and spaxel shape and size

Keyword parameters:

	rss		(float) 2D array
	xpos		(float) 1D array with spaxel x-positions
	ypos		(float) 1D array with spaxel y-positions
	size		(float) size of a spaxel
	shape		(int) spaxel shape. 0: square, 1: circular
	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.
	error		Returns an error code if set
	verbose		Show more information on what is being done
	debug		The error handler is not setup if debug is set.
	help		Show this routine documentation, and exit

Data reduced with the p3d tool can be saved in the Euro3D format using this routine. The inputs are the reduced data array and the associated position table/vectors. The output is a single Euro3D format file.

Euro3D is a common data format designed to store the reduced data from most IFU instruments in a file conforming to the FITS standard. The resulting Euro3D-data files can be visualized and analysed with a dedicated (non-IDL based) tool, viz. E3D, which can be obtained at the E3D web site.

References

Kissler-Patig, M.; Copin, Y.; Ferruit, P.; Pécontal-Rousset, A.; Roth, M. M. 2004, Astronomische Nachrichten, 325, Issue 2, p. 159-162, "The Euro3D data format: A common FITS data format for integral field spectrographs"

Links

http://www.aip.de/Euro3D/E3D/

Input parameters:

	rss		(float) 2D array
	xpos		(float) 1D array with spaxel x-positions
	ypos		(float) 1D array with spaxel y-positions
	e3dname		(string) name of the output e3d file

Keyword parameters:

	hdr		(string).
	stat		(float) 2D array of the same properties as RSS.
	shape		(int) spaxel shape. 0: square, 1: circular
	size		(float) size of a spaxel
	ctype		(string) type of spectral world coordinate system
	crval		(float) wavelength of first pixel
	cdelt		(float) wavelength step per pixel
	compress		If this keyword is set then the output file is compressed, if possible, using gzip.
	nthreads		A scalar integer that specifies how many threads to use in the parallelized output file compression. The default value is: max
	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.

The purpose of this routine is to display an error message once an error handler has been setup using CATCH. The error is shown, and an open file is closed (optionally).

Input parameters:

error_status

An integer with the error code.

Keyword parameters:

	rname		- The name of the routine where the error occurred. The default value is: 'p3d_misc_logger'
	unit		A scalar integer with the value of a file unit, that, if it is open, is closed.
	topwid		If set, then the error message (iff ERROR) is shown using a dialog instead of printing the message on the console.

This routine escapes the characters [, ], {, and } in a string.

Input parameters:

value

A scalar string.

Output parameters:

escape_value

A scalar string with escaped characters as described above.

This routine determines which spectrum extraction method is to be used. If no user-parameter file is specified then the default value 'tophat' is returned. If a user-parameter file is specified (as the first argument) then it is searched for the parameter name KEYWORD ['methodextract'] and thereafter reads its value. Allowed values of KEYWORD are 'tophat' and 'optimal'.

In the creation of a trace mask it might be desirable to calculate cross-dispersion line profiles even though the extraction method is 'tophat'. If this is the case then use the keyword /TRACEMASK (see below).

Optional parameters:

userparfile

A scalar string specifying the name of an optional user-parameter file, that may contain the keyword KEYWORD (the default of KEYWORD is 'methodextract'). This keyword may, in turn, be set to one of the two following options: 'tophat' default standard spectrum extraction 'optimal' to use the optimal extraction method of Horne (1986).

Keyword parameters:

	keyword		- USERPARFILE is scanned for this keyword. The default value is: 'methodextract'
	tracemask		If set, then USERPARFILE is scanned for the entry 'trace_calcprofs', that can be set to either 'yes' or 'no'. If it is 'yes' then method is set to optimal. The idea with this option is to allow cross-dispersion line profiles to be calculated even though the method of extraction is set to 'tophat'.
	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:

method

A scalar string containing the used spectrum extraction method; this is either "tophat" or "optimal".

From a list of filenames this routine finds the filenames of all blocks for multi-block instruments (PMAS 4kx4k CCD).

If the filename contains two colons, such as in '*:??:*', then filename is considered to be a time-formatted filename. In this case the original filename is read from the header keyword ORIG_FILENAME_KWD ['FILENAME'], and that original string is used instead (it requires much less work).

Input parameters:

	filename		An array of strings with raw-data filenames.
	fsfx		An array of strings with as many elements as FILENAME. This variable contains a filename suffix that is appended to FILENAME to get the complete filename.
	nblocks		A scalar integer that indicates the number of blocks of the current instrument data. This routine returns immediately if NBLOCKS is equal to 1.
	bsfx		A string array with NBLOCKS elements, which contains a block-specific string that is used to identify files of each block.

Keyword parameters:

	blocksarecombined		If this keyword is set the routine returns mediately, as all blocks are contained in the me raw-data image.
	orig_filename_kwd		This keyword provides a name for raw-data files that also e of an originally used filename. The default value is: 'FILENAME'
	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:

	nfilename		A string array with the dimensions [n_elements(FILENAME), NBLOCKS], which upon return contains a unique list of filenames (columns) for each block (rows).
	nfsfx		A string array with the same dimensions as NFILENAME, which upon return contains the filename suffix for each file in NFILENAME.

For a specified file, this routine decides which path to use with that particular file.

p3d uses many input files, which can be located to either one of the p3d directories or any other directory. It is cumbersome for the user to always specify the full path of each and every file, in particular if one wants to copy the files and continue the data-reduction work on another computer with a different directory structure.

This routine simplifies the filename handling. Specifying either one, or an array of, filename(s), this routine searches the following paths for the file, the first occurrence is used:

The routine returns the replacement filename, or a full array of replacement filenames.

Input parameters:

filename

A scalar string, or an array of strings, that contains the filename(s), which is/are searched for by this routine.

Keyword parameters:

	curdir		If this keyword is set, the file FILENAME is searched for in the current directory.
	altdir		This scalar string, or array of strings, must contain a list of alternative directories where FILENAME is searched for. Any entry that contains an empty string is ignored.
	dlldir		If this keyword is set, the file FILENAME is searched for in the p3d default line-list directory: ${p3d_path}/data/tables/linelists/. The respective default line-list file is attempted in case that the (case-insensitive) FILENAME == 'lores' || 'hires', i.e.: 'telluric_lines_lores.dat' replaces 'lores', and 'telluric_lines_hires.dat' replaces 'hires'.
	defstr		A scalar string that should contain an informative text regarding which kind of file is searched for. The default value is: ''
	replacefull		Set this keyword to allow the replacement of an already specified path with another path.
	allownofile		Set this keyword to return without an error when a file does not exist.
	found		Returns a integer scalar, or an array, with as many elements as FILENAME, specifying if a file was found (1) or not (0).
	allowcompressed		Set this keyword to also look for the compressed file if FILENAME is non-compressed, using gzip ('.gz'), or vice versa.
	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.

For a defined input value this routine checks if this value exists in a list of defined dead, unused, or possibly unused fiber values. If it does then the value is decremented/incremented until a value is found that is not in the list. The found value is then returned.

Input parameters:

	specnum		Initial spectrum to look for an emission line in (in the cross-dispersion direction). This value is checked against the values in the DEADFIBERS array. If it is present there then the value is decreased until a value is found that is not in that array. If the value 0 is reached then the search is started over by increasing the value, starting with the initial value, until a non-dead number is found. The maximum value is given by MAXNUM. The following -must- be satisfied: 0 <= SPECNUM < MAXNUM.
	maxnum		A scalar integer specifying the maximum allowed number + 1 of the return value.
	deadfibers		A one-dimensional array of integers specifying which fiber positions are to be interpolated instead of fitted. If DEADFIBERS is not specified then the input value SPECNUM is returned as is.

Keyword parameters:

	logstr		Returns a scalar string with the outcome of the value search for logging purposes.
	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:

ret

A scalar integer with the number of the spectrum to use.

Adds a keyword, optionally with a very long name, and its value and comment to a fits-header string array.

The usual routine to add a parameter to a FITS file header is fxaddpar, but it doesn't handle very long keyword names.

Input parameters:

	hdr		A string array with the fits file data keyword header.
	str		A scalar string specifying the keyword which value will be added to HDR.
	value		A scalar number or string, which is to be added to HDR.

Optional parameters:

comment

A scalar string with a comment that is added to the header.

Keyword parameters:

	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		Show more information on what is being done.
	error		Returns an error code if set.
	debug		The error handler is not setup if debug is set.
	help		Show this routine documentation, and exit.

Side effects:

Edits the contents of the HDR keyword.

This routine extracts the value with the keyword name STR from the fits header array HDR. If possible, the output value is converted to a double or a long. If the value is the same when evaluated as a double and a long then the long value is returned. If any error is encountered or if the keyword does not exist in HDR, -1 is returned.

Input parameters:

	hdr		A string array with the fits file data keyword header.
	str		A scalar string specifying the keyword which value will be read from HDR.

Keyword parameters:

	ahdr		A string array with an alternative fits-file keyword header that is used if the keyword STR is not found in HDR.
	index		A two-element integer array with the position of STR in HDR [0], or AHDR[1]; the default value is -1.
	converthourtodeg		If this keyword is set an attempt is made to convert a number that is specified in hour format (-03:12:59.120; degrees, minutes, hours) to hours.
	convertstrtodeg		If this keyword is set an attempt is made to convert a number that is specified in hour format (-03:12:59.120; degrees, minutes, seconds) to degrees.
	convertstrtosec		If this keyword is set an attempt is made to convert a number that is specified in hour format (-03:12:59.120; hours, minutes, seconds) to seconds.
	noconvert		No attempt to convert the result to an integer or a decimal value is attempted if this keyword is set.
	insertcolons		If this keyword is set, colons are inserted in the read number as: 031259.120 => 03:12:59.120. And then the conversion can take place.
	comment		Returns the read comment.
	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		Show more information on what is being done.
	error		Returns an error code if set.
	debug		The error handler is not setup if debug is set.
	help		Show this routine documentation, and exit.

Output parameters:

ret

A scalar value containing the returned value.

Reads and returns the wavelength array and the extinction array of a provided atmospheric-extinction calibration file.

The atmospheric extinction file may be a binary-table fits file or a plain-text file; fits files may be compressed using gzip, bzip2, or compress, and plain-text files with gzip. An attempt is always made to read the file as a fits file. If this fails, then a second attempt is made to read it as a plain-text file. Required properties are:

• The input file is a binary-table fits file:

  The wavelength array unit is extracted from the header of the fits file; specifically from the first extension. The extinction array, and its error, if available, are assumed to be in the unit mag/airmass.

• The input file is a plain-text file:

  The text file may contain a header where each line begins with a semicolon, such lines are considered to be comments. The first column of the remaining lines of the file is assumed to be the wavelength. The second column the extinction, and the third column, if available, the error of the extinction.

  The unit of the wavelength can be specified using the WAVEUNIT keyword; allowed values are 'angstrom', 'angstroms', 'nanometer', and 'nm'. If the wavelength unit is not provided, then it is guessed as follows. If min(wavelength) < 700, then WAVEUNIT is set to 'nanometer', otherwise WAVEUNIT is set to 'angstroms'.

  The unit of the extinction array, and its error, is assumed – and also expected – to be mag/airmass.

The units of the output arrays are as follows:

Keyword parameters:

	ext_wavelength		Upon output this keyword contains the read wavelength array, in [Angstrom] ([Å]).
	extinction		Upon output this keyword contains the read extinction, in [mag/airmass].
	ext_error		Upon output, and if the property is available, this keyword contains the read extinction error, in [mag/airmass].
	waveunit		A scalar string that can be used to define the wavelength unit of plain-text atmospheric extinction calibration files. See the description above for a list of allowed values.
	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.

Reads and returns the wavelength array and the flux of a provided standard-star calibration file.

The standard-star spectrum input file may be a binary-table fits file or a plain-text file; fits files may be compressed using gzip, bzip2, or compress, and plain-text files with gzip. An attempt is always made to read the file as a fits file, if this fails, then a second attempt is made to read it as a plain-text file. Required properties of spectrum data are:

• The input file is a binary-table fits file:

  The units are extracted from the header of the fits file.

• The input file is a plain-text file:

  An attempt is made to extract the units from the text file. Data are provided in whitespace-separated columns following an optional header. If the text file contains a header that begins with a semicolon, then lines that contan two semicolons are considered to be comments. Lines that begin with only one semicolon may contain additional information in two columns that are separated by whitespace; the first column contains the property value and the second column the property name. The following properties are recognized:

  catalog	A string that specifies the used configuration, see the description below for more details.
  waveunit	A string that specifies the unit of the wavelength array. The recognized values are: 'nanometer', 'nm', 'angstrom', and 'angstroms'.
  fluxunit	A string that specifies the unit of the flux array. The recognized values are: 'mag', 'abmag', or 'm'; 'erg/cm/cm/s/A', or 'f', and 'erg/cm/cm/s/A*10**-16' or 'f16'.
  name	The name of the standard star.
  altname	An alternative name of the standard star. This entry may be present multiple times.

  Plain-text input files may be used that do not contain these properties; these files may be compressed with gzip, but they must contain the suffix '.gz'.

  It is possible to specify the configuration using a scalar string with the keyword CATALOG. The following values of CATALOG are recognized:

  • 'fits_eso' – ESO-formatted FITS files:

    The data are contained in FITS files with three columns: wave, flux, and bin. In this case FLUXUNIT = 'erg/cm/cm/s/A*10**-16' and WAVEUNIT = 'Angstrom'.

  • 'text_eso' – ESO-formatted plain-text files:

    The data are contained in plain-text files with three columns: wave, flux, and bin. In this case, FLUXUNIT = 'erg/cm/cm/s/A*10**-16' and WAVEUNIT = 'Angstrom'. This setup is also used when plain-text files use CATALOG = fits_eso; this is the case if a read and modified fits_eso fits file is saved as a plain-text file inside the spectrum viewer.

  • 'iraf' – IRAF standard-star calibration files:

    The data is provided in three columns as: wavelength, magnitude, bandpass width. In this case, FLUXUNIT = 'abmag' and WAVEUNIT = 'Angstrom'.

  • 'oke' – Oke (AJ, 99, 1621, 1990) standard stars:

    The data is provided in either three columns as: wavelength, magnitude, bandpass width. Or in four columns as: wavelength, flux [erg/cm²/s/A*10**-16], flux [milli-Jy], bandpass width. In this case, FLUXUNIT = 'abmag'||'erg/cm/cm/s/A*10**-16' and WAVEUNIT = 'Angstrom'.

  • Free-format text files:

    To a limited degree this routine can also read free format files. The data are read according to the following criteria:

    The input keyword ECALC is set	Data are provided in either three columns as: wavelength, flux, flux error. Or in four columns as: wavelength, flux, flux error, band-pass width. In this case it is important to also specify the wavelength unit (WAVEUNIT) and the flux unit (FLUXUNIT). An attempt is made to guess these units, see below, but the guess might be incorrect.
    The input keyword ECALC is unset	Data are provided in either two columns as: wavelength, flux. Or in three columns as: wavelength, flux, band-pass width. In this case it is important to also specify the wavelength unit (WAVEUNIT) and the flux unit (FLUXUNIT). An attempt is made to guess these units, see below, but the guess might be incorrect.

    If the wavelength unit is not provided then it is guessed as follows. If min(wavelength) < 700 then WAVEUNIT = 'nanometer' else WAVEUNIT = 'angstroms'.

    If the flux unit is not provided then it is guessed as follows. If max(flux) < 0.001 then FLUXUNIT = 'erg/cm/cm/s/A', else if max(ss_flux) < 10 then FLUXUNIT = 'erg/cm/cm/s/A*10**-16', else FLUXUNIT = 'abmag'.

The units of the output arrays are as follows:

ESO provides some very useful pages on standard stars:

http://www.eso.org/sci/observing/tools/standards.html

http://www.eso.org/sci/observing/tools/standards/spectra.html

Find more information on FITS-format standard-star files, as well as standard-star calibration files at the following links:

http://www.stsci.edu/hst/observatory/cdbs/astronomical_catalogs.html

http://www.stsci.edu/hst/observatory/cdbs/calobs.html

http://www.stsci.edu/hst/observatory/cdbs/calspec.html

IRAF-formatted standard-star data can be found at the following links:

http://iraf.net/

http://www.naoj.org/Observing/Instruments/FOCAS/Detail/UsersGuide/Observing/StandardStar/Spec/SpecStandard.html

Oke-formatted standard star data can be found at the following links:

http://www.caha.es/pedraz/SSS/Oke/oke.html

http://www.eso.org/sci/observing/tools/standards/spectra/okestandards.html

References

(Classical references include these ones, see the links above for further information)

Bohlin, R.C. 1996, AJ, 111, 1743, "Spectrophotometric Standards From the Far-UV to the Near-IR on the White Dwarf Flux Scale".

Bohlin, R.C., Dickinson, M. E., & Calzettti, D. 2001, AJ, 122, 2118, "Spectrophotometric Standards from the Far-Ultraviolet to the Near-Infrared: STIS and NICMOS Fluxes".

Oke, J.B. 1990, AJ, 99, 1621, "Faint spectrophotometric standard stars".

Keyword parameters:

	catalog		A scalar string that can be used with plain-text standard-star spectrum calibration files to specify the format of the file when the file does not contain a format header. The allowed values are 'iraf', 'oke', 'hst', 'text_eso', 'fits_eso'. See the description above for more details.
	ss_wavelength		Upon output this keyword contains the read wavelength array, in [Angstrom] ([Å]).
	ss_bpw		Upon output, and if the property is available, this keyword contains the read bandpass width, in [Angstrom] ([Å]).
	ss_flux		Upon output this keyword contains the read flux, in [erg/cm/cm/s/Å].
	ss_errorflux		Upon output, and if the property is available, this keyword contains the read flux error, in [erg/cm/cm/s/Å].
	fluxunit		A scalar string that can be used to define the flux unit in plain-text calibration standard-star spectrum files. This keyword is only used when CATALOG is not provided. See the description above for a list of allowed values.
	waveunit		A scalar string that can be used to define the wavelength unit of plain-text standard-star spectrum calibration files. This keyword is only used when CATALOG is not provided. See the description above for a list of allowed values.
	ofilename		A scalar string, which, if present, data are saved to a plain-text file with this name. The file is compressed if COMPRESS is set.
	use		An integer array with as many elements as the read data; zero elements indicate removed entries. This keyword is only used when OFILENAME is set.
	compress		If this keyword is set the output text file is compressed using gzip.
	ecalc		This scalar-integer output keyword specifies if the output data contain the flux error. For free-format plain-text files this keyword is also used as an input keyword, specifying if the data contain the flux error or not.
	target_extension		A scalar integer with the extension to read in ulti-extension files.
	target_id		A scalar string used to select the default extension in multi-extension files; this keyword is only used if TARGET_EXTENSION is unset.
	target_extname		A scalar string returning the name of the used extension; set when TARGET_EXTENSION is set.
	target_cal		A scalar string used to select the default extension in the multi-extension calibration file.
	font		A scalar string with the name of the font to use in the extension-selection widget tool.
	logunit		Messages are saved to the file pointed to by this logical file unit, if it is defined.
	topwid		If set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
	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.

Provides a GUI to select the extension to use in a multi-extension standard-star file.

Input parameters:

extname

extension string array.

Shifts an image by a fractional value on either axis. If the offset is not an integer, then the value at the offset is calculated by (two-dimensional) bilinear interpolation.

Note: The error calculation is very rudimentary!

Input parameters:

	image		A two-dimensional decimal value array that contains the image that will be shifted.
	dx		A scalar decimal value that specifies the offset on the first dimension. The shift takes place in the same direction as specified by the SHIFT function of IDL. |DX| must be smaller than the number of pixels on the x axis in IMAGE.
	dy		A scalar decimal value that specifies the offset on the second dimension. The shift takes place in the same direction as specified by the SHIFT function of IDL. |DY| must be smaller than the number of pixels on the y axis in IMAGE.

Keyword parameters:

	dimage		A two-dimensional decimal value array that contains the error image that will be shifted. wavelength [Å].
	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:

oimage

A two-dimensional decimal value array that contains the shifted image.

This routine removes any number of entries from a fits-file header array.

Input parameters:

delstr

A scalar string, or an array of strings, specifying the keyword which be removed from the header HDR.

Keyword parameters:

	quiet		No logging information is saved if this keyword is set.
	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.

This routine automatically compiles all the routines of p3d written in C, to create two shared libraries. The shared libraries are always recompiled if they are older than any of their source files.

Input parameters:

rebuild

If this keyword is set, the shared library is rebuilt, even if it already exists.

Keyword parameters:

	cifsfit_lib		This scalar string returns the name of the compiled, or found shared-library file for p3d_cifsfit.
	noC		No attempt is made to compile or use the C library if this keyword is set.
	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.
	cdebug		A keyword as DEBUG used with the called C routines.

Output parameters:

libname

This scalar string returns the name of the compiled, or found shared-library file.

Side effects:

Compiles a shared library.

This routine reads the information from a file, which contains a list of what fits file header keywords are to be used with various properties in the raw data file.

If the file header keyword contains minus signs ('–') then these are replaced with spaces (' ') before returning, unless the queried property contains UNIT.

A single occurrence of the string '#' is replaced with '–'.

Input parameters:

	table		Name of the keyword translation table.
	p3d_kwrd		Name of the keyword p3d uses.

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:

ret

Name of the fitsheader keyword, it is set to -1 if the keyword was not found.

The purpose of this routine is to return instrument-specific values on the CCD gain and the CCD readout noise.

The gain and the readout noise values are searched for either in the user-parameter file, in the instrument-specific (and specified) keywords file, or in the data file header. It is, regardless of the method, mandatory to specify all the four following keywords in the instrument-specific header keywords file: GAIN, GAINUNIT, RDNOISE, and RDNUNIT.

The values are determined in the following procedure:

Explicit values are specified in the instrument-keywords file for instruments that do not provide the required information in the data header; values that are provided in the user-parameter file override values that are specified in the instrument-keywords file. In order to use explicit values in the instrument-keywords file it is necessary to set the parameter CCDMODE to "NULL" or a header keyword that exists in the data header; such a keyword could, for example, indicate different values depending on the CCD readout speed.

The gain-parameter name is determined by starting with the string "GAIN". If CCDMODE is not set to NULL the read header keyword value is appended after an underscore. An additional suffix is appended after another underscore if the parameter CCDMODE_SUFFIX is set. If the routine is called with the keyword INDEX set, that value is appended after an additional underscore. For example, let CCDMODE be set to CCDSPEED and the corresponding header-keyword value to "FAST", and INDEX to 1. In this case the routine first searches for the following parameter in the instrument-keywords file: GAIN_FAST_1. If that parameter is not found, a second attempt is made to find the parameter: GAIN_FAST. Additionally, if CCDMODE_SUFFIX is set to CCD-TYPE and the corresponding header-keyword is EV2, then the parameters would have been GAIN_FAST_E2V_1 and GAIN_FAST_E2V, respectively. Finally, the parameter value is read as a comma-separated value string, with as many values as there are CCD blocks or file extensions. The readout noise value is treated in the exact same way.

Values that are specified in the user-parameter file override values in the instrument-keywords file and the data header. In this case values are specified as follows. The gain-parameter name is specified with the string "gain", followed by the (one-based) detector number (without any underscore); the detector number must not be provided with instrument-parameter files that only use one detector. The gain values are specified in a comma-separated value list with as many elements as there are blocks or file extensions. Readout-noise values are determined in the exact same way, using the parameter-name string "rdnoise".

The normal behavior is that the gain values and the readout-noise values of each block or extension are determined by reading the value from the data header. In this case the header-keyword name is read from the instrument-keywords parameter names GAIN and RDNOISE. The header-keyword name may contain the character "@", which if present, is replaced with the numbers 1, 2, ..., NBLOCKS || NEXTENSIONS. Or, it may contain the character "&", which is replaced with the strings that are read from the GAINSFX and RDNOISESFX keywords.

One instrument-specific setup file can contain both several blocks and several detector( configuration)s. Both gain and readout-noise values must be specified as a comma-separated list when the instrument-specific setup file uses multiple instrument configurations (NDETECTOR > 1) and several blocks (NBLOCKS > 1) or file extensions (NEXTENSIONS > 1) are used.

Input parameters:

	filenames		A scalar string, or an array of strings, which contains the name of a science-object data file. The headers of these files are scanned for the gain value, and the readout-noise values. These are the values that are returned in GAIN and RDNOISE. The instrument-specific names of the keywords are at first looked up in the instrument-specific keywords file (GAIN, GAINUNIT, RDNOISE, RDNUNIT); thereafter those keywords are used when scanning the file header. The instrument-keywords file parameters GAINUNIT and RDNUNIT are used to ensure that correct units are returned with all quantities.
	kwrdlist		A scalar string with the name of a file that contains instrument-specific keyword names for use with p3d.

Keyword parameters:

	masterbias		A scalar string that contains the name of a master-bias image file. The header of this file is scanned for the CCD gain value, the readout-noise values (rdnoise), and the number of images (n), that were combined to create the master-bias image (NCOMBINE). The pixel error is thereafter calculated as: rdnoise / sqrt(n). The instrument-specific names of the keywords are at first looked up in the instrument-specific keywords file (GAIN, GAINUNIT, RDNOISE, RDNUNIT); thereafter those keywords are used when scanning the file header. The instrument-keywords file parameters GAINUNIT and RDNUNIT are used to ensure that correct units are returned with all quantities.
	dbias		A scalar decimal value, that returns the error of every pixel in the master-bias image, in ADU. This value is set to 0 if no master-bias image is provided.
	gain		A scalar decimal value that returns the CCD gain values, in units of e-/ADU.
	rdnoise		A scalar decimal value that returns the CCD readout-noise values, in units of ADU.
	userparfile		A scalar string with the name of a file with user-defined parameters. The following parameters are read here from this file (if they are present): 'gainX', 'rdnoiseX'. If they are present then the values are not read from the data header. The suffix 'X' is provided by the input keyword INDEX, if it is present.
	ndetectors		A scalar integer that indicates the number of instrument configurations that are used in the instrument-specific parameter file.
	nblocks		A scalar integer that indicates the number of data blocks that belong to one detector.
	nextensions		A scalar integer that indicates the number of extensions in multi-extension images.
	index		If the gain and the readout noise are read from the user-parameter file or are set explicitly in the instrumen-keywords file, then an optional numerical suffix can be provided in INDEX; in order to account for instruments with several detectors. This INDEX must satisfy INDEX <> 1.
	kwgain		Unless CRDNOI1 is set this keyword returns the name of the keyword used with the chosen detector (of KWRDLIST).
	rawdataarecombined		When this keyword is set, raw data of separate cks are read from separate files, which are then bined into one image.
	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.

The purpose of this routine is to combine two fits file header string arrays into one array. All elements of the second array are simply copied over to the first array, with two limitations: the NAXIS1 and NAXIS2 entries are copied from the second array, and are placed at the top of the output header. All other entries are added at the end.

Input parameters:

	hdr1		The first fits file header.
	hdr2		The second fits file header.

Keyword parameters:

	delext		If set, the 'EXTEND' and 'XTENSION' keywords are removed from the resulting header array.
	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:

ohdr

The output fits file header.

This routine combines raw images in two senses:

Input parameters:

filename

A one- or two-dimensional array of filenames that are to be combined. If FILENAME is a one-dimensional array, all files are combined as they are. If FILENAME is a two-dimensional array, data are first combined across the first dimension. Thereafter they are combined to create a larger image across the second dimension. It is a requirement to specify DETSEC if FILENAME is specified as a two-dimensional array.

Keyword parameters:

	method		A scalar string that optionally defines the image combination method. If this keyword is set, the value is not read from the user-parameter file.
	detsec		A four-element (columns) -by- number of blocks (rows) integer array that specifies the detector region to use on the CCD for each block. For each row, the first two elements are used with the x-axis and the second two elements with the y-axis. The values DBIAS, GAIN, and RDNOISE must have as many elements as DETSEC has rows. DETSEC is only used if FILENAME is a two-dimensional array.
	nextensions		A scalar integer that contains the number of extensions in the images. Some instruments store one image in the first extension instead of in the zeroth. When this is the case, NEXTENSIONS should still be set to zero, the first extension is checked automatically. The default value is: 0
	blocksarecombined		A scalar integer that specifies if multi-block images are available in separate files (0) or in the same file. In the latter case, BLOCKSARECOMBINED must equal the number of blocks.
	rawdataarecombined		When this keyword is set, raw data of separate blocks are read from separate files, which are then combined into one image.
	rawflip		This keyword is only used if RAWDATAARECOMBINED is unset. An integer array with two rows and as many columns as there are blocks, where individual elements of the first (second) row are set when read data of separate files should be flipped on the x-axis (y-axis).
	cumulativedetsep		An integer array with two columns and as many rows as there are blocks. Each column specifies a cumulative offset on the x and the y axes for each block. All elements must be >= 0, the default is 0; this parameter is only used if BLOCKSARECOMBINED is set.
	prescanx		This keyword is used with multi-block instruments that use the 'blocksarecombined' instrument parameter or multi-extension instruments (where each extension contains a block). For each block or extension, this keyword contains the x-axis prescan array (as tags 'd1' – 'dn', where //n// is short for the number of blocks or extensions). Each array has as many elements as the data have rows (on the y-axis). The tag contains the scalar integer – 1 when there is no x-axis prescan.
	prescany		This keyword is used with multi-block instruments that use the 'blocksarecombined' instrument parameter or multi-extension instruments (where each extension contains a block). For each block or extension, this keyword contains the y-axis prescan array (as tags 'd1' – 'dn', where //n// is short for the number of blocks or extensions). Each array has as many elements as the data have columns (on the x-axis). The tag contains the scalar integer - 1 when there is no y-axis prescan.
	overscanx		This keyword is used with multi-block instruments that use the 'blocksarecombined', 'nblocks', or 'nextensions' instrument parameters, as well as multi-extension instruments (where each extension contains a block). For each block or extension, upon return, this keyword contains the x-axis overscan array (as tags 'd1' – 'dn', where //n// is short for the number of blocks or extensions). Each array has as many elements as the data have rows (on the y-axis). The tag contains the scalar integer – 1 when there is no x-axis overscan.
	overscany		This keyword is used with multi-block instruments that use the 'blocksarecombined', 'nblocks', or 'nextensions' instrument parameters, as well as multi-extension instruments (where each extension contains a block). For each block or extension, upon return, this keyword contains the y-axis overscan array (as tags 'd1' – 'dn', where //n// is short for the number of blocks or extensions). Each array has as many elements as data have columns (on the x axis). The tag contains the scalar integer – 1 when there is no y-axis overscan.
	blocknx		When BLOCKSARECOMBINED is set, this integer array defines the total number of pixels on the x-axis for each block in the raw data.
	blockny		When BLOCKSARECOMBINED is set, this integer array defines the total number of pixels on the y-axis for each block in the raw data.
	daxis		A scalar integer that defines the dimension of the dispersion direction in the spectrum image; must be either 1 or 2. The default value is: 1
	dflip		If this keyword is set, the prescan and the overscan arrays are flipped, for the axis that coincides with DAXIS.
	spatialflip		If this keyword is set, the combined data (when there are several blocks of data) are flipped on the spatial axis before they are returned. The default value is: 0
	userparfile		A scalar string with the name of a file with user- defined parameters. Here the parameters 'methodcombine' and 'slowimcombine' are used. methodcombine can be set to: 'average' using a mean. 'median' using a median. 'minmax' using a min/max-filtered average. slowimcombine can be either 'yes' or 'no'. If slowimcombine == 'yes', the minimum and minmax-array is calculated by looping instead of using the IDL-intrinsic function MIN().
	parfile		A scalar string that specifies the name of a file with instrument-specific setup parameters. Note! Only required with data that use several extensions in one file.
	nthreads		A scalar integer that specifies how many threads to use in the parallelized line-profile calculations. The calculation speed scales nearly linearly with the number of threads. The default value is: 1
	stawid		If set to a valid ID, a log message is written using this ID for relevant actions.
	topwid		If set, error messages are displayed using DIALOG_MESSAGE with this widget id as DIALOG_PARENT, instead of MESSAGE.
	logunit		Messages are saved to the file pointed at 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:

	out		The combined output array. If FILENAME has two dimensions, OUT is larger than the input DATA. The output size then depends on the contents of the DETSEC array.
	nval		A scalar integer containing the final number of pixels used in the combination procedure.
	rstr		A scalar string with information on the image combination method that was used.

This routine does preparation work to combine several raw images into one output image. Images, which are read out in several blocks, or fits file extensions, as well as a number of separate images, and any combination thereof (nearly), are handled.

The combination method is setup using the user-parameter file.

This routine is a wrapper for p3d_misc_imcombine.pro.

Input parameters:

filename

A scalar or a one-dimensional array of filenames, which contents are to be combined.

Keyword parameters:

	detsec		This output variable is set to a four-element (columns) -by- number of blocks (rows) integer array that specifies the detector region to use on the CCD for each block. For each row, the first two elements are used with the x-axis, and the second two elements with the y-axis.
	mbias		If this keyword is set, the filename is appended with the string in MOSTR instead of OSTR. The default value is: 0
	dmask		If this keyword is set, it is possible to call this routine also with a two-element array for FILENAME. The default value is: 0
	ostr		A scalar string with the image-combination specific string used to create the output filename. The default value is: '_imcmb'
	mostr		A scalar string with the master-bias specific tring used to create the output filename. The default value is: '_mbias'
	method		A scalar string passed on to p3d_misc_imcombine.
	cumulativedetsep		An integer array with two columns and as many rows as there are blocks. Each column specifies a cumulative offset on the x- and y-axes for each block. All elements must be >= 0, the default is 0. This parameter is only used if BLOCKSARECOMBINED is set.
	prescanx		This keyword is used with multi-block instruments that use the 'blocksarecombined' instrument parameter or multi-extension instruments (where each extension contains a block). For each block or extension, this keyword contains the x-axis prescan array (as tags 'd1' – 'dn', where //n// is short for the number of blocks or extensions). Each array has as many elements as the data have rows (on the y-axis). The tag contains the scalar integer – 1 when there is no x-axis prescan.
	prescany		This keyword is used with multi-block instruments that use the 'blocksarecombined' instrument parameter or multi-extension instruments (where each extension contains a block). For each block or extension, this keyword contains the y-axis prescan array (as tags 'd1' – 'dn', where //n// is short for the number of blocks or extensions). Each array has as many elements as the data have columns (on the x-axis). The tag contains the scalar integer - 1 when there is no y-axis prescan.
	overscanx		This keyword is used with multi-block instruments that use the 'blocksarecombined', 'nblocks', or 'nextensions' instrument parameters, as well as multi-extension instruments (where each extension contains a block). For each block or extension, upon return, this keyword contains the x-axis overscan array (as tags 'd1' – 'dn', where //n// is short for the number of blocks or extensions). Each array has as many elements as the data have rows (on the y-axis). The tag contains the scalar integer – 1 when there is no x-axis overscan.
	overscany		This keyword is used with multi-block instruments that use the 'blocksarecombined', 'nblocks', or 'nextensions' instrument parameters, as well as multi-extension instruments (where each extension contains a block). For each block or extension, upon return, this keyword contains the y-axis overscan array (as tags 'd1' – 'dn', where //n// is short for the number of blocks or extensions). Each array has as many elements as data have columns (on the x axis). The tag contains the scalar integer – 1 when there is no y-axis overscan.
	biasconstant		This keyword is used with multi-block instruments that use the 'blocksarecombined', 'nblocks', or 'nextensions' instrument parameters.
	parfile		A scalar string that specifies the name of a file with instrument-specific setup parameters.
	userparfile		A scalar string with the name of a file with user- defined parameters.
	detector		A scalar integer that specifies the currently selected detector; DETECTOR is a zero-based value. The default value is: 0
	opath		A scalar string that specifies the path, where the output image is saved. The default value is: '.'
	opfx		A scalar string specifying a prefix of the output filename. The default value is: ''
	sfx		A scalar string specifying the file ending (without a trailing compression suffix, such as .gz or .Z). The default value is: '.fits'
	xstr		To be filled in... The default value is: ''
	dsh		This flag upon exit indicates whether anything was done by this routine (1) or not (0).
	compress		If this keyword is set, the output image file is compressed using gzip. The default value is: 0
	title		This scalar string is used to mark in the output file which kind of data this is. The default value is: ' '
	dflip		This keyword is set if the image is flipped on the dispersion axis before the routine is exited. The default value is: 0
	donotwrite		No output file is written if this keyword is set.
	ohdr		Upon return this keyword contains the written output header, if DONOTWRITE is set.
	nthreads		A scalar integer that specifies how many threads to use in the parallelized line-profile calculations. The calculation speed scales nearly linearly with the number of threads. The default value is: 1
	stawid		If set to a valid ID, a log message is written using this widget ID for relevant actions.
	topwid		If set, error messages are displayed using DIALOG_MESSAGE with 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:

	ofilename		The name of the output file(s), without the file suffix (OFSFX). If FILENAME is a two-element array, OFILENAME is also a two-element array, otherwise it is a scalar.
	ofsfx		The file suffix(es) corresponding to OFILENAME.
	odata		Contains the combined output image.

This routine sets up the required p3d system variables and preferences.

!p3d_path This variable points at the directory where p3d is located. Nothing is done here if !p3d_path is already set. If it is not then the first option is to read and use the system environment variable p3d_path (note that the letters are lower case). The second option is to use the directory where p3d.pro is found.

!p3d_data_path A directory which is first used when starting file dialogs of data to reduce. Nothing is done here if !p3d_data_path is already set. If it is not then the first option is to use the system environment variable p3d_data_path. The second option is to use the current directory.

!p3d_font A scalar string that specifies which font p3d should use. Nothing is done here if !p3d_font is already set. If it is not then the first option is to use the system environment variable p3d_font.

IDL_DLM_PATH This preference entry needs to include the src directory in p3d_path. The preference entry is cleaned of all entries that include "p3d" or the last part of !p3d_path (i.e. file_basename()).

-n/a- This routine also checks if the necessary mpfit routine (mpfit.pro) is available. This routine is used when calculating cross-dispersion line profiles on the trace mask, and are subsequently used in the optimal extraction routine. The required routine can be downloaded using the provided script in: ${p3d_path}/vm/. -n/a-

Input parameters:

p3d_path

A scalar string with the path of the (used) p3d distribution; this string is used if neither !p3d_path nor the environment variable ${p3d_path} are set. A requirement is that this routine is compiled before it is called (but that is always the case for a called routine).

Keyword parameters:

	ds9present		If the binary 'ds9' is found in the system path, this keyword is set.
	font		A scalar string with the name of a font to use; this string is added to the X resources file.
	quiet		No informational message about missing cmpfit files is displayed if this keyword is set.
	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.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

mpfitpresent

This keyword is set if mpfit.pro is found in !path.

Side effects:

Modifies the IDL preference parameter IDL_DLM_PATH and the IDL !path.

Outputs a string to the screen, and also optionally, to a log file.

Input parameters:

logstr

The string to print. Can be an array of strings.

Optional parameters:

funit

If this two-element argument is set, where the first element is a file unit, then the output is also written to the file pointed to by this file unit. Before this file unit is used, it is checked if it is open and can be written to; it is ignored if this is not the case. A second element must also be present specifying the logging level associated with the file (see LOGLEVEL).

Keyword parameters:

	rname		The name of the routine calling. The default value is: 'p3d_misc_logger'
	loglevel		Before a string is written to funit[0] (if it is open) it is checked if LOGLEVEL >= funit[1], only then is the message written to the file. The default value is: 1
	topwid		If set, the error message (iff ERROR) is shown using a dialog instead of printing the message on the console.
	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.

Output parameters:

ret

Returns -1 if error is non-zero, otherwise 0.

Creates a suitably formatted date and time string.

Optional parameters:

loglevel

Adds the log level to the output string.

Output parameters:

ret

Returns the date string.

This routine calculates a two-dimensional array smoothing. A rectangular box of the size [2*XBOX + 1,2*YBOX + 1] is moved across the array and the center of the box is replaced by the average of the box.

Input parameters:

	image		A two-dimensional array.
	xbox		The half x-width of the filter smoothing box.
	ybox		The half y-width of the filter smoothing box.

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:

out

2D image

For a two-dimensional input array (ARRAY) this routine creates a collapsed version where pixel values along the dispersion direction (DAXIS) have been averaged in bands, which are 2*SMOWIDTH+1 pixels wide and are centered on specified pixels (POS). Additionally, POS is returned as OUTPOS, where pixels have been filtered out which are <0 and larger than the dispersion dimension of ARRAY (s[DAXIS]).

Input parameters:

	array		A two-dimensional array of floating point values.
	pos		A one-dimensional array of floating point values, which specify pixels in the dispersion direction, for which the smoothing is made.
	smowidth		A scalar decimal value. The average value is calculated for a dispersion region of width 2*smowidth+1.

Keyword parameters:

	daxis		Defines the dispersion direction dimension of IMAGE. The default, 1, is in the x-direction. 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:

	out		A one-dimensional array of decimal values containing the cross-dispersion direction averaged spectrum values.
	outpos		A one-dimensional array of integers. This array is the same as POS, where negative values, and values which are larger than the maximum number of pixels in the dispersion direction of ARRAY are filtered out.

This routine calculates a two-dimensional array smoothing. A rectangular box of the size [2*XBOX+1,2*YBOX+1] is moved across the array and the center of the box is replaced by the median of the box.

Input parameters:

	array		A two-dimensional array.
	xbox		The half x-width of the filter smoothing box.
	ybox		The half y-width of the filter smoothing box.

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:

out

A two-dimensional array.

For detectors that are read out to several files (blocks), this file adds some block-specific header keywords to the input fits header variable.

It is for these detectors, moreover, likely an issue that the gain is different for the separate files. This creates a problem since the extracted spectra are stored in the ADU, and it is not possible to know what the gain of every pixel is after the data have been reduced (The error can still be calculated properly).

This routine solves this issue by first calculating a mean value on the gain (of all blocks). Thereafter the data (not the prescan and overscan regions though) are normalized to the same value of the gain.

The following keywords are passed over directly to p3d_misc_getinformation: FILENAME, KWRDLIST, USERPARFILE.

Keyword parameters:

	detsec		A four-element (columns) -by- number of blocks (rows) integer array that specifies the detector region to use on the CCD for each block. For each row the first two elements are used with the x-axis, and the second two elements with the y-axis.
	prescanx		This structure is, when provided, scaled using the same scaling factor as the main data.
	prescany		This structure is, when provided, scaled using the same scaling factor as the main data.
	overscanx		This structure is, when provided, scaled using the same scaling factor as the main data.
	overscany		This structure is, when provided, scaled using the same scaling factor as the main data.
	blocksarecombined		If this keyword is set, the gain and the adout-noise values of the different blocks are l found in the same image header.
	userparfile		A scalar string with the name of a file with user-defined parameters.
	ndetectors		A scalar integer that indicates the number of detectors used in the instrument-parameter file.
	nblocks		A scalar integer that indicates the number of data blocks that belong to one detector.
	nextensions		If this scalar is used, this many file extensions of one file are used instead of several files. The default value is: 0
	cumulativedetsep		This keyword is passed on to p3d_misc_odetsec.
	rawdataarecombined		When this keyword is set, raw data of separate cks are read from separate files, which are then bined into one image.
	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.

This routine retrieves observation-related properties from a fits-file header, or sometimes from the instrument-keywords file. Specifically, the following properties are retrieved, the string in brackets is looked up in the instrument-keywords file:

• Observatory latitude [OBSLATITUDE] This value specifies the observatory latitude, and is returned in the keyword LATITUDE, with the origin string keyword ORIGLATITUDE.

• Observatory longitude [OBSELEVATION] This value specifies the height of the observatory above the sea level, and is returned in the keyword OBSELEVATION, with the origin string keyword ORIGOBSELEVATION.

• The declination of the observations [DECLINATION] This value specifies the declination; it is returned in the keyword DECLINATION, with the origin string keyword ORIGDECLINATION. The following string formats are accepted: degrees, deg:min:sec format, or degminsec (if DECFORMAT="degminsec").

  The keyword DEC_OFFSET [arcsec] can be used if the value that is available in the header is not accurate enough.

• The right ascension of the observations [RIGHTASCENSION] This value specifies the right ascension; it is returned in the keyword RIGHTASCENSION, with the origin string keyword ORIGRIGHTASCENSION. The following string formats are accepted: hours, hour:min:sec format, or hourminsec (if RAFORMAT="hourminsec").

  The keyword RA_OFFSET [arcsec] can be used if the value that is available in the header is not accurate enough. Note that this offset value is divided by the cosine of the declination.

• The local sidereal time [LOCALSIDEREALTIME] This value specifies the local sideral time; it is returned in the keyword LOCALSIDEREALTIME. The following string formats are accepted: degrees or deg:min:sec.

• The azimuth [AZIMUTH] This value specifies the azimuth; it is returned in the keyword AZIMUTH, with the origin string keyword ORIGAZIMUTH. The following string formats are accepted: degrees or deg:min:sec.

  If the azimuth is available it is used to calculate an hourangle, which is returned in the keyword AZHOURANGLE.

• Hour angle [HOURANGLE] This value specifies the hourangle; it is returned in the keyword HOURANGLE, with the origin string keyword ORIGHOURANGLE. The following string formats are accepted: degrees or deg:min:sec.

  If the hourangle is unavailable in the header it is calculated using the right ascension and the local sidereal time: hourangle = (LOCALSIDEREALTIME / 240 – RIGHTASCENSION + 360) mod 360.

• The parallactic angle [PARALLANGLESTART, PARALLANGLEEND, PARALLANGLE]

This value specifies the parallactic angle; it is returned in the keyword PARANG, with the origin string keyword ORIGPARANG. At first this parameter is taken from the header; if both PARALLANGLESTART and PARALLANGLEEND are available then they are used to calculate a mean value on the parallactic angle, otherwise the value in the header keyword PARALLANGLE is used.

If the headers do not contain any directly available information on the parallactic angle then it is calculated using the hourangle, the declination, and the latitude.

• The zenith distance [ZENITHDISTSTART, ZENITHDISTEND, ZENITHDISTANCE]

This value specifies the zenith distance; it is returned in the keyword ZENITHDISTANCE, with the origin string keyword ORIGZENITHDISTANCE. At first this parameter is taken from the header; if both ZENITHDISTSTART and ZENITHDISTEND are available then they are used to calculate a mean value on the zenith distance, otherwise the value in the header keyword ZENITHDISTANCE is used.

If the header contains both a starting and a final value of the parallactic angle then these values are used to calculate a mean zenith distance.

If the headers do not contain any directly available information on the zenith distance then it is calculated using the hourangle, the declination, and the latitude.

• The airmass [AIRMASSTART, AIRMASSEND, AIRMASS] This value specifies the airmass; it is returned in the keyword AIRMASS, with the origin string keyword ORIGAIRMASS. At first this parameter is taken from the header; if both AIRMASSSTART and AIRMASSEND are available then they are used to calculate a mean value on the airmass, otherwise the value in the header keyword AIRMASS is used. However, this might not be the final output value on the airmass. The following steps are also considered.

  If the header contains both a starting and a final value of the parallactic angle then these values are used to first calculate a mean zenith distance, and then the airmass.

  If the header contains both a starting and a final value of the zenith distance – either through a starting and a final parallactic angle (higher priority) or directly (lower priority) – then these values are used to calculate a starting airmass (a_st), a final airmass (a_fn), and a mean airmass (a_mn). The output airmass is then calculated as: airmass = (a_st + 4 * a_mn + a_fn) / 6. If the airmass is still unset, and only one value on the zenith distance is available in the header, then that value is used to calculate the airmass.

• The airmass of the guide star [GS_RIGHTASCENSION, GS_DECLINATION] If the instrument-keywords file contains keywords for the right ascension and the declination of the guide star, then the guide-star specific airmass is returned in the keyword GS_AIRMASS. Additionally, the following calculated output keywords are returned: GS_RIGHTASCENSION, GS_DECLINATION, GS_HOURANGLE, and GS_ZENITHDISTANCE.

  The following string formats are accepted for GS_RIGHTASCENSION: hours, hour:min:sec, or hourminsec (if GS_RAFORMAT="hourminsec").

  The following string formats are accepted for GS_DECLINATION: degrees, deg:min:sec, or degminsec (if GS_DECFORMAT="degminsec").

  The right ascension is used to calculate an hourangle, which is used together with the declination and the latitude to calculate a zenith distance. This zenith distance is finally used to calculate the guide star airmass.

Used parts of the DAR routine of J. Walsh (ESO)

With the written permission of J. Walsh at ESO the following features and issues are considered properly in the entirety thanks to his work:

The source code of the original routines (arshft.f) is available online at the IFS-WIKI. See p3d_darc for more details.

Links

Keyword parameters:

	ahdr		A string array with an alternative header array.
	ra_offset		A scalar decimal value that allows a specification of an offset from the read right ascension; this value is divided by the cosine of the declination. The unit is arcsec, and the default value is 0.0. The default value is: 0
	dec_offset		A scalar decimal value that allows a specification of an offset from the read declination. The unit is arcsec, and the default value is 0.0. The default value is: 0
	spaxelscale		A scalar floating-point type value that defines the size of spatial elements; only used when the instrument keywords DEC_XTRA_OFFSET or RA_XTRA_OFFSET are used.
	kwrdlist		A scalar string with the name of a file that contains instrument-specific keyword names for use with p3d.
	airmass		A scalar decimal value that contains the finally calculated airmass.
	origairmass		A scalar string that indicates how the airmass was calculated.
	parang		A scalar decimal value that contains the finally calculated parallactic angle. The unit is degrees.
	origparang		A scalar string that indicates how the parallactic angle was calculated.
	declination		A scalar decimal value with the declination. The unit is degrees.
	origdeclination		A scalar string that indicates if the declination value was used with an offset.
	rightascension		A scalar decimal value with the right ascension. The unit is degrees.
	origrightascension		A scalar string that indicates if the right ension value was used with an offset.
	localsiderealtime		A scalar decimal value with the local sidereal me. The unit is degrees.
	zenithdistance		A scalar decimal value that contains the finally extracted or calculated zenith distance. The unit is degrees.
	origzenithdistance		A scalar string that indicates how the zenith tance was calculated.
	hourangle		A scalar decimal value that contains the finally extracted or calculated hourangle. The unit is degrees.
	orighourangle		A scalar string that indicates how the hourangle was calculated.
	azhourangle		A scalar decimal value that contains the hourangle calculated using the azimuth. The unit is degrees.
	latitude		A scalar decimal value that specifies the observatory latitude. The unit is degrees.
	origlatitude		A scalar string that indicates if the latitude was extracted from the keywords file or from the header.
	obselevation		A scalar decimal value that specifies the observatory elevation. The unit is meters.
	origobselevation		A scalar string that indicates if the observatory levation was extracted from the keywords file or rom the header.
	azimuth		A scalar decimal value that specifies the azimuth, if it is available in the header. The unit is degrees.
	gs_airmass		A scalar decimal value that contains the calculated airmass of the guide star, if available.
	gs_zenithdistance		A scalar decimal value that contains the lculated zenith distance of the guide star, if ailable. The unit is degrees.
	gs_declination		A scalar decimal value that contains the guide star declination, if available. The unit is degrees.
	gs_rightascension		A scalar decimal value that contains the guide ar right ascension, if available. The unit is grees.
	gs_hourangle		A scalar decimal value that contains the guide star hourangle, if available. The unit is degrees.
	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.

Calculates a detector-section array for the output image, using the raw-data detector-section array.

Input parameters:

detsec

A four-element (columns) -by- number of blocks or extensions (rows) integer array that specifies the raw image region to use on the CCD for each block. For each row, the first two elements are used with the x-axis, and the second two elements with the y-axis.

Keyword parameters:

	blocksarecombined		- If this keyword is set then the elements of DETSEC are assumed to be properly ordered.
	prescanremains		If this keyword is set, and BLOCKSARECOMBINED is also set, then the image in question is assumed to have been combined, but prescan regions are still present.
	nextensions		A scalar integer that specifies the number of extensions in the raw data. This keyword is only used when BLOCKSARECOMBINED is unset.
	cumulativedetsep		An integer array with two columns and as many rows s there are blocks. Each column specifies a umulative offset on the x and the y axes for each lock. All elements must be >=0, the default is 0. his parameter is only used if BLOCKSARECOMBINED is et.
	rawdataarecombined		When this keyword is set, raw data of separate cks are read from separate files, which are then bined into one image.
	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.

This routine takes a string as input and checks if it contains either !p3d_path or !p3d_data_path (/DPATH). If it does then that part of the string is replaced with either of those two variable names.

Alternatively, if the string does not contain !p3d_path or !p3d_data_path then the directory above is checked.

If !p3d_path (DPATH=0), or !p3d_data_path (DPATH=1), is not set then the input string is returned unchanged.

Input parameters:

str

The input string. Should contain a filename with a path.

Keyword parameters:

dpath

If this keyword is set then the string is checked for the contents of !p3d_data_path, otherwise !p3d_path is used.

Output parameters:

ret

This is the input string where the part correspon- ding to !p3d_path or!p3d_data_path has been replaced with '!p3d_path' or '!p3d_data_path'.

Calculates a functional value, or an array of values, using a defined set of input parameters.

Input parameters:

	x		A one-dimensional array with the abscissae of Y.
	p		A one-dimensional array with the parameter values that are used when calculating the functional return value. Each function uses its own parameters.

Keyword parameters:

	proffun		A scalar string with the name of the function to use when calculating the line profile.
	nobg		If this keyword is set then the background is not added.
	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.

Output parameters:

fun

An array of the same properties as X with the evaluated function.

This routine reads the dead fibers file. Arrays with the list of dead fibers and corresponding identification strings are returned when found.

he routine returns immediately if the first argument with the name f the dead-fibers file is unset.

hen such information is available and the keyword IFUNUM is set, his routine returns IFU-specific information, which is set with an nderscore after the dead fiber entry. For example, if IFUNUM is set

• 11 only entries such as '137', '137_11', and '137_0' are returned.

Input parameters:

dfile

A scalar string with the name of the plain-text dead-fibers file. The file must contain two columns of text; column one must list the dead fibers and column two the corresponding status of the spectrum.

Keyword parameters:

	ifunum		A scalar integer that identifies the entries to save from the read list.
	pdu		Set this keyword to save entries that contain one of the strings 'dead fiber' or 'unused fiber'.
	ppdu		Set this keyword to save entries that contain one of the strings 'dead fiber', 'unused fiber', or 'possibly unused fiber'.
	seplow		Set this keyword to return low-transmission spectra in the separate output variables TDA and TSDA.
	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:

	da		An integer array with dead fiber entries.
	sda		The string array corresponding to DA.
	tda		An integer array with low-transmission entries. This array is only returned when SEPLOW is set.
	tsda		The string array corresponding to TDA.

Reads the contents of the spectrum gaps file.

• Optional entries in the header:

  All entries must be preceeded by a '; ' in the columns 1 & 2. The parameter value is specified next, and then the parameter name. Available parameters are (default values in []):

  + STARTPX [-1]

  Specifies the starting pixel used to create simulation data.

Input parameters:

	gapfile		The name of the instrument-specific tracing gaps file, if it exists. Non-existing files are specified as emptry strings.
	detector		A scalar integer that specifies the id of the current detector, as it is setup in the parameter file.

Keyword parameters:

	hdr		A string array that is used to find the IFU number in the read data file (if any).
	kwrdlist		A scalar string that specifies the name of a file that contains a list of instrument-specific keyword names.
	ifunum
	startpx		A scalar decimal value that returns the start pixel used when creating data for simulations. 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.

For an input string array (PARNAME), with a corresponding array of values (PARVALUE), the string NAME is searched for, and the corresponding value is returned in VALUE.

The read parameter is, optionally, converted to an integer or a floating point value. Only the first value is returned if several entries are found.

Input parameters:

	parname		List of parameter names. Both upper and lower case are ok.
	parvalue		List of parameter values, corresponding to PARNAME.
	name		The parameter name for which the value is requested. Both upper and lower case are ok.

Keyword parameters:

	multiple		If this keyword is set, the number of read comma-separated parameters must be equal to this [integer] number.
	must_exist		An error is issued if this keyword is set and a parameter is not found.
	uparname		A list of alternative parameter names; both upper and lower case entries are ok. If UPARNAME and UPARVALUE exist, then the parameter is replaced with the value of UPARVALUE, if found.
	uparvalue		A list of alternative parameter values, corresponding to PARNAME; see UPARNAME.
	found		This keyword is set depending on if the parameter is found or not: 0 The parameter could not be found. 1 The parameter was found in the instrument-parameter file. 3 The parameter was found in the user-parameter file. (Through the use of 3 instead of 2 a routine that wants to use FOUND in a condition can simply say "... if found then ..." (instead of "... if found ne 0 then ...").
	type		If this scalar string is set then the read parameter is checked if it conforms to the variable type. TYPE can be set to 'integer' or 'float'. If TYPE is not set then a string is returned.
	xstr		If this scalar string is set then this routine first searches for NAME+'_'+XSTR in PARNAME. If it is not found, another search is performed using only NAME.
	upo		If this keyword is set then the parameter origin is set to '[userparfile]'. Also, if neither PARNAME nor PARVALUE is defined then the routine returns without setting the output VALUE.
	nou		If this keyword is set then no parameter origin is set (useful with parameters which are not allowed to change value).
	a0		If set, then the routine returns if PARNAME is undefined.
	parsrc		Upon returns this scalar-string keyword contains the origin of the keyword.
	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:

value

Contains the value of the parameter with the name NAME. If NAME is not found, – 1L is returned.

Read a spatial element position file, and returns the contents. The returning array XPOS always returns coordinates West->East and YPOS South->North.

There are two modes of defining the fiber position table. It is either contained in a regular plain-text file, which name is specified using the keyword POSTABLE. The second approach creates a dummy position table that is merely used as a placeholder; this approach is used in simulations and is used by setting the keyword POSTABLE to the string prefix '@__synthetic_table_with_spnum_', which is followed by the number of spectra to use.

Fiber position table format

The format of the position table is well defined and must be followed in order to provide a correctly defined output. The format of a position table file is as follows:

Header

All entries must be preceeded by a '; ' in the columns 1 & 2. The parameter value is specified next, and then the parameter name. Required parameters are (default values in []):

+ SHAPE [0], 1

+ SCALE [1.0]

Specifies a value by which all coordinates and the fiber sizes are multiplied with. The meaning is different for the different shapes.

+ XISW2E [0], 1

+ XFAC – 1, [1]

+ YFAC – 1, [1]

USESKY 0, [1]

FLIPX [0], 1

Data

The positional data must be present in five columns, and the unit of the values must be the same for all elements in columns 3-5:

• Column 1

  The image row (cross-dispersion direction). This number will be decremented by 1 inside the program in order to account for IDL's 0-based array numbering.

  Additional image rows of existing image-row numbers can be suffixed with an underscore followed by the IFU id (which is specified with the SIFUNUM keyword). The additional rows replace those that do not contain such a suffix.

  Note: Rows, which have an ID higher than, or equal to, ELEMNOUSE will be deleted and hence the row numbering will be decremented by one for rows ahead of every such row.

• Column 2

  This column specifies the spatial element ID. Element IDs, which are different from the image row number, are used by, e.g., the PPAK-IFU.

  Note: Spatial elements marked with an ID of a science, calibration (ELEMCALIB), sky (ELEMSKY), and not to be used (ELEMNOUSE) all use a different numbering (see below).

• Column 3

  This is the x-coordinate column. If the data of this column specify W-E coordinates, then XISW2E must be set to 1 in the table header.

• Column 4

  This is the y-coordinate column. If the data of this column specify S-N coordinates, then XISW2E must be set to 1 in the table header.

• Column 5

  This column specifies the size of every spatial element, in the same unit as the coordinates. If SHAPE == 1-3, then this number specifies the circular element diameter. It is not used if SHAPE == 0.

Synthetic fiber position table

The fiber position table is constructed with n_col = long(sqrt(spnum)) columns and ceil(spnum / n_col) rows. The spaxel shape is assumed to be squares (shape=0):

Keyword parameters:

	postable		Position-table filename (containing the full path). Can alternatively be set to a string with the prefix '@__synthetic_table_with_spnum_', which instead results in the creation of a synthetic table.
	rownum		An array of element row numbers [output].
	id		An array of element id numbers [output].
	xpos		An array of element x positions [output].
	ypos		An array of element y positions [output].
	lens_size		An array of element lens sizes [output].
	shape		An integer specifying the shape of the spatial elements; 0-3 [output]. The default value is: 0
	nvertices		An integer specifying the number of vertices of circularly shaped elements (SHAPE == 1 || 2 || 3). The default value is: 15
	all		If this keyword is set all entries are read, and are returned as they are. This is a useful mode when combining position tables automatically.
	science		Read science elements.
	sky		Read sky elements.
	calibration		Read calibration elements.
	elemnouse		Elements > than this value are deleted from the table. The default value is: 1000000L
	elemsky		Elements > than this value are considered sky elements. Note! ELEMSKY < ELEMCALIB ! The default value is: 800000L
	elemcalib		Elements > than this value are considered calibration elements. Note! ELEMCALIB < ELEMNOUSE ! The default value is: 900000L
	usesky		This keyword specifies if the instrument (setup) is used on the sky or not. The default value is: 1
	really_flipx		This keyword specifies if the spatial map image needs to be flipped on the x axis even though USESKY is unset. The default value is: 0
	sifunum		A scalar string that specifies a suffix that is used to replace read default rows (see the data:columns description in the routine description). The string is also used to create an alternative POSTABLE without the string '_ifuXXX' (where XXX is the remainder of SIFUNUM when the prefix underscore is removed) in case the file does not exist.
	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.

Retrieves the instrument-specific IFU number, for those instruments that use more than one IFU in the same setup file (such as VIRUS).

If the keyword IFUIDNUMBER is set in the instrument keywords file, the corresponding header keyword is read from the header of the provided filename. The routine returns an integer.

Input parameters:

kwrdlist

The name of a file, that contains a two-column list of parameters to use with p3d for the instrument in question. The routine returns if this keyword is unset or set to an emtpy string.

Optional parameters:

filename

A scalar string with the name of a fits file. Alternatively, if this variable instead is a string array, it is assumed to be a fits-file header.

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:

ifunumset

Returns the scalar integer 1 if IFUNUM was set.

Routine description pending.

Input parameters:

tracefile

A scalar string that contains the name of the trace-mask image file, which associated line-profiles image file is located and loaded here.

Keyword parameters:

	method		A scalar string specifying the spectrum extraction method.
	opath		A scalar string that, if it is specified, specifies an alternative path where the file is searched for.
	nthreads		A scalar integer that is used when setting the number of threads that are used when compressing rewritten fits files using the command pigz.
	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:

	lprofs		A three-dimensional array of line profile fitting parameters.
	proffun		Contains a scalar string with the name of the function used to calculate the line profile parameters of LPROFS.

This routine converts a two-dimensional row-stacked spectrum (RSS) data image into a three-dimensional data cube.

Input parameters:

rssdata

The 2D-array with RSS data. The format is as follows: DAXIS = 1: [# of wavel., # of spatial elements] DAXIS = 2: [# of spatial elements, # of wavel.]

Keyword parameters:

	angle		A scalar integer value that defines how the spatial axes are oriented in the cube. The unit is degrees [°]: ANGLE = 0 North is up and East left ANGLE = 90 North is left and East down ANGLE = 180 North is down and East right ANGLE = 270 North is right and East up If ANGLE assumes any other value the ANGLE = 0 case is used. The default value is: 0
	daxis		Defines the dimension of the dispersion direction in the spectrum image; must be either 1 or 2. The default value is: 1
	badarr		If specified then this integer array must have as many elements as RSSDATA has spatial elements. This array specifies which spatial elements are dead or unused (1).
	posfile		A scalar string with the fiber-position table filename corresponding to the RSSDATA variable.
	posdata		This scalar structure is used in place of POSFILE when it is present. In this case, the spatial-elements positions are calculated automatically and row and id numbers are set as increasing numbers. The lens size is set to 1.0. All arrays are returned in a structure with the following tags: rownum, id, xpos, ypos, and lens_size. All constant spectra are removed from the returned RSS image; the id array refers to the pre-removal image.
	sifunum		This keyword is used with p3d_misc_read_postable.pro.
	posreverse		Set this keyword to reverse the fiber-position arrays.
	crebuild
	noC
	nthreads		The number of threads to use in the conversion. The default value is: 1
	title		A scalar string that is written to the log file, when it is set.
	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.
	cdebug		A keyword as DEBUG used with the called C routines; valid values are 0-6 where a higher number results in more output to STDERR.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

	cube		A three-dimensional array with cube data. The data format is: [nsn, nwe, # of wavelengths]. The type is the same as that of the input array.
	nwe		A scalar integer specifying how many elements there are on the cube West->East axis.
	nsn		A scalar integer specifying how many elements there are on the cube South->North axis.
	usex		A two-dimensional byte-type array with [nsn, nww] elements. The elements indicate if the particular element contains a spectrum [1b] or not [0b].

This routine sets up a "Sauron"-style color table using the recipe of: Michele Cappellari & Eric Emsellem, Leiden, 10 July 2001

Start with 7 equally spaced coordinates, then adds 4 additional points: x = findgen(7) * 255 / 6. + 1 [1.0, 43.5, 86.0, 128.5, 171.0, 213.5, 256.0]

This colormap formulation is, with permission of its original authors used in the p3d package. The routine has been adapted to allow the use of different numbers of colors and offsets.

Keyword parameters:

	ncolors		A scalar integer specifying the number of colors to use. The default value is: !d.table_size
	bottom		A scalar integer that specifies the lower index of the colortable that is used in the scaling of the colormap. The upper index is always the maximum value (!d.table_size). This value should be set >=2 (5 is the optimum choice) to allow some room for the reserved colors of P3D. The default value is: max(index) + 1
	invert		Set this keyword to invert the color table.

Side effects:

Modifies the colortable.

Sets up a gaps array.

The setup is determined completely by the values of the array GAPSNUM and the number of spectra SPNUM. The values of GAPSNUM are the following:

• GAPSNUM[0]:

  The constant number of spectra per group. The last group may, however, contain fewer spectra depending on the value of SPNUM.

• GAPSNUM[1]:

  The constant number of empty spectra between group.

• GAPSNUM[2]:

  The starting pixel on the cross-dispersion axis.

Input parameters:

	gapsnum		A two- or three-element decimal array that contains the constant number of spectra per group, the constant number of "empty spectra" between the groups, and [optionally] the starting pixel.
	spnum		An optional scalar integer that specifies the total number of spectra.

Keyword parameters:

	startpx		A scalar decimal value that returns the start pixel used when creating data for simulations; this is the value of GAPSNUM[2], when present. 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.

This routine provides an array smoothing algorithm. A box of the width "2*XBOX+1" is moved across the array and the center of the box is replaced by the average or median of the box.

Input parameters:

	image		A one-dimensional array of data to smooth.
	xbox		The half-width of the smoothing box for the filter.

Keyword parameters:

	median		Uses a median instead of the default average.
	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

The smoothed two-dimensional array.