This routine calculates cross-dispersion line profiles for each spectrum and each wavelength bin in the input image (specified with FILENAME). The centroid positions of TRACES are used as starting central positions for each line profile.

The profile-fitting procedure is based on the mpfit routine of Craig Markwardt (Markwardt 2009). The necessary files (mpfit.pro and the cmpfit package) can be downloaded from his website (see below).

Note: Some instruments use a varying number of spectra that are collected in a group of spectra, with empty space between them on the CCD. The instrument-specific parameter 'lprofn_tr' -must- be set to the maximum number of spectra per group, otherwise this routine will enter an infinite loop (which can be left using Ctrl+C).

Links

http://purl.com/net/mpfit

References

Markwardt, C.B. 2009, "Non-Linear Least Squares Fitting in IDL with MPFIT," in Astronomical Data Analysis Software and Systems XVIII, Quebec, Canada, eds. D. Bohlender, P. Dowler & D. Durand (ASP: San Francisco), ASP Conf. Ser., 411, 251

Input parameters:

	filename		A scalar string with the name of a file with data that will be used to calculate the cross-dispersion line profiles.
	bias		Either a scalar string with the name of a file that contains a master-bias image, or a two-dimensional image that is used as a bias image.
	traces		A two-dimensional array of decimal type that contains the (starting) centroids of each spectrum and each wavelength bin.

