The p3d logo. a general data-reduction tool for fiber-fed integral-field spectrographs
About p3d

Readme

Download

References

Documentation & Tutorials

Links

Screenshots

Authors & Thanks

Sourceforge project page

Category: auxiliary routines

Summary

PROp3d_misc_2dgaussfit
Fits a two-dimensional Gaussian to an image using MPFIT.
PROp3d_misc_binextract
This routine extracts the CCD binning parameters XBIN and YBIN which must be present, in some form, in the input fits file header HDR.
PROp3d_misc_bins_file_read
Reads bin data from a plain-text or binary-table fits file; this routine reads all files written by p3d_misc_bins_file_write.
PROp3d_misc_bins_file_write
Writes bin map data to a plain-text or binary-table fits file.
PROp3d_misc_checkfile
This routine checks whether the fits header in the supplied filename contains the required detector id.
PROp3d_misc_checkob
This routine checks whether all the fits headers of the supplied filenames contain the same observation block (OB) identification string.
FUNCTIONp3d_misc_choose
This routine provides a GUI for choosing an instrument, before launching the main panel GUI.
PROp3d_misc_colortable
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.
PROp3d_misc_colortable_widget_menu
This routine extracts the CCD binning parameters XBIN and YBIN which must be present, in some form, in the input fits file header HDR.
FUNCTIONp3d_misc_colorval
Returns a decomposed-colors value for the specified color name.
FUNCTIONp3d_misc_correlate_arrays
Find the optimal offset of array VECA relative to array VECB.
PROp3d_misc_cube2rss
This routine converts a three-dimensional data cube into a two-dimensional row-stacked spectrum (RSS) data image.
PROp3d_misc_cubehelix_colormap
This routine sets up a "Cubehelix" color table using the recipe of D.
PROp3d_misc_dataclip
This routine takes an input array and calculates a limited range of values using a histogram function and a percentage.
PROp3d_misc_detsec
This routine retrieves a four-element array (DETSEC) that contains the array indices of the CCD data-area (i.
FUNCTIONp3d_misc_detsec_str2val
Provides a support routine for p3d_misc_detsec.
PROp3d_misc_e3dio_read
Open a FITS file in E3D format and return an RSS array, and position table vectors and spaxel shape and size .
PROp3d_misc_e3dio_write
Data reduced with the p3d tool can be saved in the Euro3D format using this routine.
PROp3d_misc_errors
The purpose of this routine is to display an error message once an error handler has been setup using CATCH.
FUNCTIONp3d_misc_extract_method
This routine determines which spectrum extraction method is to be used.
PROp3d_misc_fileallbl
From a list of filenames this routine finds the filenames of all blocks for multi-block instruments (PMAS 4kx4k CCD).
FUNCTIONp3d_misc_findpath
For a specified file, this routine decides which path to use with that particular file.
FUNCTIONp3d_misc_findspec
For a defined input value this routine checks if this value exists in a list of defined dead, unused, or possibly unused fiber values.
PROp3d_misc_fitsstrad
Adds a keyword, optionally with a very long name, and its value and comment to a fits-header string array.
FUNCTIONp3d_misc_fitsstrex
This routine extracts the value with the keyword name STR from the fits header array HDR.
PROp3d_misc_fluxcal_read_file_atmospheric_extinction
Reads and returns the wavelength array and the extinction array of a provided atmospheric-extinction calibration file.
PROp3d_misc_fluxcal_read_file_standard_star
Reads and returns the wavelength array and the flux of a provided standard-star calibration file.
PROp3d_misc_fluxcal_read_file_standard_star_gui
Provides a GUI to select the extension to use in a multi-extension standard-star file.
FUNCTIONp3d_misc_fshift
Shifts an image by a fractional value on either axis.
PROp3d_misc_fxdelpar
This routine removes any number of entries from a fits-file header array.
FUNCTIONp3d_misc_get_callext_exlib
This routine automatically compiles all the routines of p3d written in C, to create two shared libraries.
FUNCTIONp3d_misc_get_hdr_kwrd
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.
PROp3d_misc_getinformation
The purpose of this routine is to return instrument-specific values on the CCD gain and the CCD readout noise.
PROp3d_misc_headercombine
The purpose of this routine is to combine two fits file header string arrays into one array.
PROp3d_misc_imcombine
This routine combines raw images in two senses: 1.
PROp3d_misc_imcombine_wrapper
This routine does preparation work to combine several raw images into one output image.
PROp3d_misc_initialize
This routine sets up the required p3d system variables and preferences.
FUNCTIONp3d_misc_logger
Outputs a string to the screen, and also optionally, to a log file.
FUNCTIONp3d_misc_logger_dt
Creates a suitably formatted date and time string.
PROp3d_misc_mean_smooth
This routine calculates a two-dimensional array smoothing.
PROp3d_misc_mean_smooth_small
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).
PROp3d_misc_median_smooth
This routine calculates a two-dimensional array smoothing.
PROp3d_misc_mmodhdr
For detectors that are read out to several files (blocks), this file adds some block-specific header keywords to the input fits header variable.
PROp3d_misc_obsprop
This routine retrieves observation-related properties from a fits-file header, or sometimes from the instrument-keywords file.
FUNCTIONp3d_misc_odetsec
Calculates a detector-section array for the output image, using the raw-data detector-section array.
FUNCTIONp3d_misc_pathify
This routine takes a string as input and checks if it contains either !p3d_path or !p3d_data_path (/DPATH).
FUNCTIONp3d_misc_profunction
Calculates a functional value, or an array of values, using a defined set of input parameters.
PROp3d_misc_read_deadfibers_file
This routine reads the dead fibers file.
PROp3d_misc_read_gapsfile
Reads the contents of the spectrum gaps file.
PROp3d_misc_read_params
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.
PROp3d_misc_read_postable
Reads a spatial element position file, and returns the contents.
PROp3d_misc_retrieve_ifunumber
Retrieves the instrument-specific IFU number, for those instruments that use more than one IFU in the same setup file (such as VIRUS).
PROp3d_misc_retrieve_lprofs
Routine description pending.
PROp3d_misc_rss2cube
This routine converts a two-dimensional row-stacked spectrum (RSS) data image into a three-dimensional data cube.
PROp3d_misc_sauron_colormap
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.
PROp3d_misc_smooth_1d
This routine provides an array smoothing algorithm.
FUNCTIONp3d_misc_spaxelscale
Retrieves information on the spatial-element scale size.
PROp3d_misc_sv_widget_geometry
This routine calculates all widget sizes according to the defined size of the spectrum viewer; this routine is used when the tool is resized.
PROp3d_misc_wcs_setup
Sets up the World Coordinate System information used by p3d.
PROp3d_misc_write_fitsfiles
This routine writes all output data fits files, either to separate files or to consecutive extensions.

Copyright

p3d: a general data-reduction tool for fiber-fed IFSs

Copyright 2009-2012, 2014, 2015, 2017 Leibniz Institute for Astrophysics Potsdam (AIP)

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

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

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

Additional permission under GNU GPL version 3 section 7

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

Routine Documentation

routines/p3d_misc_2dgaussfit.pro, line 160, last changed at 2017-06-06 by christersandin (revision 4602)

p3d_misc_2dgaussfit, z, dz, fwhm=, x0=, y0=, wav0=, opar=, valid=, topwid=, logunit=, verbose=, error=, /debug, /help

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

Input parameters:
zA 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:
dzA 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:
fwhmA 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, *
wav0integer 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, *
oparUpon 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

validUpon 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.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_binextract.pro, line 122, last changed at 2017-06-28 by christersandin (revision 4659)

p3d_misc_binextract, kwrdlist, hdr, xbin=, ybin=, userparfile=, topwid=, logunit=, verbose=, error=, /debug, /help

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:
kwrdlistThe name of a file, that contains a two-column list of parameters to use with p3d for the instrument in question.
hdrA string array with the fits file data keyword header.
Keyword parameters:
xbinA scalar integer that returns XBIN.
ybinA scalar integer that returns YBIN.
userparfileA 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.
topwidIf set, error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_bins_file_read.pro, line 201, last changed at 2016-07-18 by christersandin (revision 4358)

p3d_misc_bins_file_read, filename, bindata, nbins, extension=, col_binidx=, col_x=, col_y=, topwid=, logunit=, verbose=, error=, /debug, /help

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:

binlow [- 1]

Specifies the lower bin on the dispersion axis used to calculate the bins; the first bin is 1. For example, the line could be written "; binlow = 327".

binupp [- 1]

Specifies the upper bin on the dispersion axis used to calculate the bins; the first bin is 1. The parameter binupp must satisfy binupp >= binlow. For example, the line could be written "; binupp = 331".

targetSN [- 1d0]

Specifies the target signal-to-noise ratio used in the calculation of the bins. For example, the line could be written "; targetSN = 137.0".

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:

BINLOW [- 1]

Specifies the lower bin on the dispersion axis used to calculate the bins; the first bin is 1. For example, the line could be written "; binlow = 327".

BINUPP [- 1]

