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: spectrum tracing

Summary

PROp3d_tracing_calculate_lprofs
This routine calculates cross-dispersion line profiles for each spectrum and each wavelength bin in the input image (specified with FILENAME).
PROp3d_tracing_calculate_lprofs_fits
Fit a cross-dispersion cut with a sum of Gaussians using MPFIT.
PROp3d_tracing_correctpos
This routine refines already calculated spectrum positions (in the cross-dispersion direction).
PROp3d_tracing_expand_traces
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).
PROp3d_tracing_findspec
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.
PROp3d_tracing_findspec0
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.
PROp3d_tracing_trace
This routine does an automatic tracing of raw data files.

Copyright

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

Copyright 2009-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_tracing_calculate_lprofs.pro, line 531, last changed at 2017-06-06 by christersandin (revision 4602)

p3d_tracing_calculate_lprofs, filename, bias, traces, lprofs, dmbias=, gaps=, xstr=, xbin=, ybin=, gain=, rdnoise=, detector=, nthreads=, title=, kwrdlist=, ifunum=, parfile=, userparfile=, cumulativedetsep=, /monitor, oprof=, daxis=, fixcenter=, fixprofs=, dispmask=, recenterval=, recenterlimval=, detsepgrp=, detsepnum=, /cinv, /a2, /a3, /a5, /letter, /legal, /tabloid, psnumwave=, postscriptfile=, font=, /compress, /blockgui, stawid=, topwid=, logunit=, verbose=, error=, /debug, /cdebug, /help

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:
filenameA scalar string with the name of a file with data that will be used to calculate the cross-dispersion line profiles.
biasEither 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.
tracesA two-dimensional array of decimal type that contains the (starting) centroids of each spectrum and each wavelength bin.
Keyword parameters:
dmbiasThis scalar decimal value specifies the error in the data of BIAS [ADU] (used with master-bias images).
gapsThis array of decimal values is used to determine the set of spectra which is used to calculate line profiles for simultaneously.
xstrAn empty string, or a three character string that is appended to some of the tracing parameter names. The default value is: ''
xbinDispersion axis binning factor. The default value is: 1
ybinCross-dispersion axis binning factor. The default value is: 1
gainThis scalar decimal value specifies the gain factor of the data in FILENAME [e-/ADU].
rdnoiseThis scalar (or array of) decimal value(s) specifies the readout noise of the data in FILENAME [ADU].
detectorA scalar integer that specifies the currently selected detector; DETECTOR is a zero-based value. The default value is: 0
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
titleA scalar string used in the GUI header when visualizing the line profiles. The default value is: 'Cross-dispersion line profiles of: '+FILENAME+'.'
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.
ifunumSome 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.
parfileA scalar string with the name of a file, that contains a two-column list of instrument-specific parameters.
userparfileA 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.
cumulativedetsepThis keyword is passed on to p3d_misc_odetsec.
monitorIf this keyword is set then a line profiles viewer is shown after all profiles are fitted. The default value is: 1
oprofOn output this variable contains the name of the function that was used in the fitting procedure.
daxisDefines the dispersion direction dimension of the data in FILENAME. The default, 1, is in the x-direction. The default value is: 1
fitcenterIf this keyword is set, then 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.
fixprofsThis 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.
dispmaskA 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.
recentervalThis 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.
recenterlimvalThis 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.
detsepgrpThis 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.
detsepnumTogether 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'.
cinvSet this keyword to plot white lines on a black background instead of the default, which is to plot black lines on a white background.
a2Set this keyword to use the A2 paper format with the PostScript output instead of A4.
a3Set this keyword to use the A3 paper format with the PostScript output instead of A4.
a5Set this keyword to use the A5 paper format with the PostScript output instead of A4.
letterSet this keyword to use the US Letter paper format with the PostScript output instead of A4.
legalSet this keyword to use the US Legal paper format with the PostScript output instead of A4.
tabloidSet this keyword to use the US Tabloid paper format with the PostScript output instead of A4.
psnumwavesee p3d_display_lineprofiles.
postscriptfilesee p3d_display_lineprofiles.
blockguiThe created line-profiles checking GUI is blocked if this keyword is set.
compresssee p3d_display_lineprofiles.
stawidIf set to a valid ID then a log message is written using this ID for relevant actions.
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.
cdebugA keyword as DEBUG used with the called C routines.
helpSet 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, then LPROFS only contains the offset line center positions; i.e. the difference between the newly calculated positions and the input center positions (of FIXPROFS).

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