Keyword parameters:

	dmbias		This scalar decimal value specifies the error in the data of BIAS [ADU] (used with master-bias images).
	gaps		This array of decimal values is used to determine the set of spectra which is used to calculate line profiles for simultaneously.
	lprofn		An optional scalar integer that specifies the number of spectra that are fit together; this keyword is set automatically in p3d_ctrace when reducing [p3d-]simulated data. The instrument parameter 'lprofn_tr' is not read when this keyword is set.
	xstr		An empty string, or a three character string that is appended to some of the tracing parameter names. The default value is: ''
	xbin		Dispersion axis binning factor. The default value is: 1
	ybin		Cross-dispersion axis binning factor. The default value is: 1
	gain		This scalar decimal value specifies the gain factor of the data in FILENAME [e-/ADU].
	rdnoise		This scalar (or array of) decimal value(s) specifies the readout noise of the data in FILENAME [ADU].
	detector		A scalar integer that specifies the currently selected detector; DETECTOR is a zero-based value. The default value is: 0
	nthreads		A scalar integer that specifies how many threads to use in the parallelized line-profile calculations. The calculation speed scales nearly linearly with the number of threads. The default value is: 1
	title		A scalar string used in the GUI header when visualizing the line profiles. The default value is: 'Cross-dispersion line profiles of: '+FILENAME+'.'
	kwrdlist		A scalar string with the name of a file, that contains a two-column list of p3d-names and instrument-specific names for fits-header keywords.
	ifunum		Some instruments (/FVIRUS) use several IFU bundles with one setup file. For these setup this integer value specifies an IFU id, which associated entries are searched for in the dead-fibers file.
	parfile		A scalar string with the name of a file, that contains a two-column list of instrument-specific parameters.
	userparfile		A scalar string with the name of a file with user- defined parameters. The following parameters are read here from this file: dist_tr, fwhm_tr, deadfibersfile, lproffun_tr, lprofendmin_tr, lprofn_tr, lprofmaxiter_tr, lprofdint_tr, lprofdwid_tr: These parameters are described in the instrument-specific parameter file. rebuildlib, dontuseCroutines, lprofcenter, lprofcoffset, lprofwidth, lprofnobgslope, lprofbgzlevel, lprofminfwhmfac, lprofmaxfwhmfac, lproflowcut: These parameters are described in the master user-parameter file. recenterusetelluric, recenteroffset, recenterlimval, recentertellines, recentermedwidth, recenterlimval, recenterdpixpos: These parameters are used to configure the line-profile recentering. Please see the master user-parameter file as well as the keyword descriptions in this file for RECENTERVAL and RECENTERLIMVAL.
	cumulativedetsep		This keyword is passed on to p3d_misc_odetsec.
	monitor		If this keyword is set then a line profiles viewer is shown after all profiles are fitted. The default value is: 1
	oprof		On output this variable contains the name of the function that was used in the fitting procedure.
	daxis		Defines the dispersion direction dimension of the data in FILENAME. The default, 1, is in the x-direction. The default value is: 1
	fitcenter		If this keyword is set, the profile center positions are fitted. The outcome is in this case an offset array (see LPROFS). The profile width is taken from the FIXPROFS parameter.
	fixprofs		This variable is only used if FITCENTER is used. It must then have the same format as LPROFS has when FIXPROFS is not provided, and is used to provide initial profile center positions and set fixed values of the profile widths when fitting the line center positions.
	dispmask		A scalar string with the name of a dispersion-mask image file; this dispersion mask is used to locate telluric lines in the data when calculating the offset between the continuum image and the object image.
	recenterval		This keyword is only used if FITCENTER is used. Set this keyword or RECENTERLIMVAL to activate the use of profile recentering on science images (recenterprofiles). This keyword is able to configure several of the recentering options. If RECENTERVAL is a: string the telluric line mode is used (recenterusetelluric). RECENTERVAL='telluric' results in the default file being used, while any other string is interpreted as a filename (recentertellines). decimal value the value is used as a preset of fset (recenteroffset); allowed values are - 2.0 <= value <= 2.0. other values are used as a median-filter width with data, the used width is actually long(|RECENTERVAL|). Note! The use of this keyword overrides the setting in the user-parameter file.
	recenterlimval		This keyword is only used if FITCENTER is set. Set this keyword, or RECENTERVAL, to activate the use of profile recentering on science images (recenterprofiles). This keyword is used to set recenterlimval, which is used to filter out all the spectra that have a lower maximum count than this value [ADU], before calculating an offset using the median-filter method or the telluric-line method. Note! The use of this keyword overrides the setting in the user-parameter file.
	detsepgrp		This keyword can be set in instrument setups where there are more than one detector on the spatial axis, and the background levels differ (making a line-profile fit tricky). The keyword should in this case be set to a positive non-zero integer that indicates beyond which spectrum the new detector begins. This value can also be set with the (instrument- or) user-parameter 'detector_sepgrp'. If this keyword, or user-parameter is set, it is also mandatory to set DETSEPNUM.
	detsepnum		Together with DETSEPGRP, this value specifies the number of spectra in the group that falls within the first detector; the value must be a positive non-zero integer. If DETSEPGRP is set, it is also mandatory to set this keyword. This value can also be set with the (instrument- or) user-parameter 'detector_sepnum'.
	cinv		Set this keyword to plot white lines on a black background instead of the default, which is to plot black lines on a white background.
	a2		Set this keyword to use the A2 paper format with the PostScript output instead of A4.
	a3		Set this keyword to use the A3 paper format with the PostScript output instead of A4.
	a5		Set this keyword to use the A5 paper format with the PostScript output instead of A4.
	letter		Set this keyword to use the US Letter paper format with the PostScript output instead of A4.
	legal		Set this keyword to use the US Legal paper format with the PostScript output instead of A4.
	tabloid		Set this keyword to use the US Tabloid paper format with the PostScript output instead of A4.
	psnumwave		see p3d_display_lineprofiles.
	postscriptfile		see p3d_display_lineprofiles.
	blockgui		The created line-profiles checking GUI is blocked if this keyword is set.
	compress		see p3d_display_lineprofiles.
	stawid		If set to a valid ID then a log message is written using this ID for relevant actions.
	topwid		If set, error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
	logunit		Messages are saved to the file pointed to by this logical file unit, if it is defined.
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all. This is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.
	font		Set this scalar string to the name of the font you want to use with all the widget components of this tool.
	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:

lprofs

A three-dimensional array with the line profile parameters (3rd dimension) of each spectrum and each wavelength bin. Note: Whenever the keyword FITCENTER is set, LPROFS only contains the offset line center positions; i.e. the difference between the newly calculated positions and the input center positions (of FIXPROFS).

Fit a cross-dispersion cut with a sum of Gaussians using MPFIT.

If the keyword FITC is specified then the profile center positions are fitted as well.

If the keyword FITW is specified then the profile widths are fitted as well.

Input parameters:

	x		A one-dimensional array with the abscissae of Y.
	y		A one-dimensional array with the data to be fitted.
	dy		A one-dimensional array with the variance of Y.
	traces		A one-dimensional array with the traces along Y.
	par		A one-dimensional array with fitting initial values. Overwritten with the fitted parameter values upon return.

