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 extraction

Summary

PROp3d_extract
This is the p3d spectral extraction routine.
PROp3d_extract_optimal
This routine is a wrapper for the two routines that perform the actual task of optimal extraction, viz.
PROp3d_extract_optimal_mox
This routine extracts spectra from a two-dimensional spectrum image using the modified optimal extraction of Sandin et al.
PROp3d_extract_optimal_mpd
This routine extracts spectra from a two-dimensional spectrum image using the multi-profile deconvolution approach of Sharp & Birchall 2010, PASA, 27, 91.
PROp3d_extract_prepare_extraction
This routine loads science-object image, a bad-pixel mask image, a trace-mask image, and a master-bias image.
PROp3d_extract_tophat
This routine provides a simple spectrum extraction algorithm.

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_extract.pro, line 694, last changed at 2017-04-13 by christersandin (revision 4547)

p3d_extract, array, traces, out, out_bsw, dout=, bdout=, parfile=, flat=, dflat=, bias=, dbias=, bpmask=, obpmask=, bobpmask=, satlimit=, satmask=, bsatmask=, gain=, rdnoise=, userparfile=, detsec=, ifunum=, cumulativedetsep=, bsw=, bin=, xstr=, method=, lprofs=, proffun=, /scattlightsubtract, /exmonitor, subtitle=, nthreads=, daxis=, font=, /cinv, postscriptfile=, /compress, /blockgui, stawid=, topwid=, logunit=, verbose=, error=, /debug, /cdebug, /help

This is the p3d spectral extraction routine. The algorithm works by integrating along the cross-dispersion direction. Optionally a shift of the image to the tracemask can be calculated and a flat field correction can be made.

his routine is actually a driver for the spectrum extraction outines p3d_extract_tophat and p3d_extract_optimal.

Input parameters:
arrayA raw spectrum image, of two dimensions.
tracesA tracemask, that must have the same number of elements on the dispersion axis as ARRAY.
Keyword parameters:
doutThe resulting error of the extraction image OUT. This is only calculated if DBIAS is set.
bdoutThe resulting error of the extr. image OUT_BSW. This is only calculated if DBIAS is set.
parfileThe parameter list filename, this keyword must be present. This file is used to extract the number of spectra (SPNUM) and the spectrum extraction width (PROFWIDTH).
flatIf flat fielding is requested then this variable should be set to the raw flatfield data, or the final flatmask.
dflatIf present, then this is the error in FLAT. The dimensions of DFLAT must be the same as those of FLAT. If BIAS and FLAT are present, then DFLAT must also be present.
biasIf bias subtraction is requested, then this variable should give the bias image data.
dbiasIf present, then this is the error in BIAS [ADU]. This value must be a decimal value (scalar or array). DOUT is only calculated if DBIAS is set. The number of elements of DBIAS must correspond to the number of rows of DETSEC.
bpmaskThis two-dimensional array, of byte type, is used, if set, by the routine p3d_extract_optimal.
obpmaskA two-dimensional byte image of the same dimensions as OUT. Each element in this image contains the number of masked pixels in the bad-pixels mask that were used to calculate the extracted image. This array is only calculated if BPMASK is set.
bobpmaskA two-dimensional byte image of the same dimensions as OUT_BSW. Each element in this image contains the number of masked pixels in the bad-pixels mask that were used to calculate the extracted image. This array is only calculated if BPMASK is set.
satlimitA scalar integer that specifies the saturation limit that is used to set each element in the saturation masks (SATMASK and BSATMASK) [ADU]. If any of the pixels that are considered across the center part of the profile is higher than this limit, then the output element is masked.
satmaskA two-dimensional output array of byte type, which indicates spectrum elements that involved saturated raw-data pixels. This array is only calculated if SATLIMIT is set.
bsatmaskA two-dimensional output array of byte type, which indicates spectrum elements of beam switched data that involved saturated raw-data pixels.
gainThe data gain factor [e-/ADU]; a scalar floating-point type value. If DBIAS is present then GAIN must also be present.
rdnoiseThe readout noise [ADU]; a decimal value (scalar or array). If DBIAS is present then GAIN must also be present. The number of elements of RDNOISE must correspond to the number of rows of DETSEC.
userparfileA scalar string specifying the name of an optional user-parameter file, that could contain some of the keywords below. If it does, then these values are recognized used in the spectrum extraction:

'profwidth_bsw_ctex'

optimal extraction