Specifies the upper bin on the dispersion axis used to calculate the bins; the first bin is 1. The parameter binupp must satisfy binupp >= binlow. For example, the line could be written "; binupp = 331".

TARGETSN [- 1d0]

Specifies the target signal-to-noise ratio used in the calculation of the bins. For example, the line could be written "; targetSN = 137.0".

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:
filenameA scalar string with the name of the bins file to read.
Optional parameters:
nbinsA 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_xA scalar string that specifies the name of the column with the x positions. The default value is: 'X'
col_yA scalar string that specifies the name of the column with the y positions. The default value is: 'Y'
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
bindataA 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.

routines/p3d_misc_bins_file_write.pro, line 113, last changed at 2016-07-07 by christersandin (revision 4293)

p3d_misc_bins_file_write, filename, binlow, binupp, targetSN, bindata, source=, revision=, tool=, /append, topwid=, logunit=, verbose=, error=, /debug, /help

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

Input parameters:
filenameA scalar string with the name of the bins map file to write.
binlowA scalar integer with the lower bin used in the input file.
binuppA scalar integer with the higher bin used in the input file.
targetSNA scalar decimal value with the target signal-to-noise value used in the binning.
bindataAn IDL structure with the bins and the //x// and //y// positions of each spatial element: bins, x, y.
Keyword parameters:
sourceA scalar string with the name of the used source cube or RSS file.
revisionA scalar integer with the revision of TOOL.
toolA scalar string with the name of the tool, whose name is added to the output file.
appendSet this keyword to append the Voronoi bin map to a new extension in an already existing fits file.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_checkfile.pro, line 111, last changed at 2017-06-28 by christersandin (revision 4659)

p3d_misc_checkfile, file, ndetectors, detector, kwrdlist, topwid=, logunit=, verbose=, error=, /debug

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:
fileThe filename of the data fits file to check.
ndetectorsA scalar integer that specifies the total number of detectors.
detectorA scalar integer that specifies the id of the current detector.
kwrdlistA scalar string that specifies the name of a file that contains a list of instrument-specific keyword names.
Keyword parameters:
topwidIf set, error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_checkob.pro, line 107, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_checkob, files, type, kwrdlist, topwid=, logunit=, verbose=, error=, /debug

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:
filesA string array with the names of fits files. At least two files must be specified!
typeA string array with the same number of elements as FILES. Each element of TYPE is a four-character string.
kwrdlistA scalar string that specifies the name of a file that contains a list of instrument-specific keyword names.
Keyword parameters:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_choose.pro, line 410, last changed at 2017-06-06 by christersandin (revision 4602)

odata = p3d_misc_choose(defv, verbose=, error=, /debug)

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

Input parameters:
defvA structure containing default paths and additional parameters such as the window title for each instrument.
Keyword parameters:
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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:
odataA structure containing the chosen instrument parameters.

routines/p3d_misc_colortable.pro, line 216, last changed at 2016-05-26 by christersandin (revision 4163)

p3d_misc_colortable, colortable, bottom=, index=, indv=, define=, name=, colors=, offset=, ch_start=, ch_rots=, ch_gamma=, ch_hue=, /invert, topwid=, logunit=, verbose=, error=, /debug, /help

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:
colortableA 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:
bottomA 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
indexAn 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
indvA 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].
defineIf 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

nameThis output keyword returns the name of the loaded color table.
colorsThis output keyword structure returns the loaded color arrays as: colors.red, colors.green, and colors.blue.
offsetA scalar integer that returns an offset depending on how many additional color tables have been. defined. Currently OFFSET = 3.
ch_startScalar decimal value (used if COLORTABLE = -4). The default value is: 0.5
ch_rotsScalar decimal value (used if COLORTABLE = -4). The default value is: -1.5
ch_gammaScalar decimal value (used if COLORTABLE = -4). The default value is: 1.0
ch_hueScalar decimal value (used if COLORTABLE = -4). The default value is: 1.2
invertSet this keyword to invert the color table.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Side effects:

Modifies the color table.

routines/p3d_misc_colortable_widget_menu.pro, line 179, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_misc_colortable_widget_menu, widid, wid_base, wid_xloadct, wid_invert, colortable=, /invert, strout=, /tracking_events, font=, topwid=, logunit=, verbose=, error=, /debug, /help

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:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_colorval.pro, line 66, last changed at 2016-04-08 by christersandin (revision 4087)

value = p3d_misc_colorval(str), unknown

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:
strA scalar string with the color name.
Output parameters:
valueA scalar long value with the color value. The value 0 is returned if the color name was unidentified.

routines/p3d_misc_correlate_arrays.pro, line 102, last changed at 2015-10-19 by christersandin (revision 3628)

doffset = p3d_misc_correlate_arrays(veca, vecb, topwid=, logunit=, verbose=, error=, /debug, /help)

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:
vecaA one-dimensional array of decimal type.
vecbA one-dimensional array of decimal type.
Keyword parameters:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
doffsetA scalar decimal value containing the optimal offset of VECB relative to VECA.

routines/p3d_misc_cube2rss.pro, line 159, last changed at 2016-07-15 by christersandin (revision 4353)

p3d_misc_cube2rss, cube, rssdata, dcube, drssdata, angle=, daxis=, predata=, use=, posfile=, posdata=, sifunum=, /noremove, /crebuild, /noC, nthreads=, topwid=, logunit=, verbose=, error=, /debug, /cdebug, /help

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:
cubeA 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:
dcubeA three-dimensional error data cube. Formatted as CUBE.
Keyword parameters:
angleA 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
daxisDefines 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
predataA 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.
useAn integer array that specifies which elements to copy to the RSS image. Useful when doing the errors array immediately after the data array.
posfileA scalar string with the fiber-position table filename corresponding to the RSSDATA variable. Position-table data are calculated when POSFILE is unset, see POSDATA.
posdataThis 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.
sifunumThis keyword is used with p3d_misc_read_postable.pro.
noremoveIf unset, then zero-arrays are removed before the POSDATA structure is returned. The default value is: 0
crebuild
noC
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
cdebugA keyword as DEBUG used with the called C routines.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
rssdataA two-dimensional array with RSS-data. The data format is: DAXIS = 1: [# of wavel., # of spatial elements] DAXIS = 2: [# of spatial elements, # of wavel.]

routines/p3d_misc_cubehelix_colormap.pro, line 116, last changed at 2015-11-06 by christersandin (revision 3756)

p3d_misc_cubehelix_colormap, start=, rots=, gamma=, hue=, ncolors=, bottom=, /invert, verbose=

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:
startColor; 1=red, 2=green, 3=blue. For example, 0.5=purple. The default value is: 0.5
rotsRotations in colour; typically -1.5-1.5. The default value is: -1.5
hueHue 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
gammaThe gamma correction for the intensity. The default value is: 1.0
ncolorsA scalar integer specifying the number of colors to use. The default value is: !d.table_size
bottomA 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
invertSet this keyword to invert the color table.
verboseSet 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.

routines/p3d_misc_dataclip.pro, line 106, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_dataclip, array, range, percentage=, topwid=, logunit=, verbose=, error=, /debug, /help

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:
arrayAn array of decimal type. This is the data array that is used to calculate the range values. It can have any dimensions.
Keyword parameters:
percentageRANGE is calculated to embrace with many percent of all pixel values in ARRAY. The default value is: 95.0
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
rangeA two-element array returning the lower and upper limits calculated in this routine.

routines/p3d_misc_detsec.pro, line 280, last changed at 2017-06-28 by christersandin (revision 4659)

p3d_misc_detsec, hdr, kwrdlist, parfile, detsec, odetsec, detector=, userparfile=, blocknx=, blockny=, topwid=, logunit=, verbose=, error=, /debug, /help

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:

1.

DETSEC is specified in USERPARFILE (see below).

2.

DETSEC is read from the object data header, if it exists. In order to use this function the proper DETSEC must be defined in the instrument keywords file.

3.

DETSEC is read from the instrument-parameter file.

4.

DETSEC is read from the object data header as separate numbers, if they exist. In order to use this function the proper keywords must be specified in the instrument keywords file. The required properties are:

DETSEC_X0

The x axis readout coordinate of the current block. May be absent if there is only one block, in this case this property is set to 0.

DETSEC_PX

The size of the prescan region on the x axis of the current block. When absent it is set to 0.

DETSEC_OX

The size of the overscan region on the x axis of the current block. When absent it is set to 0.

DETSEC_NX

The number of elements on the x axis in the current block. May be absent if there is only one block, in this case this property is calculated as: NAXIS1-PX-OX.

DETSEC_Y0

The y axis readout coordinate of the current block. May be absent if there is only one block, in this case this property is set to 0.

DETSEC_PY

The size of the prescan region on the y axis of the current block. When absent it is set to 0.

DETSEC_OY

The size of the overscan region on the y axis of the current block. When absent it is set to 0.

DETSEC_NY

The number of elements on the y axis in the current block. May be absent if there is only one block, in this case this property is calculated as: NAXIS2-PY-OY.

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

x_start

used region, the first pixel in x.

x_end

used region, the last pixel in x.

y_start

used region, the first pixel in y.

y_end

used region, the last pixel in y.

The first pixel is specified as 1 (despite IDL using 0-based indices).

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:
hdrAn string array with the fits-file header of the file that should be parsed for the detector area.
kwrdlistA 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.
parfileA scalar string with the name of a file, that contains a two-column list of instrument-specific parameters.
Keyword parameters:
detectorA scalar integer that specifies the currently selected detector; DETECTOR is a zero-based value. The default value is: 0
userparfileA 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.
blocknxAn 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.
blocknyAn 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.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
detsecA 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.
odetsecLike DETSEC, but this array has not been flipped on the dispersion axis.

routines/p3d_misc_detsec_str2val.pro, line 63, last changed at 2017-06-06 by christersandin (revision 4602)

p3d_misc_detsec_str2val, str, num, string

Provides a support routine for p3d_misc_detsec.

routines/p3d_misc_e3dio_read.pro, line 85, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_e3dio_read, fname, rss=, xpos=, ypos=, size=, shape=, topwid=, logunit=, error=, verbose=, /debug, /help

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
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
errorReturns an error code if set
verboseShow more information on what is being done
debugThe error handler is not setup if debug is set.
helpShow this routine documentation, and exit

routines/p3d_misc_e3dio_write.pro, line 551, last changed at 2015-10-27 by christersandin (revision 3695)

p3d_misc_e3dio_write, rss, xpos, ypos, e3dname, hdr=, stat=, shape=, size=, ctype=, crval=, cdelt=, /compress, nthreads=, verbose=, error=, /debug, /help

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
compressIf this keyword is set then the output file is compressed, if possible, using gzip.
nthreadsA scalar integer that specifies how many threads to use in the parallelized output file compression. The default value is: max
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_errors.pro, line 73, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_errors, error_status, rname=, unit=, topwid=

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_statusAn integer with the error code.
Keyword parameters:
rname- The name of the routine where the error occurred. The default value is: 'p3d_misc_logger'
unitA scalar integer with the value of a file unit, that, if it is open, is closed.
topwidIf set, then the error message (iff ERROR) is shown using a dialog instead of printing the message on the console.

routines/p3d_misc_extract_method.pro, line 125, last changed at 2015-10-19 by christersandin (revision 3628)

method = p3d_misc_extract_method(userparfile, tracemask=, keyword=, topwid=, logunit=, verbose=, error=, /debug, /help)

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:
userparfileA 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'
tracemaskIf 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'.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
methodA scalar string containing the used spectrum extraction method; this is either "tophat" or "optimal".

routines/p3d_misc_fileallbl.pro, line 124, last changed at 2016-02-19 by christersandin (revision 4002)

p3d_misc_fileallbl, filename, fsfx, nblocks, bsfx, nfilename, nfsfx, /blocksarecombined, orig_filename_kwd=, topwid=, logunit=, verbose=, error=, /debug, /help

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:
filenameAn array of strings with raw-data filenames.
fsfxAn 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.
nblocksA scalar integer that indicates the number of blocks of the current instrument data. This routine returns immediately if NBLOCKS is equal to 1.
bsfxA string array with NBLOCKS elements, which contains a block-specific string that is used to identify files of each block.
Keyword parameters:
blocksarecombinedIf this keyword is set the routine returns mediately, as all blocks are contained in the me raw-data image.
orig_filename_kwdThis keyword provides a name for raw-data files that also e of an originally used filename. The default value is: 'FILENAME'
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
nfilenameA string array with the dimensions [n_elements(FILENAME), NBLOCKS], which upon return contains a unique list of filenames (columns) for each block (rows).
nfsfxA string array with the same dimensions as NFILENAME, which upon return contains the filename suffix for each file in NFILENAME.

routines/p3d_misc_findpath.pro, line 160, last changed at 2017-06-28 by christersandin (revision 4659)

ofile = p3d_misc_findpath(filename, /curdir, altdir=, /dlldir, defstr=, /replacefull, /allownofile, found=, /allowcompressed, topwid=, logunit=, verbose=, error=, /debug, /help)

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:

i) No other directory