Keyword parameters:

	oniter		On output this parameter contains the number of iterations performed by MPFIT; ONITER is a scalar integer.
	ochisq		On output this parameter contains the chi square value of the fit; OCHISQ is a scalar decimal value.
	onfev		On output this parameter contains the number of function evaluations performed by MPFIT; ONFEV is a scalar integer.
	odof		On output this parameter contains the number of degrees of freedom; ODOF is a scalar integer.
	mpmaxiter		A scalar integer specifying the maximum number of allowed iterations for MPFIT.
	proffun		A scalar string with the name of the function to use when (re-)calculating the line profile.
	fitc		If set, then the profile center positions are fitted, instead of using the fixed trace mask positions. The allowed offset in this case is specified by FOFFSET.
	fitw		If set, then the profile widths are fitted; instead of using one profile width per group of spectra.
	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 refines already calculated spectrum positions (in the cross-dispersion direction). The refining is made by weighting each spectrum position with the cross-dispersion axis profile. Optionally, a Gaussian profile of specified proportions can be used for further weighting (using the GAP argument). Such a Gaussian is always used with the first and the last spectra.

Input parameters:

	array		A two-dimensional array of floating-point type.
	oldpos		A one-dimensional array which contains the spectrum positions which are to be corrected.
	gap		If used: a one-dimensional array of floating-point type values. If not used: a scalar integer set to – 1.
	dist		A scalar floating-point type value that defines the expected separation of spectra in the cross-dispersion direction of ARRAY; DIST > 0.0.
	fwhm		A scalar floating-point type value that defines the full width at half maximum of the Gaussian profile, which is used when weighting the cross-dispersion spectrum profile; FWHM > 0.0.
	width		A scalar floating-point type value that specifies the cross-dispersion profile width; WIDTH > 0.0.
	niterat		A scalar integer that specifies how many times the weighted spectrum position value is calculated; NITERAT >= 1.

Keyword parameters:

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

Output parameters:

	newpos		A one-dimensional array that contains the corrected positions of all spectra provided in OLDPOS.
	integral		TBA.

This routine calculates spectrum cross-dispersion positions for all wavelength bins, starting with an array of positions which was calculated for a scaled-down array (in the dispersion direction; REFPOS). For every spectrum, totally MAXPOS in number, positions along the dispersion direction are linearly interpolated between the already calculated positions of REFTRACES.

Input parameters:

	reftraces		A two-dimensional array of floating point numbers, which provide the spectrum cross-dispersion positions for every spectrum and a number of wavelength bins, which has to be the same as the number of elements in REFPOS.
	refpos		A one-dimensional array of integers specifying the pixels along the dispersion direction in the OUT array (and original data array), which were used to create the scaled-down array. The number of elements in REFPOS must be the same as the number of wavelength bins in REFTRACES.
	maxpos		A scalar integer specifying the number of wavelength bins in the output array.

Keyword parameters:

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

Output parameters:

out

A two-dimensional array of floating point type which holds the linearly interpolated spectrum cross-dispersion positions for every spectrum (1...NSPEC) and wavelength bin (1...MAXPOS).

This routine scans input data in the cross-dispersion direction for the presence and the location of spectrum lines, in the form of local maxima. This is done in a four step algorithm with the following steps:

Input parameters:

	array		A two-dimensional array of floating-point type.
	refmask		A one-dimensional array of integer type.
	dist		A scalar floating-point type value which defines the expected separation of spectra in the cross-dispersion direction of ARRAY.
	dmin		A scalar floating-point type value, which defines that a local maximum at a position of DIST – DMIN is OK for the identification of a spectrum.
	dmax		A scalar floating-point type value, which defines that a local maximum at a position of DIST + DMAX is OK for the identification of a spectrum.
	cut		A scalar floating-point type value; 0.0 <= CUT <= 1.0. CUT determines the fraction of all pixels along the extracted spectrum (which is centered on COLUMN) that should have a local maximum in order for the collapsed value (for all spectrum bins) to be a real spectrum.