p3d_tracing_calculate_lprofs_fits, x, y, dy, traces, par, parinfo, oniter=, ochisq=, onfev=, odof=, mpmaxiter=, proffun=, /fitc, /fitw, topwid=, logunit=, verbose=, error=, /debug, /help

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:
xA one-dimensional array with the abscissae of Y.
yA one-dimensional array with the data to be fitted.
dyA one-dimensional array with the variance of Y.
tracesA one-dimensional array with the traces along Y.
parA one-dimensional array with fitting initial values. Overwritten with the fitted parameter values upon return.
Keyword parameters:
oniterOn output this parameter contains the number of iterations performed by MPFIT; ONITER is a scalar integer.
ochisqOn output this parameter contains the chi square value of the fit; OCHISQ is a scalar decimal value.
onfevOn output this parameter contains the number of function evaluations performed by MPFIT; ONFEV is a scalar integer.
odofOn output this parameter contains the number of degrees of freedom; ODOF is a scalar integer.
mpmaxiterA scalar integer specifying the maximum number of allowed iterations for MPFIT.
proffunA scalar string with the name of the function to use when (re-)calculating the line profile.
fitcIf 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.
fitwIf set, then the profile widths are fitted; instead of using one profile width per group of spectra.
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_tracing_correctpos.pro, line 126, last changed at 2017-06-28 by christersandin (revision 4659)

p3d_tracing_correctpos, array, oldpos, gap, dist, fwhm, width, niterat, newpos, integral, topwid=, logunit=, verbose=, error=, /debug, /help

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:
arrayA two-dimensional array of floating-point type.
oldposA one-dimensional array which contains the spectrum positions which are to be corrected.
gapIf used: a one-dimensional array of floating-point type values. If not used: a scalar integer set to – 1.
distA scalar floating-point type value that defines the expected separation of spectra in the cross-dispersion direction of ARRAY; DIST > 0.0.
fwhmA 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.
widthA scalar floating-point type value that specifies the cross-dispersion profile width; WIDTH > 0.0.
niteratA scalar integer that specifies how many times the weighted spectrum position value is calculated; NITERAT >= 1.
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.
debugAn 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.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
newposA one-dimensional array that contains the corrected positions of all spectra provided in OLDPOS.
integralTBA.

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

p3d_tracing_expand_traces, reftraces, refpos, maxpos, out, topwid=, logunit=, verbose=, error=, /debug, /help

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:
reftracesA 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.
refposA 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.
maxposA scalar integer specifying the number of wavelength bins in the output array.
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 of floating point type which holds the linearly interpolated spectrum cross-dispersion positions for every spectrum (1...NSPEC) and wavelength bin (1...MAXPOS).

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

p3d_tracing_findspec, array, refmask, dist, dmin, dmax, cut, specpos, width=, column=, spec0=, var=, /display, fwhm=, centervar=, niterat=, yrange=, deadfibers=, gaps=, specsep=, /zeroclean, /cinv, /blockgui, topwid=, logunit=, verbose=, findspec=, font=, error=, /debug, /help, _extra=

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:

i.

A stripe of width 2 * WIDTH + 1, that is centered on pixel COLUMN on the dispersion axis, is searched for local maxima. Rows of pixels, where at least a fraction CUT of the total number of elements in the row are found to be a local maximum, are indicated as locations of spectra. In order to account for slightly tilted spectra the consecutive row of pixels is also taken into account (resulting in fractional positions). The result is stored in the array MASKPOS_0.

ii.

The actual spectrum positions on the CCD should be separated by a roughly constant value – DIST, allowing for possible deviations from a constant separation using DMIN and DMAX. The output array of step i., MASKPOS_0, is traversed in order to find the largest group of spectra which are separated by about DIST pixels; local maxima due to cosmic rays, for instance, would unlikely appear in regularly separated 'hits'. The result is stored in MASKPOS.

Alternatively, the separation can be variable as specified in the input array SPECSEP. In this case DIST and GAPS are not used in this tracing step. However, the gaps are inserted before the third step (iii.) in order to match the spectra. It is important that the first spectrum is actually found in the data in tracing step i. If it is not, the first spectra -must- be marked as dead, unused, or possibly unused, in the dead fibers file.

iii.

The list of spectra returned in the result array of step ii. could still contain elements which are not expected for the used instrument. In this third step the calculated spectrum mask of MASKPOS (REGMASK, REMASKPOS) is compared to a pre-defined spectrum mask, REFMASK. REFMASK is moved over REGMASK in order to find the position with the largest number of hits. Positions of the matched elements are stored in the results array SPECPOS.

Note: SPECPOS only gives the position for the specified pixel on the cross-dispersion (spatial) axis.

Note: If DEADFIBERS is specified, the spectra of this array are ignored in this third step of the tracing.

The format of the integer-array REFMASK is as follows: It should contain enough DIST-separated elements to cover all spectra along the cross-dispersion axis. The location of a real spectrum is marked with a 1 in this array. Elements should correspondingly be set to 0 for positions where there is a gap in the sequence of spectra.

iv.

In a fourth step spectrum positions for elements of REFMASK, which could not be identified in the matching of step iii), are interpolated (or extrapolated) from the positions identified in the previous steps.

v.

More accurate positions are calculated by weighting the positions array with the cross-dispersion profile of the data.