No additional attempt is performed if the filename already contains a path separator character. The file is simply reported as missing if it does not exist in the specified path.

ii) The current directory (/CURDIR)

The file is searched for in the (current) directory where p3d is running from.

iii) Alternative dirs. (ALTDIR='...' or ['...', '...', ...])

The file is searched for in each of the specified directories, until it is found. Note that each entry of ALTDIR must exist and be a directory.

iv) The p3d default line-list directory (/DLLDIR)

The file is searched for in the directory "${p3d_path}/data/tables/linelists". In this case it is allowed to specify FILENAME = "lores" or FILENAME = "hires" (the names are both case insensitive), which simply results in the use of either one of the default line-list files "telluric_lines_lores.dat" or "telluric_lines_hires.dat".

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

Input parameters:
filenameA scalar string, or an array of strings, that contains the filename(s), which is/are searched for by this routine.
Keyword parameters:
curdirIf this keyword is set, the file FILENAME is searched for in the current directory.
altdirThis 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.
dlldirIf 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'.
defstrA scalar string that should contain an informative text regarding which kind of file is searched for. The default value is: ''
replacefullSet this keyword to allow the replacement of an already specified path with another path.
allownofileSet this keyword to return without an error when a file does not exist.
foundReturns a integer scalar, or an array, with as many elements as FILENAME, specifying if a file was found (1) or not (0).
allowcompressedSet this keyword to also look for the compressed file if FILENAME is non-compressed, using gzip ('.gz'), or vice versa.
topwidIf set, error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_findspec.pro, line 119, last changed at 2015-10-19 by christersandin (revision 3628)

ret = p3d_misc_findspec(specnum, maxnum, deadfibers=, logstr=, topwid=, logunit=, verbose=, error=, /debug, /help)

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:
specnumInitial 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.
maxnumA scalar integer specifying the maximum allowed number + 1 of the return value.
deadfibersA 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:
logstrReturns a scalar string with the outcome of the value search for logging purposes.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
retA scalar integer with the number of the spectrum to use.

routines/p3d_misc_fitsstrad.pro, line 92, last changed at 2017-06-28 by christersandin (revision 4659)

p3d_misc_fitsstrad, hdr, str, value, comment, topwid=, logunit=, verbose=, error=, /debug, /help

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:
hdrA string array with the fits file data keyword header.
strA scalar string specifying the keyword which value will be added to HDR.
valueA scalar number or string, which is to be added to HDR.
Optional parameters:
commentA scalar string with a comment that is added to the header.
Keyword parameters:
topwidIf set, error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseShow more information on what is being done.
errorReturns an error code if set.
debugThe error handler is not setup if debug is set.
helpShow this routine documentation, and exit.
Side effects:

Edits the contents of the HDR keyword.

routines/p3d_misc_fitsstrex.pro, line 114, last changed at 2017-06-06 by christersandin (revision 4602)

ret = p3d_misc_fitsstrex(hdr, str, ahdr=, index=, /converthourtodeg, /convertstrtodeg, /convertstrtosec, /noconvert, /insertcolons, comment=, topwid=, logunit=, verbose=, error=, /debug, /help)

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:
hdrA string array with the fits file data keyword header.
strA scalar string specifying the keyword which value will be read from HDR.
Keyword parameters:
ahdrA string array with an alternative fits-file keyword header that is used if the keyword STR is not found in HDR.
indexA two-element integer array with the position of STR in HDR [0], or AHDR[1]; the default value is -1.
converthourtodegIf 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.
convertstrtodegIf 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.
convertstrtosecIf 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.
noconvertNo attempt to convert the result to an integer or a decimal value is attempted if this keyword is set.
insertcolonsIf 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.
commentReturns the read comment.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseShow more information on what is being done.
errorReturns an error code if set.
debugThe error handler is not setup if debug is set.
helpShow this routine documentation, and exit.
Output parameters:
retA scalar value containing the returned value.

routines/p3d_misc_fluxcal_read_file_atmospheric_extinction.pro, line 222, last changed at 2016-02-19 by christersandin (revision 4002)

p3d_misc_fluxcal_read_file_atmospheric_extinction, extfile=, ext_wavelength=, extinction=, ext_error=, waveunit=, logunit=, topwid=, verbose=, error=, /debug, /help

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:

EXT_WAVELENGTH

the wavelength array; [Angstrom] ([Å]).

EXTINCTION

the standard-star flux array; [mag/airmass].

EXT_ERROR

the atmospheric extinction error array; [mag/airmass].

Keyword parameters:
ext_wavelengthUpon output this keyword contains the read wavelength array, in [Angstrom] ([Å]).
extinctionUpon output this keyword contains the read extinction, in [mag/airmass].
ext_errorUpon output, and if the property is available, this keyword contains the read extinction error, in [mag/airmass].
waveunitA 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.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_fluxcal_read_file_standard_star.pro, line 395, last changed at 2017-06-06 by christersandin (revision 4602)