Keyword parameters:

	width		A scalar integer specifying the half-width of the spectrum region, which is searched for local maxima in the first step. The unit is pixels. The default value is: 12
	column		A scalar integer specifying the pixel position, in the dispersion-direction, where the spectrum is extracted.
	spec0		A scalar floating-point type value specifying the position of the first spectrum (in the cross-dispersion direction).
	var		not sure.
	display		Ordinarilly p3d makes a postscript plot of the spectrum data, together with symbols showing positive identifications of spectra from the different steps. Set this keyword to show the plot in a widget tool.
	fwhm		This value is passed to p3d_tracing_correctpos.pro.
	centervar		This value is passed to p3d_tracing_correctpos.pro.
	niterat		This value is passed to p3d_tracing_correctpos.pro.
	yrange		Defines an y-direction range. If this variable is not set to a two-element array, a min-max value is used instead.
	offsetmpos		A scalar integer specifying an offset during the matching step. This value allows the fitting of data sets with many dead or unused fibers, which are otherwise difficult to match. After the position of the best match has been found, this offset is added to that position. The default value is: 0
	deadfibers		A one-dimensional array of integers specifying which fiber positions are to be ignored when matching the gaps in the third step.
	gaps		An integer array specifying a pre-defined pattern of gaps between spectra in the data; across the cross-dispersion direction. This is an optional input when using DEADFIBERS, see p3d_tracing_trace.
	specsep		A one-dimensional array of floating-point type values specifying the separation between consecutive spectra. If this keyword is not present, the constant separation DIST is used instead.
	pillar		This keyword is used in p3d_tracing_findspec0.
	zeroclean		This keyword is used in p3d_tracing_findspec0.
	cinv		Set this keyword to plot white lines on a black background instead of the default, which is to plot black lines on a white background.
	blockgui		The created trace-check GUI is blocked if this keyword is set.
	topwid		If set, error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
	logunit		Messages are saved to the file pointed to by this logical file unit, if it is defined.
	verbose		Set this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged: 0 Writes no information at all. This is the default. 1 Writes the more important information; regarding subroutine configurations, mostly. 2 Writes most information; includes a more verbose output than 1. 3 Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.
	font		Set this scalar string to the name of the font you want to use with all the widget components of this tool.
	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.
	_extra		Passes on keywords to p3d_display_lineprofiles.pro.

Output parameters:

specpos

A one-dimensional array which contains the fractional positions of all spectra, which were identified in steps i)-iv). Note: The number of elements in SPECPOS is always the same as the number of elements in REFMASK.

For the value COLUMN in the dispersion direction of ARRAY, this routine finds the location of all spectra (it can find) in the cross- dispersion direction.

Input parameters:

	array		A two-dimensional array [not checked for its properties in this routine].
	column		A scalar integer specifying on which pixel in the dispersion direction the data in the cut out wavelength range is centered.
	width		A scalar integer specifying the half wavelength range, which is used to identify the spectra.
	cut		A decimal scalar specifying the fraction of the wavelength bins which must have a maximum in order for a spectrum to be indicated as such; 0.0 <= CUT <= 1.0.
	dist		A scalar value that specifies the mean distance between two spectra.

Keyword parameters:

	pillar		Sharp peaks are by default located as gridpoints of maximum value. Set this keyword to instead look for pillars without a sharp top. The procedure is nearly the same as in the default case, but the array block is at first smoothed using a boxcar average with a width of half the value of DIST. Thereafter, lower gridpoints are looked for in the two pixels that are DIST / 6L pixels away from the current pixel, instead of the immediate neighbors.
	zeroclean		If set, regions next to regions filled by zeroes are set to the lowest value in the closest pixels.
	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:

pos

A one-dimensional array of floating point type which specifies the fractional positions of all found spectra in the cross-dispersion direction. If none was found, pos = – 1L.

This routine does an automatic tracing of raw data files. The steps that are performed are:

The input parameter file (PARFILE) must contain the following keywords (all values must be specified for data before it is read out - in pixels [b]). Optional additional specifiers are the quadrant (Q) and the block (B) – these are specified with the XSTR keyword:

• spnum[_QB]

  The number of spectra.

  If this parameter is not present, an attempt is made to instead read the parameter

  norders[_QB]

  The number of spectrum orders.

• dist_tr[_QB] [b]

  The average separation between consecutive spectra.

• dmin_tr[_QB] [b]

  The minimum allowed spectrum separation.

• dmax_tr[_QB] [b]

  The maximum allowed spectrum separation.

• cut_tr

  This value specifies the fraction of all pixels (2*findwidth_tr+1) that must be found to be a maximum in order for their average to be defined as a maximum.

• findwidth_tr

  This value specifies the number of pixels (/2) that are averaged across the dispersion direction when searching for spectra. The actually used number of pixels is 2*findwidth+1. The maximum number allowed is half the number of pixels on the dispersion axis (although it is not recommended to use that many pixels).

• findcolumn_tr[_QB]

  This value specifies the pixel number, on the dispersion axis, which is used in the first search of spectra on the cross-dispersion axis. The central bin is used if this value is set to -1, or if the specified number is larger than the number of bins. If the value is <-1 then the central bin – value is used.

• centervar_tr[_QB] [b]

  This value specifies a half-width of every spectrum on the cross-dispersion axis. The actual width is 2*centervar_tr+1.