Input parameters:
arrayA two-dimensional array of floating-point type.
refmaskA one-dimensional array of integer type.
distA scalar floating-point type value which defines the expected separation of spectra in the cross-dispersion direction of ARRAY.
dminA 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.
dmaxA 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.
cutA 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:
widthA 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
columnA scalar integer specifying the pixel position, in the dispersion-direction, where the spectrum is extracted.
spec0A scalar floating-point type value specifying the position of the first spectrum (in the cross-dispersion direction).
varnot sure.
displayOrdinarilly 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.
fwhmThis value is passed to p3d_tracing_correctpos.pro.
centervarThis value is passed to p3d_tracing_correctpos.pro.
niteratThis value is passed to p3d_tracing_correctpos.pro.
yrangeDefines an y-direction range. If this variable is not set to a two-element array, a min-max value is used instead.
offsetmposA 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
deadfibersA one-dimensional array of integers specifying which fiber positions are to be ignored when matching the gaps in the third step.
gapsAn 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.
specsepA 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.
zerocleanThis keyword is used in p3d_tracing_findspec0.
cinvSet this keyword to plot white lines on a black background instead of the default, which is to plot black lines on a white background.
blockguiThe created trace-check GUI is blocked if this keyword is set.
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.

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

routines/p3d_tracing_findspec0.pro, line 116, last changed at 2015-11-18 by christersandin (revision 3781)

p3d_tracing_findspec0, array, column, width, cut, pos, dist, /zeroclean, topwid=, logunit=, verbose=, error=, /debug, /help

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:
arrayA two-dimensional array [not checked for its properties in this routine].
columnA scalar integer specifying on which pixel in the dispersion direction the data in the cut out wavelength range is centered.
widthA scalar integer specifying the half wavelength range, which is used to identify the spectra.
cutA 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.
distA scalar value that specifies the mean distance between two spectra.
Keyword parameters:
zerocleanIf set, regions next to regions filled by zeroes are set to the lowest value in the closest pixels.
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:
posA 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.

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

p3d_tracing_trace, parfile, array, traces, gaps=, /const, bin=, dbin=, spec0=, yrange=, var_spec0=, xstr=, /no_display, daxis=, ifunum=, userparfile=, /alsof, /cinv, postscriptfile=, /a2, /a3, /a5, /letter, /legal, /tabloid, /compress, /blockgui, stawid=, topwid=, logunit=, verbose=, font=, error=, /debug, /help, _extra=

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

1.

Locate the spectra

2.

Follow the spectra in the direction of dispersion (optional)

ad 1: Peaks are looked for in several (max. 81) columns and compared to minimize errors because of noise. The procedure works save for at least 10-20 columns, better more than 40 columns (depending on SNR).

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.

  • 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 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:
parfileA scalar string specifying the filename of an ASCII file that contains parameters that are used in the tracing process.
arrayA one- or two-dimensional array of decimal type, that provides the data which are used to find the spectrum positions.
Keyword parameters:
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.

constIf 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
binBinning factor for the y axis (DAXIS==1) or the x axis (DAXIS==2). The default value is: 1
dbinBinning factor for the x axis (DAXIS==1) or the y axis (DAXIS==2). The default value is: 1
spec0A scalar decimal value specifying the position of the first spectrum. The default value is: -1
yrangethis variable is forwarded to P3D_TRACING_FINDSPEC.
var_spec0A scalar decimal value. If SPEC0 is set then VAR_SPEC0 provides the uncertainty in the position.
xstrAn empty string, or a three character string that is appended to some of the tracing parameter names. The default value is: ''
no_displayIf set, then results are not displayed.
userparfileA 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').
daxisDefines the dispersion direction dimension of IMAGE. The default, 1, is in the x-direction. The default value is: 1
ifunumSome 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.
alsofIf 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.
cinvSet this keyword to plot white lines on a black background instead of the default, which is to plot black lines on a white background.
postscriptfilesee p3d_tracing_findspec->p3d_display_lineprofiles.
a2Set this keyword to use the A2 paper format with the PostScript output instead of A4.
a3Set this keyword to use the A3 paper format with the PostScript output instead of A4.
a5Set this keyword to use the A5 paper format with the PostScript output instead of A4.
letterSet this keyword to use the US Letter paper format with the PostScript output instead of A4.
legalSet this keyword to use the US Legal paper format with the PostScript output instead of A4.
tabloidSet this keyword to use the US Tabloid paper format with the PostScript output instead of A4.
compresssee p3d_tracing_findspec->p3d_display_lineprofiles.
blockguiThe created trace-check GUI is blocked if this keyword is set.
stawidIf set to a valid ID then a log message is written using this ID for relevant actions.
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.
_extraPasses on keywords to p3d_tracing_findspec.pro.
Output parameters:
tracesA 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.

page last updated on: Wednesday June 28, 2017 11:06:27; retrieved on: Saturday July 22, 2017 02:45:42