p3d_misc_fluxcal_read_file_standard_star, ssfile, catalog=, ss_wavelength=, ss_bpw=, ss_flux=, ss_errorflux=, fluxunit=, waveunit=, ofilename=, use=, /compress, /ecalc, target_extension=, target_id=, target_extname=, target_cal=, font=, logunit=, topwid=, verbose=, error=, /debug, /help

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:

SS_WAVELENGTH

the wavelength array; [Angstrom] ([Å]).

SS_BPW

the bandpass-width array; [Angstrom] ([Å]).

SS_FLUX

the standard-star flux array; [erg/cm²/s/Å].

SS_ERRORFLUX

the standard-star flux error array; [erg/cm²/s/Å].

= Links =

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:
catalogA 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_wavelengthUpon output this keyword contains the read wavelength array, in [Angstrom] ([Å]).
ss_bpwUpon output, and if the property is available, this keyword contains the read bandpass width, in [Angstrom] ([Å]).
ss_fluxUpon output this keyword contains the read flux, in [erg/cm/cm/s/Å].
ss_errorfluxUpon output, and if the property is available, this keyword contains the read flux error, in [erg/cm/cm/s/Å].
fluxunitA 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.
waveunitA 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.
ofilenameA scalar string, which, if present, data are saved to a plain-text file with this name. The file is compressed if COMPRESS is set.
useAn integer array with as many elements as the read data; zero elements indicate removed entries. This keyword is only used when OFILENAME is set.
compressIf this keyword is set the output text file is compressed using gzip.
ecalcThis 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_extensionA scalar integer with the extension to read in ulti-extension files.
target_idA scalar string used to select the default extension in multi-extension files; this keyword is only used if TARGET_EXTENSION is unset.
target_extnameA scalar string returning the name of the used extension; set when TARGET_EXTENSION is set.
target_calA scalar string used to select the default extension in the multi-extension calibration file.
fontA scalar string with the name of the font to use in the extension-selection widget tool.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_fluxcal_read_file_standard_star_gui.pro, line 156, last changed at 2015-11-05 by christersandin (revision 3744)

p3d_misc_fluxcal_read_file_standard_star_gui, extname, select, altname=, index=, target_id=, target_cal=, font=, topwid=, verbose=, error=, /debug

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

Input parameters:
extnameextension string array.

routines/p3d_misc_fshift.pro, line 125, last changed at 2017-06-06 by christersandin (revision 4602)

oimage = p3d_misc_fshift(image, dx, dy, doimage, dimage=, topwid=, logunit=, verbose=, error=, /debug, /help)

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:
imageA two-dimensional decimal value array that contains the image that will be shifted.
dxA 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.
dyA 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:
dimageA two-dimensional decimal value array that contains the error image that will be shifted. wavelength [Å].
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
oimageA two-dimensional decimal value array that contains the shifted image.

routines/p3d_misc_fxdelpar.pro, line 103, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_fxdelpar, hdr, delstr, /quiet, topwid=, logunit=, verbose=, error=, /debug, /help

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

Input parameters:
delstrA scalar string, or an array of strings, specifying the keyword which be removed from the header HDR.
Keyword parameters:
quietNo logging information is saved if this keyword is set.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_get_callext_exlib.pro, line 104, last changed at 2016-07-09 by christersandin (revision 4317)

libname = p3d_misc_get_callext_exlib(rebuild, cifsfit_lib=, /noC, topwid=, logunit=, verbose=, error=, /debug, /cdebug)

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:
rebuildIf this keyword is set, the shared library is rebuilt, even if it already exists.
Keyword parameters:
cifsfit_libThis scalar string returns the name of the compiled, or found shared-library file for p3d_cifsfit.
noCNo attempt is made to compile or use the C library if this keyword is set.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
cdebugA keyword as DEBUG used with the called C routines.
Output parameters:
libnameThis scalar string returns the name of the compiled, or found shared-library file.
Side effects:

Compiles a shared library.

routines/p3d_misc_get_hdr_kwrd.pro, line 107, last changed at 2016-02-22 by christersandin (revision 4003)

ret = p3d_misc_get_hdr_kwrd(table, p3d_kwrd, topwid=, logunit=, verbose=, error=, /debug, /help)

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:
tableName of the keyword translation table.
p3d_kwrdName of the keyword p3d uses.
Keyword parameters:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
retName of the fitsheader keyword, it is set to -1 if the keyword was not found.

routines/p3d_misc_getinformation.pro, line 242, last changed at 2017-06-28 by christersandin (revision 4659)

p3d_misc_getinformation, filenames, kwrdlist, masterbias=, dbias=, gain=, rdnoise=, userparfile=, ndetectors=, nblocks=, nextensions=, index=, kwgain=, /rawdataarecombined, topwid=, logunit=, verbose=, error=, /debug, /help

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:

1.

The gain and the readout-noise values were already determined if the keywords CRDNOIx are found in the header. In this case there is no checking of units, CRDNOI and GAIN are expected to have the correct units (as used in p3d; i.e. ADU and e-/ADU). This is the case with images that were combined by p3d with p3d_misc_imcombine.

2.

Alternatively, if the header keyword NCOMBINE is found in a specified master-bias image file then the error of every pixel value of the master-bias image can be calculated – and thereafter also other errors. In this case the gain and the readout-noise values are read from the user-parameter file, using explicitly set values in the instrument-specific header keywords file, or reading the data header.

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:
filenamesA 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.
kwrdlistA scalar string with the name of a file that contains instrument-specific keyword names for use with p3d.
Keyword parameters:
masterbiasA 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.
dbiasA 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.
gainA scalar decimal value that returns the CCD gain values, in units of e-/ADU.
rdnoiseA scalar decimal value that returns the CCD readout-noise values, in units of ADU.
userparfileA 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.
ndetectorsA scalar integer that indicates the number of instrument configurations that are used in the instrument-specific parameter file.
nblocksA scalar integer that indicates the number of data blocks that belong to one detector.
nextensionsA scalar integer that indicates the number of extensions in multi-extension images.
indexIf 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.
kwgainUnless CRDNOI1 is set this keyword returns the name of the keyword used with the chosen detector (of KWRDLIST).
rawdataarecombinedWhen this keyword is set, raw data of separate cks are read from separate files, which are then bined into one image.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_headercombine.pro, line 109, last changed at 2017-06-28 by christersandin (revision 4659)

p3d_misc_headercombine, hdr1, hdr2, ohdr, /delext, topwid=, logunit=, verbose=, error=, /debug, /help

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:
hdr1The first fits file header.
hdr2The second fits file header.
Keyword parameters:
delextIf set, the 'EXTEND' and 'XTENSION' keywords are removed from the resulting header array.
topwidIf set, error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
ohdrThe output fits file header.

routines/p3d_misc_imcombine.pro, line 264, last changed at 2016-07-04 by christersandin (revision 4282)

p3d_misc_imcombine, filename, out, nval, rstr, method=, detsec=, nextensions=, blocksarecombined=, /rawdataarecombined, rawflip=, cumulativedetsep=, prescanx=, prescany=, overscanx=, overscany=, blocknx=, blockny=, daxis=, /dflip, /spatialflip, userparfile=, parfile=, nthreads=, stawid=, topwid=, logunit=, verbose=, error=, /debug, /cdebug, /help

This routine combines raw images in two senses:

1.

A combined image is created by taking the average, median, or min/max-average [default] of the available values for every pixel, using three or more input files. The method can only be set using the user-parameter file. If the method min/max is used, the minimum and the maximum values of every pixel are discarded; the output parameter NVAL is decremented by 2 to reflect this filtering.

The method can be selected among the following four options:

'mean'

A mean is calculated for each pixel separately, using all images.

'average'

This option is equivalent to 'mean'.

'median'

The median is calculated for each pixel separately, using all images.

['minmax']

For each additional number of ten input images, the lowest and the highest pixel values are discarded; this is the default method. The discarding procedure is repeated as many times as necessary when the total number of images is greater than the value of the user parameter (imcomb_minmaxgroupn [10]).

2.

If the input array of filenames has a second dimension, data are combined across that second dimension to create a larger final output image. This way data are handled that have been read out in separate blocks from the CCD. Data are combined using information in the DETSEC input array. No checking is done here if data of different blocks belong to each other.

Input parameters:
filenameA 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:
methodA scalar string that optionally defines the image combination method. If this keyword is set, the value is not read from the user-parameter file.
detsecA 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.
nextensionsA 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
blocksarecombinedA scalar integer that specifies if multi-block ages are available in separate files (0) or in e same file. In the latter case, OCKSARECOMBINED must equal the number of blocks.
rawdataarecombinedWhen this keyword is set, raw data of separate cks are read from separate files, which are then bined into one image.
rawflipThis 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).
cumulativedetsepAn 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.
prescanxThis 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.
prescanyThis 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.
overscanxThis 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.
overscanyThis 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.
blocknxWhen BLOCKSARECOMBINED is set, this integer array defines the total number of pixels on the x-axis for each block in the raw data.
blocknyWhen BLOCKSARECOMBINED is set, this integer array defines the total number of pixels on the y-axis for each block in the raw data.
daxisA 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
dflipIf this keyword is set, the prescan and the overscan arrays are flipped, for the axis that coincides with DAXIS.
spatialflipIf 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
userparfileA 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().
parfileA 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.
nthreadsA 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
stawidIf set to a valid ID, a log message is written using this ID for relevant actions.
topwidIf set, error messages are displayed using DIALOG_MESSAGE with this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed at by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
cdebugA keyword as DEBUG used with the called C routines.
helpSet this keyword to show this routine documentation and then exit.
Output parameters:
outThe 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.
nvalA scalar integer containing the final number of pixels used in the combination procedure.
rstrA scalar string with information on the image combination method that was used.