'profwidth_bsw_ex'

optimal extraction

'profwidth_ctex'

optimal extraction

'profwidth_ex'

optimal extraction

'profwidth_variable'

tophat extraction

'deadfibersfile'

dead fibers

'sls_maskwidth'

scatt.-light subtraction

'sls_medfiltern'

scatt.-light subtraction

'sls_polorder'

scatt.-light subtraction

'sls_constantvalue'

scatt.-light subtraction

'sls_gaussfiltersig'

scatt.-light subtraction

'rebuildlib'

C-routine

detsecA four-element (columns) -by- number of blocks (rows) integer array that specifies the detector region to use on the CCD for each block. DBIAS, GAIN, and RDNOISE must have as many elements as DETSEC has rows. Since all arrays of this routine and its subroutines are assumed to have a as the dispersion axis, the 0:1 and 2:3 columns of DETSEC are swapped if DAXIS = 2 (this swapping does not affect the input array).
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.
cumulativedetsepThis keyword is passed on to p3d_misc_odetsec.
bswSpecifies beam switching mode. The default value is: 0
binThe CCD binning factor of the cross-dispersion axis; either the y-direction (DAXIS = 1) or the x-direction (DAXIS = 2). The default value is: 1
xstrAn empty string, or a three character string that is appended to some of the tracing parameter names. The default value is: ''
methodThis scalar string specifies the used spectrum traction method:

tophat'

see p3d_extract_tophat

optimal'

see p3d_extract_optimal. In this case it is mandatory to also provide LPROFS.

The default value is: 'tophat'
lprofsA three-dimensional array with the cross-dispersion line profiles of every spectrum and wavelength bin (in the third dimension). LPROFS is used iff METHOD == 'optimal'.
proffunA scalar string with the name of the function to use when (re-)calculating the profiles (using LPROFS).
scattlightsubtractIf this keyword is set then a model of the ttered light is applied to the raw data. An ge with scattered-light image is first culated, and is thereafter subtracted from the s-subtracted image – before calculating the or or extracting any spectra. Upon exit of this tine the image is returned in this same iable. The model of the scattered light is ated in the following four steps: ll pixels within sls_maskwidth [1.5 * profwidth] ixels of a spectrum are masked to not be used. he remaining unmasked regions are edian-filtered one wavelength bin at a time, sing a median filter of size /sls_medfiltern// * //med_filtern// 20 / //bin// * 20 / //bin//] pixels. The filter s truncated at the boundaries of each region. polynomial of order sls_polorder [7] is fitted or each wavelength bin on the cross-dispersion xis. In order to keep the noise low the dataset hat is used for each wavelength bin is the edian of a region that is five pixels wide, entered on the current wavelength bin. he data is filtered with a Gaussian kernel with pre-defined width sigma sls_gaussfiltersig [30]). The data are onvolved first on the dispersion axis, and hereafter on the cross-dispersion axis. e! This approach to subtract scattared light nly works with instruments where there are some egions on the cross-dispersion axis, which are ree of spectra. Ideally there should be some ixels left on both boundaries, as well as etween the fibers.
exmonitorIf this keyword is set, a line profiles viewer is shown after all fitting is done when using optimal extraction.
subtitleIf this keyword is set to a string then the string is added to the spectrum viewer title (in p3d_extract_optimal).
nthreadsA scalar integer that specifies how many threads to use in the parallelized median calculation, as well as in the parallelized spectrum extraction. The default value is: 1
daxisDefines the dimension of the dispersion direction in the spectrum image; must be either 1 or 2. The default value is: 1
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_display_lineprofiles.
compresssee p3d_display_lineprofiles.
blockguiThe extracted-profiles checking GUI is blocked if this keyword is set.
stawidIf set, then various messages are written to the p3d GUI status line (this must be the widget id of that label widget).
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

fontSet this scalar string to the name of the font you want to use with all the widget components of this tool.
errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
cdebugA keyword as DEBUG used with the called C routines.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
outThe resulting image of the extraction.

routines/p3d_extract_optimal.pro, line 166, last changed at 2017-04-13 by christersandin (revision 4547)

p3d_extract_optimal, im, traces, dim, lprofs, out, dout, /ecalc, bpmask=, obpmask=, satmask=, proffun=, profwidth=, userparfile=, /monitor, /cinv, nthreads=, postscriptfile=, stawid=, topwid=, logunit=, verbose=, error=, /debug, /cdebug, /help, _extra=