• fwhm_tr [b]

  This value specifies the full width at half maximum of the Gaussian profile, which is used when weighting the cross-dispersion spectrum profile.

• refindwidth_tr [b]

  This value specifies the half-width of the region that is used when calculating a reduced-size positions array.

• refinddist_tr

  This value specifies the dividing factor when determining the size of the reduced size spectrum-positions array.

• smowidth_tr[_QB] The reduced-size data are smoothed across the cross-dispersion axis using a box-car smoothing algorithm and this half-width.

• dispsmowidth_tr

  The spectrum positions of the reduced-size data are smoothed across the dispersion axis using a box-car smoothing algorithm and this half-width.

• niterat_tr

  This value specifies how many times the calculation of the central position, on the cross-dispersion axis, of each spectrum is iterated.

Input parameters:

	parfile		A scalar string specifying the filename of an ASCII file that contains parameters that are used in the tracing process.
	array		A one- or two-dimensional array of decimal type, that provides the data which are used to find the spectrum positions.

Keyword parameters:

	spnum		An optional scalar integer specifying the number of spectra; this keyword must only be set when finding spectra in simulated data, in all other cases it is set here.
	dist		An optional scalar decimal value specifying the spectrum separation; this keyword must only be set when finding spectra in simulated data, in all other cases it is set here.
	gaps		An integer array specifying a pre-defined pattern of gaps between spectra in the data; across the cross-dispersion direction. This is an optional input. Assuming equally spaced spectra on the CCD in the cross-dispersion direction the values in this array specify the sequential positions where no spectra are found. For example if GAPS contains [16,16... then the pre-defined spectrum sequence 0,1,2,...,15,16,17,18,19,... is changed to: 0,1,2,...,15,18,19,20,21,... i.e. there must be no spectra in the linearly sequential positions 16 and 17.
	const		If set then it is assumed that the spectrum positions are constant in the dispersion direction (this is generally not true). The default value is: 0
	cdbin		Binning factor for the y axis (DAXIS==1) or the x axis (DAXIS==2). The default value is: 1
	dbin		Binning factor for the x axis (DAXIS==1) or the y axis (DAXIS==2). The default value is: 1
	spec0		A scalar decimal value specifying the position of the first spectrum. The default value is: -1
	yrange		this variable is forwarded to P3D_TRACING_FINDSPEC.
	var_spec0		A scalar decimal value. If SPEC0 is set then VAR_SPEC0 provides the uncertainty in the position.
	xstr		An empty string, or a three character string that is appended to some of the tracing parameter names. The default value is: ''
	no_display		If set, then results are not displayed.
	userparfile		A scalar string specifying the name of an optional user-parameter file, that could contain any of the keywords read from the instrument parameter file (except for 'spnum').
	daxis		Defines the dispersion direction dimension of IMAGE. The default, 1, is in the x-direction. The default value is: 1
	ifunum		Some instruments (/FVIRUS) use several IFU bundles with one setup file. For these setup this integer value specifies an IFU id, which associated entries are searched for in the dead-fibers file.
	alsof		If this keyword is set it is assumed that the tracing procedure consists of four steps instead of three, where the final step is the cross-dispersion profile fitting, which is not covered by this routine.
	dataheader		A FITS header string array, which is used when ARRAY does not contain IFU data, but several orders of separated spectra. In this case, the number of orders in the data file is read using the header string array.
	cinv		Set this keyword to plot white lines on a black background instead of the default, which is to plot black lines on a white background.
	postscriptfile		see p3d_tracing_findspec->p3d_display_lineprofiles.
	a2		Set this keyword to use the A2 paper format with the PostScript output instead of A4.
	a3		Set this keyword to use the A3 paper format with the PostScript output instead of A4.
	a5		Set this keyword to use the A5 paper format with the PostScript output instead of A4.
	letter		Set this keyword to use the US Letter paper format with the PostScript output instead of A4.
	legal		Set this keyword to use the US Legal paper format with the PostScript output instead of A4.
	tabloid		Set this keyword to use the US Tabloid paper format with the PostScript output instead of A4.
	compress		see p3d_tracing_findspec->p3d_display_lineprofiles.
	blockgui		The created trace-check GUI is blocked if this keyword is set.
	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.
	font		Set this scalar string to the name of the font you want to use with all the widget components of this tool.
	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.
	_extra		Passes on keywords to p3d_tracing_findspec.pro.

Output parameters:

traces

A one- or two-dimensional array of floating point type specifying the spectrum position for every spectrum at every pixel in the dispersion direction. This is the trace mask.