routines/p3d_misc_imcombine_wrapper.pro, line 308, last changed at 2017-06-28 by christersandin (revision 4659)

p3d_misc_imcombine_wrapper, filename, ofilename, ofsfx, odata, detsec=, /bias, /dmask, ostr=, mostr=, method=, cumulativedetsep=, prescanx=, prescany=, overscanx=, overscany=, biasconstant=, parfile=, userparfile=, detector=, opath=, opfx=, sfx=, xstr=, /dsh, /compress, title=, /dflip, /donotwrite, ohdr=, nthreads=, stawid=, topwid=, logunit=, verbose=, error=, /debug, /cdebug, /help

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:
filenameA scalar or a one-dimensional array of filenames, which contents are to be combined.
Keyword parameters:
detsecThis 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.
mbiasIf this keyword is set, the filename is appended with the string in MOSTR instead of OSTR. The default value is: 0
dmaskIf this keyword is set, it is possible to call this routine also with a two-element array for FILENAME. The default value is: 0
ostrA scalar string with the image-combination specific string used to create the output filename. The default value is: '_imcmb'
mostrA scalar string with the master-bias specific tring used to create the output filename. The default value is: '_mbias'
methodA scalar string passed on to p3d_misc_imcombine.
cumulativedetsepAn integer array with two columns and as many rows s there are blocks. Each column specifies a umulative offset on the x- and y-axes for each lock. All elements must be >= 0, the default is 0. his parameter is only used if BLOCKSARECOMBINED is et.
prescanxThis 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.
prescanyThis 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.
overscanxThis 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.
overscanyThis 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.
biasconstantThis keyword is used with multi-block instruments that use the 'blocksarecombined', 'nblocks', or 'nextensions' instrument parameters.
parfileA scalar string that specifies the name of a file with instrument-specific setup parameters.
userparfileA scalar string with the name of a file with user- defined parameters.
detectorA scalar integer that specifies the currently selected detector; DETECTOR is a zero-based value. The default value is: 0
opathA scalar string that specifies the path, where the output image is saved. The default value is: '.'
opfxA scalar string specifying a prefix of the output filename. The default value is: ''
sfxA scalar string specifying the file ending (without a trailing compression suffix, such as .gz or .Z). The default value is: '.fits'
xstrTo be filled in... The default value is: ''
dshThis flag upon exit indicates whether anything was done by this routine (1) or not (0).
compressIf this keyword is set, the output image file is compressed using gzip. The default value is: 0
titleThis scalar string is used to mark in the output file which kind of data this is. The default value is: ' '
dflipThis keyword is set if the image is flipped on the dispersion axis before the routine is exited. The default value is: 0
donotwriteNo output file is written if this keyword is set.
ohdrUpon return this keyword contains the written output header, if DONOTWRITE is set.
nthreadsA 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
stawidIf set to a valid ID, a log message is written using this widget ID for relevant actions.
topwidIf set, error messages are displayed using DIALOG_MESSAGE with this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
cdebugA keyword as DEBUG used with the called C routines.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
ofilenameThe 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.
ofsfxThe file suffix(es) corresponding to OFILENAME.
odataContains the combined output image.

routines/p3d_misc_initialize.pro, line 211, last changed at 2016-07-20 by christersandin (revision 4372)

p3d_misc_initialize, p3d_path, mpfitpresent, /ds9present, /quiet, /verbose=, error=, /help

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_pathA 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:
ds9presentIf the binary 'ds9' is found in the system path, this keyword is set.
quietNo informational message about missing cmpfit files is displayed if this keyword is set.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
mpfitpresentThis keyword is set if mpfit.pro is found in !path.
Side effects:

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

routines/p3d_misc_logger.pro, line 110, last changed at 2017-06-28 by christersandin (revision 4659)

ret = p3d_misc_logger(logstr, funit, rname=, loglevel=, topwid=, verbose=, error=)

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

Input parameters:
logstrThe string to print. Can be an array of strings.
Optional parameters:
funitIf 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:
rnameThe name of the routine calling. The default value is: 'p3d_misc_logger'
loglevelBefore 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
topwidIf set, the error message (iff ERROR) is shown using a dialog instead of printing the message on the console.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
Output parameters:
retReturns -1 if error is non-zero, otherwise 0.

routines/p3d_misc_logger_dt.pro, line 69, last changed at 2016-04-05 by christersandin (revision 4056)

ret = p3d_misc_logger_dt(loglevel), unknown

Creates a suitably formatted date and time string.

Optional parameters:
loglevelAdds the log level to the output string.
Output parameters:
retReturns the date string.

routines/p3d_misc_mean_smooth.pro, line 102, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_mean_smooth, image, out, xbox, ybox, topwid=, logunit=, verbose=, error=, /debug, /help

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:
imageA two-dimensional array.
xboxThe half x-width of the filter smoothing box.
yboxThe half y-width of the filter smoothing box.
Keyword parameters:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
out2D image

routines/p3d_misc_mean_smooth_small.pro, line 117, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_mean_smooth_small, array, pos, smowidth, out, outpos, topwid=, logunit=, verbose=, error=, /debug, /help

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:
arrayA two-dimensional array of floating point values.
posA one-dimensional array of floating point values, which specify pixels in the dispersion direction, for which the smoothing is made.
smowidthA scalar decimal value. The average value is calculated for a dispersion region of width 2*smowidth+1.
Keyword parameters:
daxisDefines the dispersion direction dimension of IMAGE. The default, 1, is in the x-direction. The default value is: 1
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
outA one-dimensional array of decimal values containing the cross-dispersion direction averaged spectrum values.
outposA 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.

routines/p3d_misc_median_smooth.pro, line 101, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_median_smooth, image, out, xbox, ybox, topwid=, logunit=, verbose=, error=, /debug, /help

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:
arrayA two-dimensional array.
xboxThe half x-width of the filter smoothing box.
yboxThe half y-width of the filter smoothing box.
Keyword parameters:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
outA two-dimensional array.

routines/p3d_misc_mmodhdr.pro, line 151, last changed at 2017-06-28 by christersandin (revision 4659)

p3d_misc_mmodhdr, hdr, data, gain, detsec=, prescanx=, prescany=, overscanx=, overscany=, /blocksarecombined, userparfile=, ndetectors=, nblocks=, nextensions=, cumulativedetsep=, /rawdataarecombined, topwid=, logunit=, verbose=, error=, /debug, /help

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:
detsecA 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.
prescanxThis structure is, when provided, scaled using the same scaling factor as the main data.
prescanyThis structure is, when provided, scaled using the same scaling factor as the main data.
overscanxThis structure is, when provided, scaled using the same scaling factor as the main data.
overscanyThis structure is, when provided, scaled using the same scaling factor as the main data.
blocksarecombinedIf this keyword is set, the gain and the adout-noise values of the different blocks are l found in the same image header.
userparfileA scalar string with the name of a file with user-defined parameters.
ndetectorsA scalar integer that indicates the number of detectors used in the instrument-parameter file.
nblocksA scalar integer that indicates the number of data blocks that belong to one detector.
nextensionsIf this scalar is used, this many file extensions of one file are used instead of several files. The default value is: 0
cumulativedetsepThis keyword is passed on to p3d_misc_odetsec.
rawdataarecombinedWhen this keyword is set, raw data of separate cks are read from separate files, which are then bined into one image.
topwidIf set, error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_obsprop.pro, line 322, last changed at 2015-12-11 by christersandin (revision 3896)

p3d_misc_obsprop, hdr, ahdr=, kwrdlist=, ra_offset=, dec_offset=, spaxelscale=, airmass=, origairmass=, parang=, origparang=, declination=, origdeclination=, rightascension=, origrightascension=, localsiderealtime=, zenithdistance=, origzenithdistance=, hourangle=, orighourangle=, azhourangle=, latitude=, origlatitude=, obselevation=, origobselevation=, azimuth=, gs_airmass=, gs_zenithdistance=, gs_declination=, gs_rightascension=, gs_hourangle=, topwid=, logunit=, verbose=, error=, /debug, /help

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 hour angle

When the azimuth angle is available it is used to calculate the hour angle in addition of using the regular hour-angle-formula.

Effective airmass

The routine calculates the effective airmass using the starting and ending parallactic angle, when available.

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

Links

The IFS Wiki

http://ifs.wikidot.com

The Starlink project

http://starlink.jach.hawaii.edu/starlink