This routine is a wrapper for the two routines that perform the actual task of optimal extraction, viz. p3d_extract_optimal_mox and p3d_extract_optimal_mpd.

After the spectra have been extracted the line profile viewer of p3d is launched to allow an examination of the result.

Input parameters:
imA two-dimensional array, that holds the spectra that will be extracted here.
tracesA two-dimensional array, that for every spectrum bin provides the y-position of every spectrum line on the raw data CCD image.
dimA two-dimensional array of the same dimensions as IM, with the errors of IM. DIMAGE must be present. The variance of IM is DIMAGE².
lprofsA three-dimensional array, that for every spectrum bin, of every spectrum, holds the fitting parameters of a cross-dispersion profile. The default value is: sp=size(lprofs)
Keyword parameters:
ecalcErrors are calculated and returned (DOUT) if this keyword is set. The default value is: 1
bpmask

A two-dimensional array of byte type, and of the same dimensions as IM. The weight of all pixels that are non-zero in BPMASK are set to 0. This way bad pixels and pixels that are hit by cosmic rays are given no weight when the spectra are extracted.

Note: If this mask is specified then the eliminate_crays option of the modified optimal extraction is always unset.

obpmaskA two-dimensional output byte array, which indicates how many bad pixels each spectrum element involves. This array is only calculated if BPMASK is set.
satmaskA two-dimensional output byte array, which indicates spectrum elements that involved saturated raw-data pixels. This array is only calculated if SATLIMIT is set (passed on via _EXTRA here).
proffunA scalar string with the name of the function to use when (re-)calculating the line profile.
profwidth2 * PROFWIDTH + 1 is the total pixel-width of the interval where the flux is integrated. This parameter is only used if OPTEXMETHOD == 'modhorne', but is always used when plotting the profiles if MONITOR is set.
userparfileA scalar string specifying the name of an optional user-parameter file, that could contain any of the keywords that are described in the routine description.
monitorIf this keyword is set then a line profiles viewer is shown after the extraction is done. The default value is: 1
subtitleIf this keyword is set to a string then the string is added to the spectrum viewer title.
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.
nthreadsA scalar integer that specifies how many threads to use in the parallelized spectrum extraction.
postscriptfilesee p3d_display_lineprofiles.
stawidIf set, then various messages are written to the p3d GUI status line (this must be the widget id of that label widget).
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

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.
_extraContains keywords that are passed on to other routines.
Output parameters:
outA two-dimensional array of the extracted spectra with the same dimensions as TRACES.
doutA two-dimensional array of the extracted spectra with the same dimensions as OUT. This is the error of OUT.

routines/p3d_extract_optimal_mox.pro, line 261, last changed at 2016-06-30 by christersandin (revision 4257)

p3d_extract_optimal_mox, im, dim, lprofs, out, dout, profwidth=, detsec=, gain=, rdnoise=, proffun=, nextensions=, /rawdataarecombined, /ecalc, bpmask=, obpmask=, satlimit=, satmask=, userparfile=, skipw=, rimage=, stawid=, topwid=, logunit=, verbose=, error=, /debug, /cdebug, /help

This routine extracts spectra from a two-dimensional spectrum image using the modified optimal extraction of Sandin et al. 2010, A&A, 515, A35. Optimal extraction weights are calculated according to the approach of Horne, K. 1986, PASP, 98, 609-617 (all equations in the comments refer to this paper).

The spectra are extracted using (pre-calculated) input profiles (over the cross-dispersion axis) to sum up the flux at every wavelength bin. The input image is turned into an extracted spectrum image, where every spectrum is placed in an individual row.

In order to correct for cross-talk the extraction is iterated; thereby recalculating the fraction every profile occupies of the total profile at every pixel. The total profile is the sum of all profiles in the cross-dispersion direction.

This method also allows for removal of cosmic rays, although note that it may be difficult to remove them efficiently. Also note that the flux is just removed if this method is used, no flux replacement or interpolation is used.

The following parameters are read from the user-parameter file:

eliminate_crays ['no']

If this keyword is set then the extraction is iterated in order to eliminate probable cosmic ray hits across the cross-dispersion profile of every spectrum. The maximum number of iterations is CR_MAXIT, and the threshold that determines if the data of a pixel is a cosmic ray hit is defined by CR_SIGMA.

Note: Cosmic rays are only removed using this approach if no cosmic ray mask has been specified (BPMASK).

