This is the p3d routine that handles cosmic-ray rejection.

This routine is based on the cosmic-ray hit rejection algorithms PyCosmic (Husemann, Kamann, Sandin, et al. 2012), and L.A. Cosmic (van Dokkum 2001). PyCosmic was developed to work well with fiber-fed IFS images, and L.A. Cosmic to detect cosmic-ray hits in images in general. The code provided here contains both the PyCosmic algorithm and a modified and extended version of the IDL-version of L.A. Cosmic (la_cosmic.pro, by J. Bloom), and was adjusted for p3d with the permission of both P. van Dokkum (Yale) and J. Bloom (UC Berkeley). The full algorithm as implemented by Bloom is implemented, all equations refer to van Dokkum (2001).

An alternative approach to remove cosmic-ray hits, which is not implemented in p3d, is given by Pych (DCR; 2004).

This routine is most easily used through the wrapper p3d_cr.pro.

More details on the functionality

This routine takes a two-dimensional image as input. Data must already have been debiased. The PyCosmic (L.A. Cosmic) algorithm is used when the keyword IMAGEMETHOD is unset (is set); IMAGEMETHOD is unset by default. Both algorithms require two criteria to be fulfilled to mask a pixel as a cosmic-ray hit.

The first criterion demands that a sampling-flux subtracted image containing deviations from Poisson noise must be greater than a limiting value sigma_clip (S'>SIGCLIP). In the formulation of van Dokkum (2001) the sampling flux is removed using a two-dimensional five-pixel median kernel. Since IFS spectra always extend on the dispersion axis, p3d allows the additional option to remove one-dimensional spectrum-sampling flux on the dispersion axis only, before the two-dimensional subtraction takes place. See the keyword DISPMEDIAN to use this option. Our studies have shown that the best results with IFS data are achieved using the new second criterion (IMAGEMETHOD=0; the default) together with a one-dimensional sampling flux removal (DISPMEDIAN=5 is the default). The second criterion depends on the algorithm:

In a final step cosmic-ray hit pixels are "grown" to the surrounding pixels to check if they are also affected. The growing takes place by convolving the cosmic-ray mask with a growth kernel. The kernel is a square matrix with 2*GROWRADIUS+1 elements on each side; the default value is GROWRADIUS=1 (GROWRADIUS=0 and 2 are also possible). Pixels in the frame around each cosmic-ray masked pixel are also masked if S'>SIGCLIP*SIGFRAC.

This routine works with both single-block and multi-block CCDs, where the PMAS 4kx4k CCD is an example of the latter type. In the multi-block case different blocks have a different readout noise. For such instruments the readout noise is specified as an array of //n// blocks, along with a 4x//n// array that specifies where each block belongs in the image (DETSEC). Any prescan and overscan regions are, in this case, excluded from the dataset before removing cosmic-ray hits (they are replaced in the output).

Comments

J.Bloom (la_cosmic.pro): "If you find that after ~4 iterations that the routine is still finding cosmic rays chances are that you are digging into the noise and or objects. Try setting the sigclip number a bit higher."

References

van Dokkum, P.G. 2001, PASP, 113, 1420, "Cosmic-Ray Rejection by Laplacian Edge Detection"

Pych, W. 2004, PASP, 116, 148, "A Fast Algorithm for Cosmic-Ray Removal from Single Images"

Husemann, B., Kamann, S., Sandin, C., Sánchez, S., Mast, D. and Garcia-Benito, R. 2012, A&A, 545, A137, "PyCosmic: a robust method to detect cosmics in CALIFA and other fiber-fed integral-field spectroscopy datasets"

Links

The PyCosmic code can be found here: http://pycosmic.sf.net

The original L.A. Cosmic code(s) can be found here: http://www.astro.yale.edu/dokkum/lacosmic/

The DCR code of Pych (2004) can be downloaded here: http://users.camk.edu.pl/pych/DCR/index.html

Input parameters:

	image		A two-dimensional array of floating-point type.
	gain		A scalar floating-point value that specifies the gain. The unit of GAIN must be electrons per analog-to-digital unit [e-/ADU].
	ron		A scalar decimal value (or an array of values) that specifies the readout noise. The unit of RON must be the analog-to-digital unit [ADU]. The default value is: 0.0

Keyword parameters:

	sigclip		A scalar decimal value that specifies the clipping sigma; sigma_clip in van Dokkum (2001). The default value is: 5.0
	objlim		A scalar decimal value that specifies the object limit value; f_lim in van Dokkum (2001). The default value is: 2.0
	ratlim		A scalar decimal value that specifies the ratio limit value; r_lim in Husemann et al. (2012). The default value is: 1.2
	fwhm		A two-element array that specifies the full width t half maximum of the spectra in the image. his value is only used if IMAGEMETHOD is unset. The default value is: 1.0, 1.0
	gausskernelsize		A scalar integer that specifies the size of the Gaussian kernel that is used when convolving the input image with a Gaussian kernel using the PyCosmic algorithm. This value is by default set to 2*q+1, where q is the maximum value of the x and the y pixel where a one-dimensional Gaussian reaches 15% of its maximum value (1.0); this condition makes use of the full-width-at-half-maximum value of FWHM. The maximum value is in any case 19. Be aware that convolution times increase strongly with the size of the Gaussian kernel.
	sigfrac		A scalar decimal value that specifies a scale factor for pixels surrounding a cosmic-ray masked pixel. This parameter is only used if GROWRADIUS is non-zero. The default value is: 0.5
	growradius		Set this keyword to grow all cosmic-ray hit pixels by a frame that is this many pixels wide. This is done to check if the surrounding pixels are affected by cosmic-ray hits as well. The default value is 1, the values 0 and 2 are also accepted. Surrounding pixels are checked if they are cosmic-ray affected using the first criterion S' > SIGFRAC * SIGCLIP. The default value is: 1
	maxiter		A scalar integer value that specifies the maximum number of iterations that are used when identifying cosmic-ray hits in each image. The default value is: 4
	imagemethod		Set this keyword to use the L.A. Cosmic algorithm instead of the (default) PyCosmic algorithm.
	imageclean		Set this keyword to use the original two-dimensional [5*5] median filter when replacing the flux in masked pixels with that of the surrounding pixels. Otherwise an [11 pixel] one-dimensional median filter is used. The masked pixels are replaced with NAN in both cases; in the latter case fewer pixels are available to calculate a replacement value, which is why there are likely more NANs in this case. The default value is: 1
	dispmedian		Set this keyword to a positive integer > 1 to subtract one-dimensional sampling flux that is only calculated along the dispersion axis. The value defines the width of the median window. The default value is: 5
	writeall		Set this keyword to write all intermediate images in addition to the cleaned image and the cosmic-ray mask.
	filenames		A five-element string array. This keyword must be set if WRITEALL is set.
	foffset		A five-element integer array that specifies the position in FILENAMES where the iteration-dependent string is inserted for each element in FILENAMES. No string insertion is done if FOFFSET is not provided.
	hdr		A string array that contains an image header that is used when WRITEALL is set.
	compress		If this keyword is set then the output is compressed using gzip, and the file ending '.gz' is appended to all output filenames. The default value is: 0
	nblocks		A scalar integer that specifies the number of used CCD blocks. The default value is: 1
	blocksarecombined		If this keyword is set the DETSEC array is eated differently.
	nextensions		A scalar integer indicating the number of data extensions in the input raw data file. The default value is: 0
	cumulativedetsep		This keyword is passed on to p3d_misc_odetsec.
	rawdataarecombined		When this keyword is set, raw data of e blocks are read from separate files, which n combined into one image. Otherwise, they d from separate extensions. The default value is: 1
	opath		If this scalar string is set then the corresponding value is used as output directory, otherwise the current directory is used.
	allinone		Unset this keyword to write the output data to separate files, instead of writing the images to consecutive extensions. The default value is: 1
	nthreads		A scalar integer that specifies how many threads to use in the parallelized line-profile calculations. The calculation speed does not scale linearly with the number of threads. The default value is: 1
	cshlib		A scalar string with the full name of a shared C library file that contains the parallelized C version of the cosmic-ray cleaning routine.
	noc		Set this keyword to force the use of the slower IDL-based routine instead of the faster C-based routine. Note! This keyword is by default set until the C routine is debugged.
	detsec		A four-element by //n//-element integer array that specifies the detector region to use on the CCD. DETSEC must be present if the number of blocks is greater than one.
	daxis		A scalar integer that specifies the dispersion dimension in (all) the input image(s). The default value is: 1
	topwid		If set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
	logunit		Messages are saved to the file pointed to by this logical file unit, if it is defined.
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all. This is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.
	error		This scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
	debug		No error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
	cdebug		A keyword as DEBUG used with the called C routines.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

cimage

A two-dimensional array of decimal type that contains the cosmic-ray cleaned image. The size of CIMAGE is the same as that of IMAGE.

Astronomical spectrum datacube continuum subtraction filter.

The filter works as follows.

A datacube with astronomical spectra is assumed to be provided in a file that is saved in the FITS format. Two out of the three axes are expected to be spatial and a third is spectral.

The user specifies a quadratic region where there is little disturbance and few features; this is done using the first two arguments (//APER_X// and //APER_Y// [pixel] coordinates) and the half-side (//APER_S//, also a pixel value). The flux in the region is summed up to create a reference spectrum using all layers (pixels on the wavelength axis) in the datacube.

A new datacube is constructed layer by layer, where a continuum image is created for each layer individually based on two regions offset (OFFSET) towards lower and higher pixels of the current layer. The total width of the continuum regions is set using the fourth argument (CWIDTH, the width is specified in Angstrom). The continuum image is at first normalized (corrected) with the corresponding continuum regions of the reference spectrum. Thereafter, the normalized continuum image is subtracted from the current layer image.

Creating the continuum image and continuum reference spectrum for each layer, the two continuum regions are offset towards either lower or higher pixels until no telluric line falls within the respective region. Telluric line wavelengths are read from a plain-text file (TELLURICLINE) that provides a wavelength value per line. The full width of any individual telluric line region can be set (BWIDTH).

The filtered image is written to a file, adding a set of header keywords that indicate what argument values were used ("d11_x", "d11_y", "d11_apr", and "d11_cwid") for (x, y, apr, and cwidth). The output filename can be set explicitly (OFILENAME), but otherwise the input filename is used with the added suffix "_d11".

Input parameters:

	filename		A scalar string with the name of the datacube file. The file needs to be stored using the FITS format. An attempt is made at locating the dispersion axis in the datacube using the CTYPEx header keywords (x is an integer in the range 1-3), which needs to be set to either AWAV or WAVE.
	aper_x		A scalar decimal value with the x-coordinate of the region center that is used to create a reference spectrum. The value is specified in pixel units. There is no default as this value has to be chosen by identifying a region in the datacube where there is little change.
	aper_y		A scalar decimal value with the y-coordinate of the region center that is used to create a reference spectrum. The value is specified in pixel units. There is no default as this value has to be chosen by identifying a region in the datacube where there is little change.
	aper_s		A scalar decimal value. The reference spectrum region half-width. The value is specified in pixel units. There is no default as this value has to be chosen by identifying a region in the datacube where there is little change.
	cwidth		A scalar decimal value. The full (band)width of the continuum region that includes both the region towards lower and higher pixels away from the current layer on the dispersion axis. The value is specified in wavelength units (Angstrom). There is no default value as this value has to be chosen depending on the data.

Keyword parameters:

	offset		A scalar integer value that specifies the initial offset towards lower and higher pixels when defining the continuum image. The unit is pixels, The default value is 5 pixels. The default value is: 5
	emissionlines		An optional array with wavelengths of emission lines that should be excluded in the calculation of the continuum regions. The wavelength unit is Angstrom (Å).
	dwl		A scalar floating-point type value that defines a maximum allowed deviation from the provided center wavelengths of emission lines. The unit is Ångström [Å]. This keyword is only used when the keyword EMISSIONLINES is set. The default value is: 1.0
	z		A scalar decimal value or a two-dimensional array of decimal values of the same size as the spatial extent of the data available in the data cube of FILENAME. A scalar value specifies a single redshift used with all spatial elements while an array provides a redshift value per spatial element. This keyword is only used when the keyword EMISSIONLINES is set.
	fit_intensity_limit		A scalar decimal value that defines a lower limit on the fitted emission line intensity for the fit to be considered OK. The default value is: 0.0
	fit_flux_continuum_fraction		A scalar decimal value that defines a lower limit on the ratio between the emission line flux at the line center and the continuum for the fit to be considered OK. The default value is: 0.0
	bin		A scalar integer that is used to bin the input data before fitting emission lines. For example, if bin is set to 10, the spectra of ten spatial elements are summed together on both spatial axes to form a binned spectrum out of 100 unbinned spectra. In the case that the number of spatial elements on either axis is not evenly divisible with the bin number, an additional bin is added that contains as many spatial elements, counting from the back. The default value is: 1
	telluriclines		An optional array with wavelengths of telluric lines that should be excluded in the calculation of the continuum regions. The wavelength unit is Angstrom (Å).
	bwidth		A scalar decimal value. Specifies the bandwidth of bandpasses to ignore; centered on telluric lines. The value is specified in wavelength units (Angstrom). The default value is 3.0 Å. The default value is: 3.0
	commentslines		A scalar string that specifies a character that identifies comment lines in the emission and telluric line-list files. The default value is ";". The default value is: ';'
	ofilename		A scalar string. Specifies the name of the resulting filtered file. When this keyword is unset, the input filename is used with the added suffix "_d11".
	overwrite		A scalar integer that specifies if any existing output file is overwritten (1) or not (0). The default value is: 0
	logunit		Messages are saved to the file pointed to by this logical file unit if it is defined.
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all; this is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines; this may be a useful mode when debugging the code.
	error		This scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
	debug		No error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
	help		Set this keyword to show this routine documentation and then exit.

This routine prepares, and optionally normalizes, an extracted flat-field image. All elements operated upon are ensured to be > 0.

If NORMALIZE is set, the image is normalized. If the original p3d treatment is used (/NORIG), each spectrum is at first divided with the mean spectrum. Otherwise, the spectra are at first smoothed (SMOWID) and replaced with a polynomial fit (DEG), before they are normalized fiber-to-fiber (NF2F) and spectrum-to-spectrum (NDISP).

Note: The fiber-to-fiber normalization is done using the current data set by default. If TRANSMISSION is set, that array is used instead.

If NORMALIZE is unset, the image is, nevertheless, normalized to calculate a fiber-to-fiber transmission array, which is returned in the keyword TRANSMISSION. The main data set is, however, kept un-normalized.

Input parameters:

in

A two-dimensional array of decimal type.

Keyword parameters:

	din		An array of the same type and dimensions as IN; containing the error of IN.
	spec		A one-dimensional array that upon exit holds the mean spectrum of IN.
	normalize		If this keyword is set, the data are normalized. If it is unset, all elements, which are <= 0, are masked before the routine returns an un-normalized data set. However, before returning a transmission array is calculated for a normalized data set. The default value is: 0
	smowid		A scalar integer specifying the width of a smoothing box, which is used across the data in the dispersion direction. The default value is: 0
	deg		A scalar integer specifying the order of a polynomial that is used to fit and then replace the normalized data. The default value is: 0
	norig		If this keyword is set, the normalization is done using the original p3d approach – which was to normalize the data with the average spectrum, before smoothing the data and replacing each spectrum with a polynomial fit. Note! If NORIG is set, NF2F and NDISP are unset, and TRANSMISSION will not be used either. The default value is: 0
	nf2f		If this keyword is set, each spectrum is divided with the normalized mean of each spectrum. The mean is calculated avoiding NPLOW % of the pixel range in the lower range, and avoiding NPHIGH % of the pixel range in the higher range. The normalized mean is then calculated by dividing with the mean for all spectra. Note! If TRANSMISSION is set, that array is used instead to normalize each spectrum. The default value is: 0
	ndisp		If this keyword is set, each spectrum is divided with the mean spectrum. The default value is: 1
	nplow		A scalar decimal value that specifies the extent of the total number of pixels on the dispersion axis that is removed from each spectrum at the lower (blue) end before calculating the fiber-to-fiber transmission array. This value is specified in per cent. The default value is: 5.0
	nphigh		A scalar decimal value that specifies the extent of the total number of pixels on the dispersion axis that is removed from each spectrum at the upper (red) end before calculating the fiber-to-fiber transmission array. This value is specified in per cent. The default value is: 5.0
	transmission		A one-dimensional array of decimal type with as many elements as there are spectra in IN. If this array is specified, it is used to normalize the spectra fiber-to-fiber. If it is not specified, the spectra of IN are used for this purpose, but iff NF2F is set. If NORMALIZE is unset, TRANSMISSION will contain the fiber-to-fiber array upon exit of this routine.
	smspec		A scalar decimal that contains the summed value of the mean spectrum that is used when NDISP == 1. The default value is: 1.0
	deadfibersmask		An integer array with as many elements as there are spectra in the IN parameter. The elements must each have the value 0 (the fiber is dead, should not be used, is a low-transmission fiber) or 1 (the fiber can be used). This mask is used when calculating the mean spectrum (/NDISP).
	daxis		Defines the dispersion direction dimension of IMAGE. The default, 1, is in the x-direction. The default value is: 1
	topwid		If set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
	logunit		Messages are saved to the file pointed to by this logical file unit, if it is defined.
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all. This is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.
	error		This scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
	debug		No error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

out

A two-dimensional array of decimal type. In comparison to IN, the data have been masked from values < 0.0 and, optionally, normalized and smoothed.

This routines calculates a sensitivity function based on observed data and calibration data.

Please note, that a full documentation of this routine is provided in the routine p3d_fluxsens.

NOTE! Needs adaptation when using a logarithmic wavelength axis.

Input parameters:

	ssobs		A scalar structure that must contain the wavelength array and the data of an observed standard-star spectrum.
	sscal		A scalar structure that must contain the wavelength array and the data of a calibration standard-star spectrum.

Keyword parameters:

	extinction		An optional scalar structure that should contain the wavelength array and the corresponding extinction array.
	airmass		An optional scalar decimal value with the value of the airmass of the observations. It is mandatory to specify this property when EXTINCTION is set, otherwise it is not used.
	exptime		A scalar decimal value that must contain the exposure time of the observed spectrum; the unit is seconds.
	inpfunction		A scalar string that specifies which kind of terpolation to use. The available options are: 'spline' see the IDL routine SPLINE. 'cspline' see the astro-lib routine CSPLINE. 'ispline' see the IDL routine INTERPOL. 'iquadratic' see the IDL routine INTERPOL. 'ilsquadratic' see the IDL routine INTERPOL. 'chebyshev_x' a Chebyshev polynomial of order x; 0 <= x <= 20. 'legendre_x' a Legendre polynomial of order x; 0 <= x <= 20. 'x' a linear polynomial of order x; 0 <= x <= 20. ese options are described more thoroughly in d_fluxsens. The default value is: '6'
	splinetension		A scalar decimal value that determines the ion in the spline fit (when UNCTION == 'spline'); 0 < SPLINETENSION <= 100. all value results in a cubic spline, and a e value in a polynomial fit. The default value .0. The default value is: 1.0
	linearextrapolation		Set this keyword to extrapolate the ity function as a linear function using the st or the two highest gridpoints. The default value is: 1
	sensitivityfunction		Upon completion this keyword contains an array the sensitivity function.
	ssobs_calibrated		Upon completion this keyword contains a one- or wo-dimensional array with the calibrated tandard-star spectrum. Optionally, the second row ontains the calibrated sky spectrum.
	ssobs_dcalibrated		Upon completion this keyword contains a one- or o-dimensional array with the error of the librated standard-star spectrum. Optionally, the cond row contains the error of the calibrated sky ectrum.
	window		A scalar integer or an 8-element integer array with draw widget window ids.
	interactive		Set this keyword to make an interactive fitting instead of an automatic fitting. The default value is: 0
	psplot		.
	a2		Set this keyword to use the A2 paper format with PostScript and PDF output instead of A4.
	a3		Set this keyword to use the A3 paper format with PostScript and PDF output instead of A4.
	a5		Set this keyword to use the A5 paper format with PostScript and PDF output instead of A4.
	letter		Set this keyword to use the US Letter paper format with PostScript and PDF output instead of A4.
	legal		Set this keyword to use the US Legal paper format with PostScript and PDF output instead of A4.
	tabloid		Set this keyword to use the US Tabloid paper format with PostScript and PDF output instead of A4.
	psfilename		.
	pdf		.
	binpdf		.
	ploti		A structure with all the information about the plot windows in the spectrum viewer.
	plotd		An output structure that contains all plotted calibration-data values. The used values are updated each time the routine is called. The non-used values are plotted with the X symbol in each panel.
	charsize		A scalar decimal value that defines the font size in the plots. The default value is: 1.0
	topwid		If set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
	logunit		Messages are saved to the file pointed to by this logical file unit, if it is defined.
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all. This is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.
	error		This scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
	debug		No error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
	help		Set this keyword to show this routine documentation, and then exit.

This routine sets up the main GUI of p3d. This routine should not be used by itself, instead use the wrapper p3d.pro.

All components of this routine, but the input and output parameters and keywords, are described in full in the routine p3d.pro.

Input parameters:

parfile

A string specifying the filename of an existing file containing instrument-specific parameters, which are used by p3d to perform semi-automatic reductions.

Keyword parameters:

	cwd		This keyword can be set in two ways: If CWD is a scalar string, the string is assumed to be the path where all data are saved. If CWD is used as /CWD (i.e. an integer == 1), the current directory is used to save all output data.
	path		A scalar string that specifies where the raw data is placed. If it is set, the data path is set to PATH (after checking if PATH is a directory). If PATH is unset, the data path is set to !p3d_data_path.
	title		A scalar string that is used in the title of the p3d GUI.
	sfx		A scalar string that specifies the raw data filename suffix to use. The default value is: .fits
	detector		This scalar integer specifies the detector to start with for instruments which have more than one (such as, e.g., VIMOS or SPIRAL).
	userparfile		A scalar string that specifies the name of an optional file with user parameters. This file is used by various routines in the p3d package (please see the separate routines for its use).
	displib		N/A.
	colortable		A scalar string or integer that specifies which color table should be loaded. If COLORTABLE is a string, the string must contain two parts separated by a comma, without any whitespace between. The first part before the comma specifies the color-table number in the file name specified after the comma; the file must be formatted as described in the documentation for MODIFYCT. As an example, COLORTABLE='25,brewer.tbl'. Components in the ColorBrewer color-table file "brewer.tbl" found in the resource directory can be specified explicitly by preceeding the string with "CB"; for example, COLORTABLE='CB25'. If COLORTABLE is an integer, the integer must be given in the range -4, -3, -2, -1, 0, ..., up to the maximum number of available tables in IDL, plus the available tables in the ColorBrewer file (resource/) "brewer.tbl". Select -4, -3, -2, or -1 to load the cubehelix, 2 * Califa, and the Sauron color tables, the other values use the respective color map as defined by LOADCT. These are the permitted values: -4 Loads the cubehelix color table. -3 Loads the Califa project intensity color table, as defined September 2012. -2 Loads the Califa project velocity field color table, as defined September 2012. -1 Loads the Sauron color table (default). 0-74 (IDL version >= 8.3) Loads the corresponding color table with LOADCT. 0-40 (IDL version < 8.3) Loads the corresponding color table with LOADCT. 'CB0'-'CB85' Loads the corresponding ColorBrewer color table; the color tables are defined in the file "resource/brewer.tbl" 75-159 (IDL version >= 8.3) Loads the ColorBrewer color table corresponding to this number after 75 is subtracted; the color tables are defined in the file "resource/brewer.tbl" 41-125 (IDL version < 8.3) Loads the ColorBrewer color table corresponding to this number after 41 is subtracted; the color tables are defined in the file "resource/brewer.tbl" 'x,ctfile' Loads the x:th entry ('x' must be an integer) in the color-table file 'ctfile. The default value is: -1
	invert		Set this keyword to reverse the loaded color table.
	bottom		A scalar integer that specifies the lower index of the color table that is used to scale the colormap (the upper index is the maximum possible; see p3d_misc_colortable).
	cindex		An array of integers specifying which color indices to use for reserved colors. It doesn't make sense to use more than 4 elements in the CINDEX array. The indices should also be set as low as possible in order to allow the remaining indices to be used by the (scaled) COLORTABLE (see p3d_misc_colortable).
	ch_start		This scalar decimal value defines the color when COLORTABLE = -4. The default value is: 0.5
	ch_rots		This scalar decimal value defines the rotation in color when COLORTABLE = -4. The default value is: -1.5
	ch_hue		This scalar decimal value defines the hue intensity scaling when COLORTABLE = -4. The default value is: 1.2
	ch_gamma		This scalar decimal value defines the gamma correction factor when COLORTABLE = -4. The default value is: 1.0
	ds9		When this keyword is set ds9-specific buttons are added to the GUI. These buttons allow an easy launch of the image viewer ds9. This keyword must only be set if the binary ds9 is available in the system path.
	display_name		Set this keyword equal to a string that specifies the name of the X Windows display on which the base should be displayed; this keyword has no effect on Microsoft Windows platforms.
	tracking_events		If this keyword is set, (some) p3d tools, which have a GUI, show a status line with updated information on what various widgets do, and what is going on. The default value is: 1
	logfile		A scalar string that specifies the name of a logfile. If a file already exists, with the name LOGFILE, it is overwritten. Use this keyword to save the output of the various routine of p3d. In order to only print information at the prompt, use VERBOSE instead.
	loglevel		A scalar integer, which determines the amount of information that is recorded in the logfile LOGFILE. LOGLEVEL can be set to 1-3, where a higher number means that more information is written to the logfile.
	mpfit		If this keyword is set, it is assumed that the fitting routine mpfit.pro (see http://purl.com/net/mpfit) exists in the path. This routine is then used in various routines of p3d where curve fitting is required. (MPFIT has more options to control than, e.g., GAUSSFIT.)
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all. This is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.
	font		Set this scalar string to the name of the font to be used with all widget components of this tool. It is advised to use a fixed font, the outcome is otherwise difficult to predict. Set the keyword to 'big' to use the following pre-defined font ed-medium-r-normal--18-120-100-100-c-90-iso8859-1'; this could be useful on a system using a 4k screen (with 3160x2560 pixels). Another option to specify a font is to set the environment variable p3d_font or the p3d IDL system variable !p3d_font. The default font used with the widgets is, for your information, printed to the screen when FONT is unset and the highest verbosity level is used (verbose = 3). On Linux machines, use a shell command such as 'xlsfonts' to list all available fonts.
	error		This scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
	debug		No error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
	help		Set this keyword to show this routine documentation, and then exit.
	restart		This keyword is used by p3d internally if p3d is restarted (with the menu option).

Side effects:

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

Provides a GUI with setup option for the dispersion-mask creation.

Input parameters:

state

The state structure of p3d_tool_gui.

Side effects:

The GUI creates an event when it is closed, which is caught by the p3d main GUI event handler.

Draws spatial-map plots in the draw widgets of the p3d main GUI. sets.

Input parameters:

state

The state structure of p3d_tool_gui.

Handles the events of the p3d main GUI.

Input parameters:

event

The event structure of p3d_tool_gui.

Provides a GUI with setup option for the object extraction.

Input parameters:

	state		The state structure of p3d_tool_gui.
	sexmethod		.

Side effects:

The GUI creates an event when it is closed, which is caught by the p3d main GUI event handler.

Provides a GUI with setup option for the flat-field extraction.

Input parameters:

state

The state structure of p3d_tool_gui.

Side effects:

The GUI creates an event when it is closed, which is caught by the p3d main GUI event handler.

Provides a GUI with setup option for the flux calibration.

Input parameters:

state

The state structure of p3d_tool_gui.

Side effects:

The GUI creates an event when it is closed, which is caught by the p3d main GUI event handler.

Provides a GUI to store the loaded data along with the headers in the p3d main GUI state structure.

Input parameters:

state

The state structure of p3d_tool_gui.

Provides a GUI to select a data set from the already loaded data sets.

Input parameters:

state

The state structure of p3d_tool_gui.

Collects file suffixes to use as specified in the user-parameter file.

Input parameters:

state

The state structure of p3d_tool_gui.

Keyword parameters:

error

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

Using a raw bias image, which can be noisy with bad pixels, this routine models a "master bias" image. The input image is first smoothed using a median filter, and is thereafter smoothed again using a mean filter.

The bias level can optionally be assumed to be constant in the x- and y-directions.

Input parameters:

in

A two-dimensional array.

Keyword parameters:

	xclean		The x-size (2*xclean+1) of the median filter box.
	yclean		The y-size (2*yclean+1) of the median filter box.
	xsmo		The x-size (2*xsmo+1) of the mean filter box.
	ysmo		The y-size (2*ysmo+1) of the mean filter box.
	const		This parameter is set to 1 if the bias is constant. The default value is: 0
	xconst		This parameter is set to 1 if the output bias is constant in the x-direction. The default value is: 0
	yconst		This parameter is set to 1 if the output bias is constant in the y-direction. The default value is: 0
	topwid		If set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
	logunit		Messages are saved to the file pointed to by this logical file unit, if it is defined.
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all. This is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.
	error		This scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
	debug		No error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

out

The 'cleaned' two-dimensional array.

For a specified raw bias image, this routine calls P3D_MASTERBIAS_SMOOTH, which cleans the data from cosmic rays and bad pixels. The result is an image where the original information in every pixel has been smoothed with the value of neighbor pixels.

Input parameters:

	filename		A scalar string specifying the filename of the raw bias data file.
	parfile		The parameter list filename, this argument must be present.

Keyword parameters:

	ostr		A scalar string with the master-bias specific tring that is used to create the output filename. The default value is: '_mbias'
	quadrant		A scalar integer, or character, that is appended to some of the tracing parameter names. The default value is: ''
	block		A scalar integer, or character, that is appended to some of the tracing parameter names. Note! QUADRANT must be specified if BLOCK is. The default value is: ''
	opath		A scalar string that, optionally, specifies the path where the output data are written.
	ofilename		Upon exit this string contains the name of the written output file.
	opfx		A scalar string specifying a prefix of the output filename. The default value is: ''
	sfx		A scalar string specifying the file ending (without a trailing compression suffix, such as .gz or .Z). The default value is: .fits
	compress		If this keyword is set then the output data file is compressed (using gzip). The default value is: 0
	stawid		If set to a valid ID then a log message is written using this ID for relevant actions.
	topwid		If set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
	logunit		Messages are saved to the file pointed to by this logical file unit, if it is defined.
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all. This is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.
	error		This scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
	debug		No error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
	help		Set this keyword to show this routine documentation, and then exit.

Output parameters:

out

The 'cleaned' bias image.

Creates a two-dimensional bias image using information of prescan and overscan regions, or a pre-set constant value.

The output image is created using a provided constant value, or using prescan and overscan arrays. These arrays are median-value arrays across all columns of prescan and overscan data on the x axis, or all rows of prescan and overscan data on the y axis. One array is used, allowing for a possible gradient in the calculated bias image. Alternatively, one median value of all (used) arrays can be used instead when BIASCONSTANT is set to 1. If BIASCONSTANT is an array of integers, then these integers are used to create a bias image accounting for blocks or extensions.

A plot of all available prescan and overscan bias data is created in the form of a PostScript file. This plot, which shows all prescan and overscan arrays for each block separately, can be used to check the quality of these bias data.

Input parameters:

image

A two-dimensional array of decimal type.

Keyword parameters:

	praw		A scalar integer that specifies if the created bias image should keep prescan regions (1) or not (0).
	detsec		A four-element (columns) -by- number of blocks (rows) integer array that specifies the detector region to use on the CCD for each block. For each row the first two elements are used with the x-axis, and the second two elements with the y-axis.
	nextensions		A scalar integer that contains the number of extensions in the images. Some instruments store one image in the first extension, instead of in the zeroth. When this is the case, NEXTENSIONS should still be set to zero, the first extension is checked automatically; this keyword is only used if BLOCKSARECOMBINED is unset. The default value is: 0
	blocksarecombined		A scalar integer that specifies if multi-block ages are available in separate files (0) or in e same file (1).
	biaspx		If this keyword is set, the x-axis prescan region (PRESCANX) is used when preparing a bias image. The same array is used with all y-axis columns of data.
	biaspy		If this keyword is set, the y-axis prescan region (PRESCANY) is used when preparing a bias image. The same array is used with all x-axis rows of data.
	biasox		If this keyword is set, the x-axis overscan region (OVERSCANX) is used when preparing a bias image. The same array is used with all y-axis columns of data.
	biasoy		If this keyword is set, the y-axis overscan region (OVERSCANY) is used when preparing a bias image. The same array is used with all y-axis rows of data.
	biasconstant		This keyword can be used in two ways: Set this keyword to use a constant value as a bias value; otherwise, one of the arrays specified above is used. All the prescan and overscan regions specified using the keywords BIASPX, BIASPY, BIASOX, and BIASOY can be used when this keyword is set; otherwise, only one of them. Specifically, the one value is calculated as the median value of all used prescan and overscan arrays. If this keyword is set to an array of floating-point type values, these values are used to create a bias. The number of elements must be the same as the number of blocks or extensions.
	cumulativedetsep		This keyword is passed on to p3d_misc_odetsec.
	rawdataarecombined		When this keyword is set, raw data of separate cks are read from separate files, which are then bined into one image.
	prescanx		When BIASPX is set, this keyword must contain the x-axis prescan arrays (as tags 'd1'–'dn', where n is short for the number of blocks). Each array has as many elements as the data have rows (on the y axis).
	prescany		When BIASPY is set, this keyword must contain the y-axis prescan arrays (as tags 'd1'–'dn', where n is short for the number of blocks). Each array has as many elements as the data have columns (on the x axis).
	overscanx		When BIASOX is set, this keyword must contain the x-axis overscan arrays (as tags 'd1'–'dn', where n is short for the number of blocks). Each array has as many elements as the data have rows (on the y axis).
	overscany		When BIASOY is set, this keyword must contain the y-axis overscan arrays (as tags 'd1'–'dn', where n is short for the number of blocks). Each array has as many elements as the data have columns (on the x axis).
	psplot		A plot that shows all bias sections is written to a PostScript file when this keyword is set. The default value is: 1
	a2		Set this keyword to use the A2 paper format with PostScript and PDF output instead of A4.
	a3		Set this keyword to use the A3 paper format with PostScript and PDF output instead of A4.
	a5		Set this keyword to use the A5 paper format with PostScript and PDF output instead of A4.
	letter		Set this keyword to use the US Letter paper format with PostScript and PDF output instead of A4.
	legal		Set this keyword to use the US Legal paper format with PostScript and PDF output instead of A4.
	tabloid		Set this keyword to use the US Tabloid paper format with PostScript and PDF output instead of A4.
	psfilename		A scalar string that is used as output filename for the PostScript file. The file is written to the current directory when this keyword does not contain any path; this keyword is only considered when PSPLOT is set. The default value is: 'p3d_tool_pobias.ps'
	compress		If this keyword is set, an attempt is made to compress the output PostScript file using bzip2. The default value is: 1
	topwid		If set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
	logunit		Messages are saved to the file pointed to by this logical file unit if it is defined.
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all; this is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines; this may be a useful mode when debugging the code.
	error		This scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
	debug		No error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
	help		Set this keyword to show this routine documentation and then exit.

Output parameters:

bias

A two-dimensional array of floating-point type, which contains the calculated bias image.

Enters a loop where pre-defined poll files are checked for information on which p3d tool to launch next.

This tool can only be launched from a system shell, where two compulsory arguments must be specified and two optional keywords may be specified:

The first argument is a scalar string that contains an identifier for the server instance to be run. The string must contain a path with machine and user-specific information, such as (on *NIX-type machines) "/tmp/p3d_server_machine_username/"; the server puts all temporary files in this directory. The remaining part of the string must contain a thread identifier after a final underscore, so that the complete string is, for example: "/tmp/p3d_server_machine_username/p3d_server_1". Once a server is started, an empty file with the name FILENAME is created. The server shuts down when a file with the name FILENAME + '_STOP' is found; at this point both FILENAME and FILENAME + '_STOP' are removed.

The second argument is also a scalar string that contains an identifier of jobs that will be executed by this server. All job files must exist in the directory of FILENAME. In each loop, the server looks for job files with the filename POLLFILE + '_*', where a number must be contained in the wildcard, excluding any additional underscores. After the job files are sorted by number, the first file is taken.

Examples:

This tool is not called by itself, but is a wrapper for all other p3d tools when used through the Python tool p3d_dispatch.py.