Keyword parameters:
ahdrA string array with an alternative header array.
ra_offsetA 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_offsetA 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
spaxelscaleA 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.
kwrdlistA scalar string with the name of a file that contains instrument-specific keyword names for use with p3d.
airmassA scalar decimal value that contains the finally calculated airmass.
origairmassA scalar string that indicates how the airmass was calculated.
parangA scalar decimal value that contains the finally calculated parallactic angle. The unit is degrees.
origparangA scalar string that indicates how the parallactic angle was calculated.
declinationA scalar decimal value with the declination. The unit is degrees.
origdeclinationA scalar string that indicates if the declination value was used with an offset.
rightascensionA scalar decimal value with the right ascension. The unit is degrees.
origrightascensionA scalar string that indicates if the right ension value was used with an offset.
localsiderealtimeA scalar decimal value with the local sidereal me. The unit is degrees.
zenithdistanceA scalar decimal value that contains the finally extracted or calculated zenith distance. The unit is degrees.
origzenithdistanceA scalar string that indicates how the zenith tance was calculated.
hourangleA scalar decimal value that contains the finally extracted or calculated hourangle. The unit is degrees.
orighourangleA scalar string that indicates how the hourangle was calculated.
azhourangleA scalar decimal value that contains the hourangle calculated using the azimuth. The unit is degrees.
latitudeA scalar decimal value that specifies the observatory latitude. The unit is degrees.
origlatitudeA scalar string that indicates if the latitude was extracted from the keywords file or from the header.
obselevationA scalar decimal value that specifies the observatory elevation. The unit is meters.
origobselevationA scalar string that indicates if the observatory levation was extracted from the keywords file or rom the header.
azimuthA scalar decimal value that specifies the azimuth, if it is available in the header. The unit is degrees.
gs_airmassA scalar decimal value that contains the calculated airmass of the guide star, if available.
gs_zenithdistanceA scalar decimal value that contains the lculated zenith distance of the guide star, if ailable. The unit is degrees.
gs_declinationA scalar decimal value that contains the guide star declination, if available. The unit is degrees.
gs_rightascensionA scalar decimal value that contains the guide ar right ascension, if available. The unit is grees.
gs_hourangleA scalar decimal value that contains the guide star hourangle, if available. The unit is degrees.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_odetsec.pro, line 120, last changed at 2016-06-30 by christersandin (revision 4260)

odetsec = p3d_misc_odetsec(detsec, /blocksarecombined, /prescanremains, nextensions=, cumulativedetsep=, /rawdataarecombined, topwid=, logunit=, verbose=, error=, /debug, /help)

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

Input parameters:
detsecA 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.
prescanremainsIf 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.
nextensionsA scalar integer that specifies the number of extensions in the raw data. This keyword is only used when BLOCKSARECOMBINED is unset.
cumulativedetsepAn 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.
rawdataarecombinedWhen this keyword is set, raw data of separate cks are read from separate files, which are then bined into one image.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_pathify.pro, line 87, last changed at 2015-10-19 by christersandin (revision 3628)

ret = p3d_misc_pathify(str, /dpath)

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:
strThe input string. Should contain a filename with a path.
Keyword parameters:
dpathIf this keyword is set then the string is checked for the contents of !p3d_data_path, otherwise !p3d_path is used.
Output parameters:
retThis 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'.

routines/p3d_misc_profunction.pro, line 100, last changed at 2015-10-19 by christersandin (revision 3628)

fun = p3d_misc_profunction(x, p, proffun=, /nobg, topwid=, logunit=, verbose=, error=)

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

Input parameters:
xA one-dimensional array with the abscissae of Y.
pA one-dimensional array with the parameter values that are used when calculating the functional return value. Each function uses its own parameters.
Keyword parameters:
proffunA scalar string with the name of the function to use when calculating the line profile.
nobgIf this keyword is set then the background is not added.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
Output parameters:
funAn array of the same properties as X with the evaluated function.

routines/p3d_misc_read_deadfibers_file.pro, line 126, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_read_deadfibers_file, dfile, da, sda, tda, tsda, ifunum=, /pdu, /ppdu, /seplow, topwid=, logunit=, verbose=, error=, /debug, /help

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.

ll entries are returned when IFUNUM is unset.

Input parameters:
dfileA 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:
ifunumA scalar integer that identifies the entries to save from the read list.
pduSet this keyword to save entries that contain one of the strings 'dead fiber' or 'unused fiber'.
ppduSet this keyword to save entries that contain one of the strings 'dead fiber', 'unused fiber', or 'possibly unused fiber'.
seplowSet this keyword to return low-transmission spectra in the separate output variables TDA and TSDA.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
daAn integer array with dead fiber entries.
sdaThe string array corresponding to DA.
tdaAn integer array with low-transmission entries. This array is only returned when SEPLOW is set.
tsdaThe string array corresponding to TDA.

routines/p3d_misc_read_gapsfile.pro, line 116, last changed at 2017-06-28 by christersandin (revision 4659)

p3d_misc_read_gapsfile, gapfile, detector, gaps, hdr=, kwrdlist=, ifunum=, startpx=, topwid=, logunit=, verbose=, error=, /debug, /help

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:
gapfileThe name of the instrument-specific tracing gaps file, if it exists. Non-existing files are specified as emptry strings.
detectorA scalar integer that specifies the id of the current detector, as it is setup in the parameter file.
Keyword parameters:
hdrA string array that is used to find the IFU number in the read data file (if any).
kwrdlistA scalar string that specifies the name of a file that contains a list of instrument-specific keyword names.
ifunum
startpxA scalar decimal value that returns the start pixel used when creating data for simulations. The default value is: -1
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_read_params.pro, line 147, last changed at 2015-11-06 by christersandin (revision 3757)

p3d_misc_read_params, parname, parvalue, name, value, must_exist=, uparname=, uparvalue=, found=, type=, xstr=, /upo, /nou, /a0, parsrc=, topwid=, logunit=, verbose=, error=, /debug, /help

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:
parnameList of parameter names. Both upper and lower case are ok.
parvalueList of parameter values, corresponding to PARNAME.
nameThe parameter name for which the value is requested. Both upper and lower case are ok.
Keyword parameters:
must_existIf this keyword is set and a parameter is not, found, then an error is issued.
uparnameA 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.
uparvalueA list of alternative parameter values, corresponding to PARNAME; see UPARNAME.
foundThis 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 ...").

typeIf 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.
xstrIf 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.
upoIf 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.
nouIf this keyword is set then no parameter origin is set (useful with parameters which are not allowed to change value).
a0If set, then the routine returns if PARNAME is undefined.
parsrcUpon returns this scalar-string keyword contains the origin of the keyword.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
valueContains the value of the parameter with the name NAME. If NAME is not found, -1L is returned.

routines/p3d_misc_read_postable.pro, line 236, last changed at 2017-06-06 by christersandin (revision 4602)

p3d_misc_read_postable, postable=, rownum=, id=, xpos=, ypos=, lens_size=, shape=, nvertices=, /all, /science, /sky, /calibration, elemnouse=, elemsky=, elemcalib=, /usesky, sifunum=, topwid=, logunit=, verbose=, error=, /debug, /help

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

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

    0

    Square-shaped elements.

    1

    Circular elements.

    2

    Hexagon-shaped elements; with vertice 1 at angle = 0.

    3

    Hexagon-shaped elements; with vertice 1 at angle = 30.

    + 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.

    SHAPE = 0

    The scale value has no meaning.

    SHAPE = 1

    The fiber diameter is scale*lens_size.

    SHAPE = 2, 3

    The scale is the separation between opposite sides of the hexagons, i.e. two times the apothem.

    + XISW2E [0], 1

    0

    Column 1, out of 2, in the data gives the S->N positions.

    1

    Column 1, out of 2, in the data gives the W->E positions.

    + XFAC -1, [1]

    -1

    The first column positions will be multiplied with -1 to make the coordinates go from West to East (not from East to West). This multiplication takes place -before- the x and y columns are swapped (iff XISW2E == 0).

    1

    The first column positions already give coordinates as West to East.

    + YFAC -1, [1]

    -1

    The first column positions will be multiplied with – 1 to make the coordinates go from South to North (not from North to South). This multiplication takes place -before- the x and the y columns are swapped (iff XISW2E == 0).

    1

    The first column positions already give coordinates as South to North.

  • USESKY 0, [1]

    0

    The instrument is not used to observe the sky.

    1

    The instrument is used to observe the sky.

  • 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.

Keyword parameters:
postablePosition-table filename (containing the full path).
rownumAn array of element row numbers [output].
idAn array of element id numbers [output].
xposAn array of element x positions [output].
yposAn array of element y positions [output].
lens_sizeAn array of element lens sizes [output].
shapeAn integer specifying the shape of the spatial elements; 0-3 [output]. The default value is: 0
nverticesAn integer specifying the number of vertices of circularly shaped elements (SHAPE == 1 || 2 || 3). The default value is: 15
allIf this keyword is set all entries are read, and are returned as they are. This is a useful mode when combining position tables automatically.
scienceRead science elements.
skyRead sky elements.
calibrationRead calibration elements.
elemnouseElements > than this value are deleted from the table. The default value is: 1000000L
elemskyElements > than this value are considered sky elements. Note! ELEMSKY < ELEMCALIB ! The default value is: 800000L
elemcalibElements > than this value are considered calibration elements. Note! ELEMCALIB < ELEMNOUSE ! The default value is: 900000L
useskyThis keyword specifies if the instrument (setup) is used on the sky or not. The default value is: 1
sifunumA 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.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_retrieve_ifunumber.pro, line 121, last changed at 2017-06-06 by christersandin (revision 4602)