correct_crosstalk ['no']

If this keyword is set then the cross-dispersion profiles are rescaled in an iteration procedure in order to correct for fiber-to-fiber cross-talk before the spectra are finally extracted. The condition that is used to determine when the iterations can be finished is if the maximum number of iterations has been reached (CTALK_MAXIT) or if the maximum change in the scaling factors of two consecutive iterations is smaller than CTALK_EPS.

cr_sigma [10]

A scalar decimal value specifying the threshold that is used to see which pixels in the data of a profile are cosmic ray events.

cr_maxit [2]

A scalar integer specifying the maximum number of iterations that are performed during the iterations to eliminate cosmic-ray events in the profiles.

ctalk_eps [1d-5]

A scalar decimal value specifying the maximum allowed value of the difference between the integrated spectrum of two consecutive spectra.

ctalk_maxit [15]

A scalar integer specifying the maximum number of iterations that are performed during the iterations to correct for fiber-to-fiber cross-talk.

ctalk_secit [1]

A scalar integer specifying the maximum number of iterations that are performed in the secondary loop (where the raw data are not used anymore when calculating the variance). This keyword is only used if crosstalk correction is used (secit is always==1 otherwise).

ctalk_reiterate ['no']

If this keyword is set then the full spectrum extraction procedure is iterated two times. The purpose of the first iteration is to calculate a first version fractional profile for every spectrum. Pixels may, in this process, be incorrectly masked as cosmic rays. In particular this is the case if spectra are tightly packed (in which case neighboring spectra are found to be cosmic rays. In the second iteration the first version fractional profile is used initially (instead of 1.0); this will decrease the number of elements which are incorrectly masked as cosmic rays.

pmultfac [10]

A scalar integer specifying a subsampling factor that is used when calculating the profile.

Input parameters:
imA two-dimensional array, that holds the spectra that will be extracted here. The dispersion axis must be the x-axis.
dimA two-dimensional array of the same dimensions as IM, with the errors of IM. DIM must be present. The variance of IM is DIM².
lprofsA three-dimensional array, that for every spectrum bin, of every spectrum, holds the fitting parameters of a cross-dispersion profile. The default value is: sp=size(lprofs)
Keyword parameters:
profwidth2*PROFWIDTH+1 is the total pixel-width of the interval where the flux is integrated.
detsecA four-element (columns) -by- number of blocks (rows) integer array that specifies the detector region to use on the CCD for each block. RDNOISE must have as many elements as DETSEC has rows.
gainThe data gain factor [e-/ADU]; a scalar decimal value.
rdnoiseA decimal scalar or decimal array that specifies the readout noise [ADU]. RDNOISE must have as many elements as DETSEC has rows.
proffunA scalar string with the name of the function to use when (re-)calculating the line profile.
nextensionsA scalar integer indicating the number of data extensions in the input raw data file. The default value is: 0
rawdataarecombinedWhen 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
ecalcIf this keyword is set then output errors are calculated. The default value is: 0
bpmask

A two-dimensional array of byte type, and of the same dimensions as IM. The weight of all pixels that are non-zero in BPMASK are set to 0. This way, for example, bad pixels and pixels that are hit by cosmic rays are given no weight.

Note: If this mask is specified then the eliminate_crays option of the modified optimal extraction is always unset.

obpmaskA two-dimensional byte image of the same dimensions as OUT. Each element in this image contains the number of masked pixels in the bad-pixels mask that were used to calculate the extracted image. This array is only calculated if BPMASK is set.
satlimitA scalar integer that specifies the saturation limit that is used to define the value of the pixels in the saturation mask (SATMASK) [ADU]. If any of the pixel values that are included across the center part of the profile is higher than this limit, then the output element is masked.
satmaskA two-dimensional output byte array, which indicates spectrum elements that involved saturated raw-data pixels. This array is only calculated if SATLIMIT is set.
userparfileA scalar string specifying the name of an optional user-parameter file, that could contain any of the keywords that are described in the routine description.
skipwThis keyword can be set to a one-dimensional array with as many elements as there are wavelength bins. If it is set then no spectrum is calculated for bins j where skipw[j]==1. This is a useful option with multi-extension data where there are empty bins between the detectors.
rimageA two-dimensional array of the same dimensions as IM, with the unprocessed version of IM. This array is used to calculate the saturated-pixels image that is available in SATMASK. This array is only considered if SATLIMIT is set.
stawidIf set, then various messages are written to the p3d GUI status line (this must be the widget id of that label widget).
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

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:
outA two-dimensional array of the extracted spectra with the same dimensions as the first two dimensions of LPROFS.
doutA two-dimensional array of the extracted spectra with the same dimensions as OUT. This is the error of OUT. DOUT is onlyt present if ECALC is set.

routines/p3d_extract_optimal_mpd.pro, line 236, last changed at 2016-06-30 by christersandin (revision 4257)

p3d_extract_optimal_mpd, im, dim, lprofs, out, dout, detsec=, rdnoise=, proffun=, nextensions=, /rawdataarecombined, /ecalc, bpmask=, obpmask=, satlimit=, satmask=, nthreads=, userparfile=, skip=, rimage=, stawid=, topwid=, logunit=, verbose=, error=, /debug, /cdebug, /help

This routine extracts spectra from a two-dimensional spectrum image using the multi-profile deconvolution approach of Sharp & Birchall 2010, PASA, 27, 91.

The spectra are extracted using (pre-calculated) input profiles (over the cross-dispersion axis) to sum up the flux at every wavelength bin. The input image is turned into an extracted spectrum image, where every spectrum is placed in an individual row.

Depending on the number of neighbor profiles that are fitted a diffe- rent method is used to minimize the residual to find the intensities. If only one neighbor profile is used on either side of the reference profile then a tri-diagonal system of equations can be solved. If the number (MPDNPROF) is larger than 1 then it is possible to use either:

  • A band-diagonal sparse matrix solver (MPDMETHOD='band-diagonal')

  • Or solving by singular value decomposition (SVD, MPDMETHOD='svd'; see Numerical Recipes, 2nd ed., Sect. 2.6).

Note: This method has not yet been optimized for sparse arrays and is therefore extremely slow.

If either one of these latter two methods is used then the maximum number of iterations is MPDITMAX. If the SVD-method is used then all singular values which are smaller than MPDSVDLIM are set to 0 before calculating the intensities.

The following parameters are read from the user-parameter file:

mpdnprof [1]

A scalar integer specifying the number of neigbor profiles that are used on each side of the current profile. A tri-diagonal solver can only be used if this value is equal to 1.

mpdmethod ['band-diagonal']

A scalar string specifying the solver to use with this method. The default is a band-diagonal solver (that is more stable than the built-in function TRISOL for tri-diagonal systems). This value can be set to: 'band-diagonal', 'tri-diagonal', or 'svd'. Where SVD is the singular value decomposition method.

mpdthreshold [1d-10]

A scalar decimal value that is used with the band-diagonal solution method. As the IDL manual page for SPRSIN tells this keyword sets the criterion for deciding the absolute magnitude of the elements to be retained in sparse storage mode.

mpdtolerance [1d-10]

A scalar decimal value that is used with the band-diagonal solution method. As the IDL manual page for LINBCG tells this keyword specifies the desired convergence tolerance.

mpdsvdlim [1d-10]

A scalar decimal value that is used with the singular value decomposition. All singular values that are smaller than this value are set to 0.

mpditmax [20]

A scalar integer that is used with the singular value decomposition. As the IDL manual page for SVDC tells this keyword specifies the maximum number of iterations.

pmultfac [10]

A scalar integer specifying a subsampling factor that is used when calculating the profile.

Input parameters:
imA two-dimensional array, that holds the spectra that will be extracted here. The dispersion axis must be the x-axis.
dimA two-dimensional array of the same dimensions as IM, with the errors of IM. DIM must be present. The variance of IM is DIM².
lprofsA three-dimensional array, that for every spectrum bin, of every spectrum, holds the fitting parameters of a cross-dispersion profile. The default value is: sp=size(lprofs)
Keyword parameters:
detsecA four-element (columns) -by- number of blocks (rows) integer array that specifies the detector region to use on the CCD for each block. RDNOISE must have as many elements as DETSEC has rows.
rdnoiseA decimal scalar or decimal array that specifies the readout noise [ADU]. RDNOISE must have as many elements as DETSEC has rows.
proffunA scalar string with the name of the function to use when (re-)calculating the line profile.
nextensionsA scalar integer indicating the number of data extensions in the input raw data file. The default value is: 0
rawdataarecombinedWhen 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
ecalcIf this keyword is set then output errors are calculated.
bpmaskAn two-dimensional array of byte type, and of the same dimensions as IM. The weight of all pixels that are non-zero in BPMASK are set to 0. This way, for example, bad pixels and pixels that are hit by cosmic rays are given no weight.
obpmaskA two-dimensional byte image of the same dimensions as OUT. Each element in this image contains the number of masked pixels in the bad-pixels mask that were used to calculate the extracted image. This array is only calculated if BPMASK is set.
satlimitA scalar integer that specifies the saturation limit that is used to define the value of the pixels in the saturation mask (SATMASK) [ADU]. If any of the pixel values that are included across the center part of the profile is higher than this limit, then the output element is masked.
satmaskA two-dimensional output byte array, which indicates spectrum elements that involved saturated raw-data pixels. This array is only calculated if SATLIMIT is set.
nthreadsA scalar integer that specifies how many threads to use in the parallelized spectrum extraction.
userparfileA scalar string specifying the name of an optional user-parameter file, that could contain any of the keywords that are described in the routine description.
skipwThis keyword can be set to a one-dimensional array with as many elements as there are wavelength bins. If it is set then no spectrum is calculated for bins j where skipw[j]==1. This is a useful option with multi-extension data where there are empty bins between the detectors.
rimageA two-dimensional array of the same dimensions as IM, with the unprocessed version of IM. This array is used to calculate the saturated-pixels image that is available in SATMASK. This array is only considered if SATLIMIT is set.
stawidIf set, then various messages are written to the p3d GUI status line (this must be the widget id of that label widget).
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

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:
outA two-dimensional array of the extracted spectra with the same dimensions as the first two dimensions of LPROFS.
doutA two-dimensional array of the extracted spectra with the same dimensions as OUT. This is the error of OUT. DOUT is onlyt present if ECALC is set.

routines/p3d_extract_prepare_extraction.pro, line 194, last changed at 2016-09-10 by christersandin (revision 4383)

p3d_extract_prepare_extraction, extractfile, tracefile, trace, object, mbias, bsw, kwrdlist=, crmaskfile=, bpmaskfile=, bpmaskdata=, userparfile=, xbin=, ybin=, masterbias=, /poscanonly, parfile=, xsize=, ysize=, x0=, y0=, /blocksarecombined, /rawdataarecombined, prescanx=, prescany=, overscanx=, overscany=, daxis=, detector=, topwid=, logunit=, verbose=, error=, /debug, /help

This routine loads science-object image, a bad-pixel mask image, a trace-mask image, and a master-bias image. The data are checked for consistency in terms of array sizes and used binning parameters. In a second step, all data are trimmed of prescan and overscan regions using the DETSEC keyword.

The data are returned as is (i.e. no transposing).

Input parameters:
extractfileThe input raw data image that is to be treated.
tracefileA corresponding input file for tracing.
Keyword parameters:
kwrdlistA two-dimensional string array holding the instrument-specific keywords for a defined set of keywords which are used to determine the ROI on the CCD. KWRDLIST must have two columns.
crmaskfileThe filename of an, optional, cosmic-ray hit mask file. If this keyword is used the argument must be different from an empty string to use the keyword. If this keyword is at all present, then if the filename that is contained in CRMASKFILE does not exist, then an attempt is made to read the mask from the (EXTNAME=)'MASK' extension in EXTRACTFILE.
bpmaskfileThe filename of an, optional, bad-pixel mask file.
bpmaskdataReturns a bad-pixel mask image that is the ORed version of the input images of CRMASKFILE and BPMASKFILE, where prescan and overscan regions, if any, have been removed (only present if BPMASKFILE is set).
userparfileA scalar string specifying the name of an optional user-parameter file, that could contain the keyword 'detsec'. If it does then the value of that keyword is used to trim the data. If there are several 'detsec'-lines in the file then only the first is used.
xbinThe CCD binning number; x-direction.
ybinThe CCD binning number; y-direction.
masterbiasThe data of MASTERBIAS will be used as bias data.
poscanonlyThe trace-mask image is not considered if this keyword is set. This is useful if the only required output are the prescan and the overscan arrays.
parfileA string specifying the filename of an existing file containing instrument-specific parameters.
xsizeUpon return, this value is set to the x-size of the extracted data.
ysizeUpon return, this value is set to the y-size of the extracted data.
x0Upon return, this value is set to the x-offset of the extracted data.
y0Upon return, this value is set to the y-offset of the extracted data.
blocksarecombinedIf this keyword is set, the prescan and overscan gions are assumed to have been removed from the put data already.
rawdataarecombinedWhen this keyword is set, raw data of separate cks are read from separate files, which are then bined into one image.
prescanxThis keyword is used with multi-block instruments that do not use the 'blocksarecombined' instrument parameter, as well as all single block instruments. For each block this keyword contains the x axis prescan array (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). The tag contains the scalar integer -1 when there is no x-axis prescan.
prescanyThis keyword is used with multi-block instruments that do not use the 'blocksarecombined' instrument parameter, as well as all single block instruments. For each block this keyword contains the y axis prescan array (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). The tag contains the scalar integer -1 when there is no y-axis prescan.
overscanxThis keyword is used with single-block instruments. It contains the x axis overscan array (as tag 'd1'). The array has as many elements as the data have rows (on the y axis). The tag contains the scalar integer -1 when there is no x-axis overscan.
overscanyThis keyword is used with single-block instruments. It contains the y axis overscan array (as tag 'd1'). The array has as many elements as the data have columns (on the x axis). The tag contains the scalar integer -1 when there is no y-axis overscan.
daxisSpecifies the dispersion dimension in the input images (EXTRACTFILE, TRACEFILE, MASTERBIAS). The default value is: 1
detectorA scalar integer that specifies the currently selected detector; DETECTOR is a zero-based value. This value is passed on to p3d_misc_detsec.
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:
traceReturns the trace mask data array where prescan and overscan regions, if any, have been removed.
objectReturns the science-object image where prescan and overscan regions, if any, have been removed.
mbiasIf MASTERBIAS is set then this variable returns the master-bias image where prescan and overscan regions, if any, have been removed.
bswn/a.

routines/p3d_extract_tophat.pro, line 157, last changed at 2016-06-30 by christersandin (revision 4258)

p3d_extract_tophat, image, traces, out, dout, dimage=, bpmask=, obpmask=, satlimit=, satmask=, profwidth=, variable_profwidth=, skipw=, rimage=, stawid=, topwid=, logunit=, verbose=, error=, /debug, /help

This routine provides a simple spectrum extraction algorithm. Using the input image an extracted spectrum image is calculated, where each spectrum is placed in an individual row.

The spectra are extracted from the input image by summing up the flux in each wavelength bin over an interval of the width 2 * PROFWIDTH + 1 in the cross-dispersion direction. The input trace mask is used to find the spectra.

Input parameters:
imageA two-dimensional array.
tracesA two-dimensional array, which for every spectrum bin provides the y-position of every spectrum line on the raw data CCD image.
Keyword parameters:
dimageA two-dimensional array of the same dimensions as IMAGE, with the errors of IMAGE. If this keyword is present then an output error image, DOUT, is calculated.
bpmaskA two-dimensional array of byte type, and of the same dimensions as IMAGE. This array is used to calculate an output bad-pixels mask that is returned in OBPMASK.
obpmaskA two-dimensional byte image of the same dimensions as OUT. Each element in this image contains the number of masked pixels in the bad-pixels mask that were used to calculate the extracted image. This array is only calculated if BPMASK is set.
satlimitA scalar integer that specifies the saturation limit that is used to set each element in the saturation mask (SATMASK) [ADU].
satmaskA two-dimensional output byte array, which indicates spectrum elements that involved saturated raw-data pixels. This array is only calculated if SATLIMIT is set.
profwidth2 * PROFWIDTH + 1 is the total width of the interval where the flux is integrated; only used when VARIABLE_PROFWIDTH == 0.
variable_profwidthWhen this keyword is set the spectrum width, for every spectrum bin, in the cross-dispersion direction is estimated to be half the separation between any two separated spectra. The default value is: 0
skipwThis keyword can be set to a one-dimensional array with as many elements as there are wavelength bins. If it is set, no spectrum is calculated for bins //j// where skipw[j] == 1. This is a useful option with multi-extension data where there are empty bins between the detectors.
rimageA two-dimensional array of the same dimensions as IMAGE, with the unprocessed version of IMAGE. This array is used to calculate the saturated-pixels image that is available in SATMASK. This array is only considered if SATLIMIT is set.
stawidIf set, various messages are written to the p3d GUI status line (this must be the widget id of that label widget).
topwidIf set, error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
outA two-dimensional array of the extracted spectra with the same dimensions as TRACES.

page last updated on: Friday April 21, 2017 13:31:40; retrieved on: Friday May 26, 2017 07:23:14