p3d_misc_retrieve_ifunumber, kwrdlist, filename, ifunumset, ifunum, sifunum, topwid=, logunit=, verbose=, error=, /debug, /help

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:
kwrdlistThe 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:
filenameA 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:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
ifunumsetReturns the scalar integer 1 if IFUNUM was set.

routines/p3d_misc_retrieve_lprofs.pro, line 112, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_retrieve_lprofs, tracefile, lprofs, proffun, method=, opath=, nthreads=, topwid=, logunit=, verbose=, error=, /debug, /help

Routine description pending.

Input parameters:
tracefileA 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:
methodA scalar string specifying the spectrum extraction method.
opathA scalar string that, if it is specified, specifies an alternative path where the file is searched for.
nthreadsA scalar integer that is used when setting the number of threads that are used when compressing rewritten fits files using the command pigz.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
lprofsA three-dimensional array of line profile fitting parameters.
proffunContains a scalar string with the name of the function used to calculate the line profile parameters of LPROFS.

routines/p3d_misc_rss2cube.pro, line 151, last changed at 2016-07-15 by christersandin (revision 4353)

p3d_misc_rss2cube, rssdata, cube, nwe, nsn, usex, angle=, daxis=, badarr=, posfile=, posdata=, sifunum=, /posreverse, /crebuild, /noC, nthreads=, title=, topwid=, logunit=, verbose=, error=, /debug, cdebug=, /help

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

Input parameters:
rssdataThe 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:
angleA 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
daxisDefines the dimension of the dispersion direction in the spectrum image; must be either 1 or 2. The default value is: 1
badarrIf 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).
posfileA scalar string with the fiber-position table filename corresponding to the RSSDATA variable.
posdataThis 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.
sifunumThis keyword is used with p3d_misc_read_postable.pro.
posreverseSet this keyword to reverse the fiber-position arrays.
crebuild
noC
nthreadsThe number of threads to use in the conversion. The default value is: 1
titleA scalar string that is written to the log file, when it is set.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
cdebugA keyword as DEBUG used with the called C routines; valid values are 0-6 where a higher number results in more output to STDERR.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
cubeA 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.
nweA scalar integer specifying how many elements there are on the cube West->East axis.
nsnA scalar integer specifying how many elements there are on the cube South->North axis.
usexA two-dimensional byte-type array with [nsn, nww] elements. The elements indicate if the particular element contains a spectrum [1b] or not [0b].

routines/p3d_misc_sauron_colormap.pro, line 81, last changed at 2015-11-06 by christersandin (revision 3756)

p3d_misc_sauron_colormap, ncolors=, bottom=, /invert

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:
ncolorsA scalar integer specifying the number of colors to use. The default value is: !d.table_size
bottomA 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
invertSet this keyword to invert the color table.
Side effects:

Modifies the colortable.

routines/p3d_misc_smooth_1d.pro, line 101, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_smooth_1d, image, xbox, out, topwid=, logunit=, verbose=, error=, /debug, /help

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:
imageA one-dimensional array of data to smooth.
xboxThe half-width of the smoothing box for the filter.
Keyword parameters:
medianUses a median instead of the default average.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
outThe smoothed two-dimensional array.

routines/p3d_misc_spaxelscale.pro, line 114, last changed at 2017-06-06 by christersandin (revision 4602)

ret = p3d_misc_spaxelscale, kwrdlist, hdr, zhdr, orig=, /no_default, topwid=, logunit=, verbose=, error=, /debug, /help

Retrieves information on the spatial-element scale size.

Keyword parameters:
origIs set to a string indicating how the value is set.
no_defaultSet this keyword to avoide setting the default value of 1.0 arcsec/px.
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
retA scalar floating-point value with the spaxel scale. The default value, if it cannot be determined, is 1.0 arcsec/px.

routines/p3d_misc_sv_widget_geometry.pro, line 106, last changed at 2016-04-29 by christersandin (revision 4145)

p3d_misc_sv_widget_geometry, state, error=, /debug, /help

This routine calculates all widget sizes according to the defined size of the spectrum viewer; this routine is used when the tool is resized.

Input parameters:
stateThe state structure of p3d_sv.

routines/p3d_misc_wcs_setup.pro, line 68, last changed at 2016-06-24 by christersandin (revision 4236)

p3d_misc_wcs_setup, hdr, zhdr, ...

Sets up the World Coordinate System information used by p3d.

The following keywords need to be updated each time the spatial map changes: CRPIX1, CRPIX2, CD1_1, CD2_2. The WCS also needs to be rotated according to the angle of the data and the viewed orientation.

Input parameters:
hdrThe FITS header.
zhdrA secondary FITS header.

routines/p3d_misc_write_fitsfiles.pro, line 412, last changed at 2017-06-06 by christersandin (revision 4602)

p3d_misc_write_fitsfiles, data, hdr, ofilename, ofilenamee, /wwave, /fluxsens, /fluxcal, /comb, rawstr=, /bsw, ddata=, olprofs=, ocrmask=, obpmask=, osatmask=, normflat=, scattlight=, transmission=, ocorr=, sfifcald=, sfifcale=, ifile=, itype=, fmbias=, ftrace=, fdispm=, fflatf=, oflprofs=, oftrans=, ioftrans=, ofcrmask=, ofbpmask=, ofsatmask=, ofnormflat=, ofscattlight=, ofcombcorr=, iofcombcorr=, ofiscald=, ofiscale=, sensfunction=, logstr=, /biaspx, /biasox, /biaspy, /biasoy, biasconstant=, rightascension=, declination=, sscale=, pa=, comments=, oprof=, satlimit=, /keeparrangement, ncorr=, ndetectors=, crval=, cdelt=, crpix=, /wavlog, lolim=, hilim=, smspec=, /nf2f, pcutlow=, pcuthigh=, sfinpf=, /sflinextrpol, sfcalfile=, /nohdu, /allinone, /copyrest, /compress, daxis=, nthreads=, rnamex=, topwid=, logunit=, error=, /debug, /help

This routine writes all output data fits files, either to separate files or to consecutive extensions.

Input parameters:
dataA two- or three-dimensional array of floating point type. This is the main data set that will be saved here.
hdrA string array that contains a pre-defined header that belongs to DATA. This array will be modified here, before it is saved, through the addition of new p3d-related keywords.
ofilenameA scalar string with the name of the main output file. This string must contain the full path.
ofilenameeA scalar string with the name of the error output file. This string must contain the full path. Note! The error output file is only written if DDATA is set.
Keyword parameters:
wwaveWhen this keyword is set the wavelength-related keywords CRVAL, CDELT, CRPIX, CTYPE, and CUNIT are added to the header. When this keyword is set it is necessary to also set DAXIS.
fluxsensWhen this keyword is set sensitivuty-function related header keywords are written to the output file.
fluxcalWhen this keyword is set flux-calibration related header keywords are written to the output file.
combWhen this keyword is set combination-related header keywords are written to the output file.
rawstrWhen this keyword is set the input file string is modified according to this keyword. The default value is: 'RAW'
bswWhen this keyword is set the written exposure time is halfed. IMPROVE!!
ddataA floating-point type array of the same dimensions as DATA. This keyword must contain the error of DATA. If this keyword is present the error data is written to the ERROR extension or to a separate file with the name OFILENAMEE.
olprofsA three-dimensional floating-point type array, where the first two dimensions have the same shape as DATA. This keyword contains fitted line-profile parameters that are used in subsequent optimal extraction. If this keyword is present the contained line-profile data cube is written either to the PROF extension or to a separate file with the name OFLPROFS.
crmaskA two-dimensional byte-type array, which must contain a cosmic-ray mask. If this keyword is present the contained mask is written either to the MASK extension or to a separate file with the name OFCRMASK.
obpmaskA two-dimensional byte-type array, which must contain an extracted bad-pixels mask. Pixels could have been masked either through the use of a dedicated bad-pixels mask or a cosmic-ray mask. If this keyword is present the contained mask is written either to the MASK extension or to a separate file with the name OFBPMASK.
osatmaskA two-dimensional byte-type array, which must contain an extracted saturated-pixels mask. Pixels of integrated spectra are marked as saturated if any pixel value across the wavelength- and spectrum-specific aperture is higher than SATLIMIT. If this keyword is present the contained mask is written either to the SATMASK extension or to a separate file with the name OFSATMASK.
normflatA two-dimensional floating-point type array, which must contain an extracted and normalized flat-field image. If this keyword is present the contained image is written either to the NORMFLAT extension or to a separate file with the name OFNORMFLAT.
scattlightA two-dimensional floating-point type array, which must contain an extracted and normalized flat-field image. If this keyword is present the contained image is written either to the SCATTLIGHT extension or to a separate file with the name OFSCATTLIGHT.
transmissionA one-dimensional floating-point type array, which must contain a fiber-to-fiber transmission array. If this keyword is present the contained array data are written to the TRANSMSN binary-table extension, or to a separate fits file with the name OFTRANS. If this keyword is set it is necessary to also specify PCUTLOW and PCUTHIGH.
ocorrA one-dimensional floating-point type array, which must contain a re-normalization correction-factor array. If this keyword is present the contained array data are written to the CORRFACT binary-table extension, or to a separate fits file with the name OFCOMBCORR. If this keyword is set it is also mandatory to specify NCORR and NDETECTORS.
sficaldA one- or two-dimensional floating-point type array, which must contain a flux calibrated input spectrum; and optionally a flux calibrated sky spectrum. This keyword is only used if FLUXSENS is set.
sficaleA one- or two-dimensional floating-point type array, which must contain a flux calibrated input spectrum error; and optionally a flux calibrated sky spectrum error. This keyword is only used if FLUXSENS is set.
ifileA scalar string that specifies the input raw-data filename. This string is, if present, written to the header keyword IMRAW.
itypeA scalar string that specifies the p3d fits-file image type. This string is written to the header keyword IMTYPE.
fmbiasA scalar string that specifies the used master-bias image file, with the full path.
ftraceA scalar string that specifies the used trace-mask image file, with the full path.
fdispmA scalar string that specifies the used dispersion-mask image file, with the full path.
fflatfA scalar string that specifies the used flat-field image file, with the full path. If this parameter is set it is necessary to set NF2F.
oflprofsA scalar string with the name of an output file that will contain a calculated line-profiles image. This keyword is only used if ALLINONE is unset and OLPROFS is set.
oftransA scalar string with the name of an output file that will contain the calculated fiber-to-fiber transmission array. This keyword is only used if ALLINONE is unset and TRANSMISSION is set.
ioftransA scalar string with the name of an output file with the calculated fiber-to-fiber transmission array that is to be used. This keyword is only used if ALLINONE is unset and TRANSMISSION is set. Additionally, if this keyword is unset OFTRANS is used instead.
ofcrmaskA scalar string with the name of an output file that will contain a calculated cosmic-ray mask image. This keyword is only used if ALLINONE is unset and OCRMASK is set.
ofbpmaskA scalar string with the name of an output file that will contain a calculated bad-pixels mask image. This keyword is only used if ALLINONE is unset and OBPMASK is set.
ofsatmaskA scalar string with the name of an output file that will contain a calculated saturated-pixels mask image. This keyword is only used if ALLINONE is unset and OSATMASK is set.
ofnormflatA scalar string with the name of an output file that will contain a calculated normalized flat-field image. This keyword is only used if ALLINONE is unset and NORMFLAT is set.
ofscattlightA scalar string with the name of an output file that will contain a calculated scattered-light image. This keyword is only used if ALLINONE is unset and SCATTLIGHT is set.
ofcombcorrA scalar string with the name of an output file that will contain the calculated correction array. This keyword is only used if ALLINONE is unset and COMB is set.
iofcombcorrA scalar string with the name of an output file with the calculated correction array that is to be used. This keyword is only used if ALLINONE is unset and COMB is set. Additionally, if this keyword is unset OFCOMBCORR is used instead.
ofiscaldA scalar string with the name of the flux-calibrated input data file. This keyword is only used if both FLUXSENS and SFIFCALD are set, but then it is required.
ofiscaleA scalar string with the name of the flux-calibrated input data file. This keyword is only used if ALLINONE is unset and FLUXSENS and SFIFCALE are set, but then it is required.
sensfunctionA scalar string with the sensitivity-function filename. This keyword is only used when FLUXCAL is set, but then it is mandatory.
logstrA scalar string with a file-specific description of the written contents. This keyword is mandatory.
biaspxIf this keyword is set, then the x-axis prescan region (PRESCANX) was used when preparing a bias image. The same array is used with all y-axis columns of data. This keyword is only used if FMBIAS is unset, but then it is mandatory.
biaspyIf this keyword is set, then the y-axis prescan region (PRESCANY) was used when preparing a bias image. The same array is used with all x-axis rows of data. This keyword is only used if FMBIAS is unset, but then it is mandatory.
biasoxIf this keyword is set, then the x-axis overscan region (OVERSCANX) was used when preparing a bias image. The same array is used with all y-axis columns of data. This keyword is only used if FMBIAS is unset, but then it is mandatory.
biasoyIf this keyword is set, then the y-axis overscan region (OVERSCANY) was used when preparing a bias image. The same array is used with all y-axis rows of data. This keyword is only used if FMBIAS is unset, but then it is mandatory.
biasconstantThis keyword can be used in two ways:

  • Set this keyword to use a constant value as a bias value; otherwise an array is used. All the prescan and overscan regions that are specified using the keywords BIASPX, BIASPY, BIASOX, and BIASOY can be used when this keyword is set; otherwise only one of them.

  • If this keyword is set to an array of floating-point type values, then these values are used to create a bias. Note that the number of elements must be the same as the number of blocks or extensions.

This keyword is only used if FMBIAS is unset, but then it is mandatory.
rightascensionA scalar floating-point type value that specifies the center RA coordinate of the IFU. This keyword is only used if DATA is a cube, but then it is mandatory. The unit is degrees.
declinationA scalar floating-point type value that specifies the center DEC coordinate of the IFU. This keyword is only used if DATA is a cube, but then it is mandatory. The unit is degrees.
sscaleA scalar floating-point type value that specifies the size of each spatial element. This keyword is only used if DATA is a cube, but then it is mandatory. The unit is arcsec.
paA scalar floating-point type value that specifies the IFU position angle. This keyword is only used if DATA is a cube, but then it is mandatory. The unit is degrees.
commentsA string array that must contain comments, which are written to the data header.
oprofA scalar string that specifies the function type that was used when fitting the line profiles that are provided in the keyword OLPROFS. This keyword is only used when OLPROFS is set, but then it is mandatory.
satlimitA scalar integer that specifies the saturated pixels limit. This keyword is only used when OSATMASK is set, but then it is mandatory.
keeparrangementThis keyword affects how the POSTAB keyword is defined when COMB is set.
ncorrThis scalar integer defines the number of elements in the correcion-factor array of each detector when OCORR is set.
ndetectorsThis scalar integer defines the number of detectors when OCORR is set.
crvalA scalar floating-point value, which is only used when WWAVE or FLUXSENS is set. The default value is 0.0.
cdeltA scalar floating-point value, which is only used when WWAVE or FLUXSENS is set. The default value is 1.0.
crpixA scalar integer value, which is only used when FLUXSENS is set.
wavlogA scalar integer value, which is only used when FLUXSENS is set.
lolimA scalar integer which is only used when WWAVE is set and DAXIS==3, but then it is mandatory.
hilimA scalar integer which is only used when WWAVE is set and DAXIS==3, but then it is mandatory.
smspecA floating-point scalar that specifies the mean value of a normalized flat-field image. This keyword is only used if FFLATF is set, but then it is mandatory.
nf2fA scalar integer that specifies if the data were normalized with a separate transmission array. If this keyword is set it is mandatory to also specify PCUTLOW and PCUTHIGH.
pcutlowA floating-point scalar, which is mandatory when either TRANSMISSION or NF2F is set.
pcuthighA floating-point scalar, which is mandatory when either TRANSMISSION or NF2F is set.
sfinpfA scalar string or integer, which indicates the function type that was used when creating the sensitivity function. This keyword is only used when FLUXSENS is set, but then it is mandatory.
sflinextrpolA scalar integer that indicates if data were linearly extrapolated or not. This keyword is only used when FLUXSENS is set, but then it is mandatory.
sfcalfileA scalar string that indicates the name of the calibration standard-star file. This keyword is only used when FLUXSENS is set, but then it is mandatory.
nohduSet this keyword to avoid writing HDU-specific header keywords.
allinoneUnset this keyword to write the output data to separate files, instead of writing the output to the same file. The default value is: 0
copyrestWhen this keyword is set to the input data filename and ALLINONE is set the bad-pixels mask image and the saturated-pixels mask image are added to the output file. These images are searched for in the input spectrum-file extensions MASK and SATMASK, or in the separate files IMONC and IMSMK.
compressSet this keyword to compress all output files using gzip; the file suffix '.gz' is then appended to all output filenames.
daxisA scalar integer that is set to 1, 2, or 3. This keyword is only required when WWAVE is set.
nthreadsA scalar integer that specifies how many threads are used when the output file is compressed using the tool "pigz". The default value is: 1
rnamexA scalar string that must be set to the name of the calling routine.
stawidIf set, then various messages are written to the p3d GUI status line (this must be the widget id of that label widget).
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet 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.

fontSet this scalar string to the name of the font you want to use with all the widget components of this tool.
errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
outThe resulting image of the extraction.

page last updated on: Wednesday June 28, 2017 11:06:27; retrieved on: Tuesday September 26, 2017 03:37:03