pypeit.core.trace module

Module with generalized tracing routines.

Routines are primarily used for tracing slit edges.

TODO: Add object and wavelength tracing routines here?

TODO: Is there a way that we could define this link so that it’s accessible by the docstring of all modules?

pypeit.core.trace.atleast_one_edge(edge_img, bpm=None, flux_valid=True, buffer=0, copy=False)[source]

Ensure that there is at least one left and one right slit edge identified.

This is especially useful for long slits that fill the full detector, e.g. Shane Kast.

Parameters:

edge_img (numpy.ndarray) – Image with edge trace pixels numbered by their associated trace. Pixels with positive numbers follow right slit edges and negative numbers follow left slit edges.
bpm (numpy.ndarray, optional) – Integer (0 unmasked; 1 masked) or boolean array indicating bad pixels in the image. If None, all pixels are considered good.
flux_valid (bool, optional) – The flux in the image used to construct the edge traces is valid meaning that any problems should not be an issue with the trace image itself.
buffer (int, optional) – If adding an edge, this is the minimum number of pixels near the detector edge at which to place the edge.
copy (bool, optional) – Copy edge_img to a new array before making any modifications. Otherwise, edge_img is modified in-place.

Returns:

The modified trace image, which is either a new array or points to the in-place modification of edge_img according to the value of copy. If no slit edges were found and the flux in the trace image is invalid (flux_valid=False), function returns None.

Return type:

numpy.ndarray

pypeit.core.trace.build_trace_bpm(flux, trace_cen, bpm=None, boxcar=None, thresh=None, median_kernel=None)[source]

Construct a bad-pixel mask for edge trace data.

If no keyword arguments are provided, the traces are only masked when they land outside the bounds of the image.

If both boxcar and thresh are provided, traces are also masked by extracting the provided image along the trace (see pypeit.core.moment.moment1d()) and flagging extracted values below the provided threshold.

Parameters:

flux (numpy.ndarray) – Image to use for tracing. Shape is expected to be (nspec, nspat).
trace_cen (numpy.ndarray) – Trace locations. Can be a 1D array for a single trace or a 2D array with shape (nspec, ntrace) for multiple traces.
bpm (numpy.ndarray, optional) – Boolean array with the input bad-pixel mask for the image. If not provided, all values in flux are considered valid. If provided, must have the same shape as flux.
boxcar (float, optional) – The width of the extraction window used for all traces and spectral rows. If None, the trace mask will not consider the extracted flux.
thresh (float, optional) – The minimum valid value of the extraced flux used to mask the traces. If None, the trace mask will not consider the extracted flux.
median_kernel (int, optional) – The spectral width of the kernel to use with scipy.signal.medfilt to filter the extracted data before setting the trace mask based on the provided threshold. If None, the extracted data are not filtered before flagging data below the threshold.

Returns:

The boolean mask for the traces.

Return type:

numpy.ndarray

pypeit.core.trace.count_edge_traces(edge_img)[source]

Count the number of left and right edges traced.

Parameters:: edge_img (numpy.ndarray) – Image with edge trace pixels numbered by their associated trace. Pixels with positive numbers follow right slit edges and negative numbers follow left slit edges.
Returns:: Two integers with the number of left and right edges, respectively. Or 0 if the minimum input value is 0
Return type:: int or tuple

pypeit.core.trace.detect_slit_edges(flux, bpm=None, median_iterations=0, min_sqm=30.0, sobel_mode='nearest', sobel_enhance=0, sigdetect=30.0, grow_bpm=5)[source]

Find slit edges using the input image.

The primary algorithm is to run a Sobel filter on the image and then trigger on all significant gradients. Positive gradients are left edges, negative gradients are right edges.

Parameters:

flux (numpy.ndarray) – Calibration frame used to identify slit edges. Likely a flat-field image that has been lightly smoothed in the spectral direction. The image should also have its bad pixels replaced (see pypeit.core.procimg.replace_columns()). The image must follow the pypeit convention, with shape \((N_{\rm spec}, N_{\rm spat})\).
bpm (numpy.ndarray, optional) – A boolean or integer bad-pixel mask. If None, all pixels are assumed valid. This is used to ignore features in the image that may be due to bad pixels.
median_iterations (int, optional) – Number of median smoothing iteration to perform on the trace image. The size of the smoothing is always (7,3). For long-slit data, we recommend median_iterations=0.
min_sqm (float, optional) – Minimum error used when detecting a slit edge. TODO: This needs a better description.
sobel_mode (str, optional) – Mode to use with the Sobel filter. See scipy.ndimage.sobel.
sobel_enhance (int, optional) – If slit edges are not well-defined (e.g. blurred) set this parameter to a number greater than zero to enhance the edge detection.
sigdetect (float, optional) – Threshold for edge detection.
grow_bpm (int, optional) – The sobel_sig and edg_img are masked using the bpm. This is done by convolving the bpm with a spatial boxcar of width grow_bpm pixels, ensuring that pixels which touched bad pixels are also masked.

Returns:

Returns two numpy.ndarray objects – (1) The image of the: significance of the edge detection in sigma and (2) the array isolating the slit edges. In the latter, left edges have a value of -1 and right edges have a value of 1.

Return type:

tuple

pypeit.core.trace.extrapolate_orders(cen, width_fit, gap_fit, min_spat, max_spat, tol=0.01)[source]

Predict the locations of additional orders by extrapolation.

Order centers are only predicted for those that fall between a minimum and maximum spatial pixel value (see min_spat and max_spat).

The models of the order width and gap are defined such that the location of the orders are \(c_{i+1} = c_i + w_i + g_i\). Extrapolation toward larger spatial positions is, therefore, trivial. Toward smaller pixels, \(c_i\) is unknown and the width and gap models are not required to be linear; we use a simple minimiation algorithm to optimize the extrapolated values so that the order location model is accurate (see tol).

Parameters:

cen (numpy.ndarray) – The spatial pixel positions of the orders traced.
width_fit (PypeItFit) – Model of the order width as a function of the order center.
gap_fit (PypeItFit) – Model of the order gap after each order as a function of the order center.
min_spat (float) – The minimum spatial pixel for the extrapolation range.
max_spat (float) – The maximum spatial pixel for the extrapolation range.
tol (float, optional) – Tolerance used when optimizing the order locations predicted toward lower spatial pixels.

Returns:

Two arrays with orders centers (1) below the first and (2) above the last measured center. One or both of the arrays can be empty if extrapolation leads to no orders outside the specified minimum and maximum spatial range (min_spat, max_spat).

Return type:

tuple

pypeit.core.trace.find_missing_orders(cen, width_fit, gap_fit, tol=0.2)[source]

Using simple models for the order width and order gap as a function of spatial position, identify orders missed by the automated tracing.

Parameters:

cen (numpy.ndarray) – The spatial pixel positions of the orders traced.
width_fit (PypeItFit) – Model of the order width as a function of the order center.
gap_fit (PypeItFit) – Model of the order gap after each order as a function of the order center.
tol (float, optional) – Fraction of the order width used as the tolerance to identify missed orders.

Returns:

Two arrays providing (1) the centers of all slit orders and (2) a boolean array selecting orders that were missed by the tracing algorithm.

Return type:

tuple

pypeit.core.trace.fit_trace(flux, trace_cen, order, ivar=None, bpm=None, trace_bpm=None, weighting='uniform', fwhm=3.0, maxshift=None, maxerror=None, function='legendre', maxdev=2.0, maxiter=25, niter=9, bitmask=None, debug=False, idx=None, xmin=None, xmax=None, flavor='trace')[source]

Iteratively fit the trace of a feature in the provided image.

Each iteration performs two steps:

Remeasure the trace centroid using masked_centroid(). The size of the integration window (see the definition of the width parameter for pypeit.core.moment.moment1d()) depends on the type of weighting: For uniform weighting, the code does a third of the iterations with width = 2*1.3*fwhm, a third with width = 2*1.1*fhwm, and a third with width = 2*fwhm. For Gaussian weighting, all iterations use width = fwhm/2.3548.

Fit the centroid measurements with a 1D function of the provided order. See pypeit.core.pydl.TraceSet().

The number of iterations performed is set by the keyword argument niter. There is no convergence test, meaning that this number of iterations is always performed.

Notes

Revision History:

23-June-2018 Written by J. Hennawi

Parameters:

flux (numpy.ndarray) – Image to use for tracing. Must be 2D with shape (nspec, nspat).
trace_cen (numpy.ndarray) – Initial guesses for trace centroids in the spatial dimension. This can either be an 2-d array with shape (nspec, nTrace) array, or a 1-d array with shape (nspec) for the case of a single trace.
order (int) – Order of function to fit to each trace. See function.
ivar (numpy.ndarray, optional) – Inverse variance of the image intensity. If not provided, unity variance is used. If provided, must have the same shape as flux.
bpm (numpy.ndarray, optional) – Boolean array with the input bad-pixel mask for the image (pixels to ignore are True). If not provided, all values in flux are considered valid. If provided, must have the same shape as flux.
trace_bpm (numpy.ndarray, optional) – Boolean array with the trace bad-pixel mask; i.e., places where you know the trace is going to be bad that you always want to mask in the fits. Shape must match trace_cen.
weighting (str, optional) – The weighting to apply to the position within each integration window (see options in pypeit.core.moment.moment1d()).
fwhm (float, optional) – The expected width of the feature to trace, which is used to define the size of the integration window during the centroid calculation; see description above.
maxshift (float, optional) – Maximum shift allowed between the input and recalculated centroid (see masked_centroid()). If None, no limit is applied.
maxerror (float, optional) – Maximum error allowed in the calculated centroid (see masked_centroid()). Measurements with errors larger than this value are returned as the input center value. If None, no limit is applied.
function (str, optional) – The name of the function to fit. Must be a valid selection. See :class`pypeit.core.pydl.TraceSet`.
maxdev (float, optional) – If provided, reject points with abs(data-model) > maxdev during the fitting. If None, no points are rejected. See robust_fit().
maxiter (int, optional) – Maximum number of rejection iterations allowed during the fitting. See robust_fit().
niter (int, optional) – The number of iterations for this method; i.e., the number of times the two-step fitting algorithm described above is performed.
bitmask (pypeit.bitmask.BitMask, optional) – Object used to toggle the returned bit masks in edge centroid measurements; see masked_centroid().
debug (bool, optional) – Plot the data and the fits.
idx (numpy.ndarray, optional) – Array of strings with the IDs for each object. Used only if debug is true for the plotting. Default is just a running number.
xmin (float, optional) – Lower reference for robust_fit polynomial fitting. Default is to use zero
xmax (float, optional) – Upper reference for robust_fit polynomial fitting. Default is to use the image size in nspec direction
flavor (str, optional) – Defines the type of fit performed. Only used by QA

Returns:

Returns four numpy.ndarray objects all with the same shape as the input positions (trace_cen) and provide:

The best-fitting positions of each trace determined by the polynomial fit.

The centroids of the trace determined by either flux- or Gaussian-weighting, to which the polynomial is fit.

The errors in the centroids.

Boolean flags for each centroid measurement (see moment1d()).

Return type:

tuple

pypeit.core.trace.follow_centroid(flux, start_row, start_cen, ivar=None, bpm=None, fwgt=None, width=6.0, maxshift_start=0.5, maxshift_follow=0.15, maxerror=0.2, continuous=True, bitmask=None)[source]

Follow the centroid of features in an image along the first axis.

In the normal pypeit usage, this follows the spatial position (column) of a feature in the image as a function of spectral position (row).

Starting from a specified row and input centers along each column, attempt to follow a set of features to both lower and higher rows in the provided image.

Importantly, this function does not treat each row independently (as would be the case for a direct call to masked_centroid() for centroid positions along all rows), but treats the calculation of the centroids sequentially where the result for each row is dependent on and starts from the result from the previous row. The only independent measurement is the one performed at the input start_row. This function is much slower than masked_centroid() because of this introduced dependency.

Note

This is an adaptation of trace_crude from idlspec2d.
You should consider smoothing the input flux array before passing it to this function. See pypeit.utils.boxcar_smooth_rows(). For example:
```
smimg = utils.boxcar_smooth_rows(img, nave, wgt=inmask)
cen, cene, cenm = trace.follow_centroid(smimg, ...)
```

Parameters:

flux (numpy.ndarray) – Image used to weight the column coordinates when recentering. For example, when tracing slit edges, this should typically be the Sobel-filtered trace image after adjusting for the correct side and performing any smoothing; see prepare_sobel_for_trace(). In any case, consider that this image may need to be smoothed for robust output from this function. See pypeit.utils.boxcar_smooth_rows().
start_row (int) – Row at which to start the calculation. The function begins with this row and then continues first to higher indices and then to lower indices.
start_cen (int, numpy.ndarray, optional) – One or more coordinates to recenter. If an array, must be 1D.
ivar (numpy.ndarray, optional) – Inverse variance in the image. If not provided, unity variance is assumed. Used for the calculation of the errors in the moment analysis. If this is not provided, be careful with the value set for maxerror (see below).
bpm (numpy.ndarray, optional) – A boolean bad-pixel mask used to ignore pixels in the image (bad pixels are True).
fwgt (numpy.ndarray, optional) – An additional weight to apply to each pixel in flux. If None, weights are uniform.
width (float, numpy.ndarray, optional) – The size of the window about the provided starting center for the moment integration window. See pypeit.core.moment.moment1d().
maxshift_start (float, optional) – Maximum shift in pixels allowed for the adjustment of the first row analyzed.
maxshift_follow (float, optional) – Maximum shift in pixels between centroids in adjacent rows as the routine follows the feature away from the first row analyzed.
maxerror (float, optional) – Maximum allowed error in the centroid returned by pypeit.core.moment.moment1d().
continuous (bool, optional) – Keep only the continuous part of the feature trace from the starting row.
bitmask (pypeit.bitmask.BitMask, optional) – Object used to flag the feature traces. If None, assessments use a boolean array to flag traces. If not None, errors will be raised if the object cannot interpret the correct flag names defined. This function uses the DISCONTINUOUS flag.

Returns:

Three numpy arrays are returned. the optimized center, an: estimate of the error, and a bad-pixel mask (masked values are True).

Return type:

tuple

pypeit.core.trace.handle_orphan_edges(edge_img, sobel_sig, bpm=None, flux_valid=True, buffer=0, copy=False)[source]

In the case of single left/right traces and multiple matching traces, pick the most significant matching trace and remove the others.

If no left and/or right edge is present, this will add one using atleast_one_edge().

Parameters:

edge_img (numpy.ndarray) – Image with edge trace pixels numbered by their associated trace. Pixels with positive numbers follow right slit edges and negative numbers follow left slit edges.
sobel_sig (numpy.ndarray) – Image with the significance of the edge detection. See detect_slit_edges().
bpm (numpy.ndarray, optional) – Integer (0 unmasked; 1 masked) or boolean array indicating bad pixels in the image. If None, all pixels are considered good.
flux_valid (bool, optional) – The flux in the image used to construct the edge traces is valid meaning that any problems should not be an issue with the trace image itself.
buffer (int, optional) – If adding an edge, this is the minimum number of pixels near the detector edge at which to place the edge; see atleast_one_edge().
copy (bool, optional) – Copy edge_img to a new array before making any modifications. Otherwise, edge_img is modified in-place.

Returns:

The modified trace image, which is either a new array or points to the in-place modification of edge_img according to the value of copy.

Return type:

numpy.ndarray

pypeit.core.trace.identify_traces(edge_img, max_spatial_separation=4, follow_span=10, minimum_spec_length=50)[source]

Follow slit edges to identify unique slit traces.

Parameters:

edge_img (numpy.ndarray) – An array marked with -1 for left slit edges and +1 for right slit edges and 0 everywhere else. The image must follow the pypeit convention, with shape \((N_{\rm spec},N_{\rm spat})\). See detect_slit_edges().
max_spatial_separation (int, optional) – The maximum spatial separation between two edges in proximal spectral rows before they become separated into different slit traces.
follow_span (int, optional) – The number of previous spectral rows to consider when following slits forward.
minimum_spec_length (int, optional) – The minimum number of spectral rows in an edge trace. Traces that do not meet this criterion are ignored.

Returns:

An integer array with trace ID numbers at pixels locating the edge of that trace. Negative traces are for left edges, positive for right edges. The number of left and right traces can be determined using count_edge_traces(). Pixels not associated to any edge have a value of 0.

Return type:

numpy.ndarray

pypeit.core.trace.masked_centroid(flux, cen, width, ivar=None, bpm=None, fwgt=None, row=None, weighting='uniform', maxshift=None, maxerror=None, bitmask=None, fill='input', fill_error=-1)[source]

Measure the centroid within 1D apertures and flag and fill bad results.

This is primarily a wrapper for pypeit.core.moment.moment1d() that flags the output.

Data are flagged for the following reasons:

The centroids must always be within the aperture used by pypeit.core.moment.moment1d() (OUTSIDEAPERTURE).
The centroid cannot be within half an aperture of the image edge (EDGEBUFFER).
If maxerror is not None, the centroid error must be below the provided maximum (MOMENTERROR).
If maxshift is not None, the centroid must be different from the input value by less than the maximum (LARGESHIFT).

The flags are provided as either a boolean array or an array of mask bits, depending on the value of bitmask (see below). The bitmask flags used for each criteria are given in the list above. If fill is ‘input’, the output centroids are replaced by the input value for any measurements captured by these flags. For centroids above maxshift, however, the replacement value can be at the maximum shift if fill=’bound’.

Parameters:

flux (numpy.ndarray) – Array used for the centroid calculations.
cen (numpy.ndarray) – Current estimate of the trace center.
width (float) – Passed directly to pypeit.core.moment.moment1d(); see the documentation there.
ivar (numpy.ndarray, optional) – Inverse variance in flux; passed directly to pypeit.core.moment.moment1d().
bpm (numpy.ndarray, optional) – Boolean bad-pixel mask for flux; passed directly to pypeit.core.moment.moment1d().
fwgt (numpy.ndarray, optional) – A weight to apply to each pixel in flux; passed directly to pypeit.core.moment.moment1d().
row (int, optional) – Row (index along the first axis; spectral position) in flux at which to recenter the trace position. See row in pypeit.core.moment.moment1d().
weighting (str, optional) – Passed directly to pypeit.core.moment.moment1d(); see the documentation there.
maxshift (float, optional) – Maximum shift allowed between the input and recalculated centroid. If None, no limit is applied.
maxerror (float, optional) – Maximum error allowed in the calculated centroid. Measurements with errors larger than this value are returned as the input center value. If None, no limit is applied.
bitmask (pypeit.bitmask.BitMask, optional) – Object used to toggle the returned bit masks. If provided, must be able to interpret MATHERROR, OUTSIDEAPERTURE, EDGEBUFFER, MOMENTERROR, and LARGESHIFT flags. If None, the function returns boolean flags set to True if there was an error in pypeit.core.moment.moment1d() or if the error is larger than maxerror (and maxerror is not None); centroids that have been altered by the maximum shift are not flagged.
fill (str, optional) –
A string keyword specifying how flagged centroids should be replaced. Options are:
- ’input’: Replace the flagged centroids with their input value.
- ’bound’: Only for the case where the centroid is outside the provided maxshift, replace the centroid by the value at either the positive or negative boundary edge. In all other cases, the centroid is still replaced with the input value. See replacement cases above.
fill_error (float, optional) – For flagged centroids, this error is replaced with this dummy value.

Returns:

Returns three numpy.ndarray objects. the new centers, the: center errors, and the measurement flags with a data type depending on bitmask.

Return type:

tuple

pypeit.core.trace.most_common_trace_row(trace_bpm, valid_frac=0.3333333333333333)[source]

Find the spectral position (row) that crosses the most traces.

If provided the mask for a single trace, this just returns the median of the unmasked rows.

Parameters:

trace_bpm (numpy.ndarray) – Bad-pixel mask for the trace data (True is bad; False is good). Can be a 1D array for a single trace or a 2D array with shape (nspec, ntrace) for multiple traces.
valid_frac (float, optional) – The valid fraction of the detector from which to choose the row. For example, if 1/3, only choose the row from the central third of the rows.

Returns:

The row that crosses the most valid trace data.

Return type:

int

pypeit.core.trace.parse_user_slits(add_slits, this_det, rm=False)[source]

Parse the parset syntax for adding or removing slits

Parameters:

add_slits (str, list) – Taken from the parset
this_det (int) – current detector
rm (bool, optional) – Remove instead of add?

Returns:

if list, [[x0,x1,yrow]] for add (rm=False) with one or more entries if list, [[xcen,yrow]] for rm=True with one or more entries

Return type:

list or None

pypeit.core.trace.peak_trace(flux, ivar=None, bpm=None, trace_map=None, extract_width=None, smash_range=None, peak_thresh=100.0, peak_clip=None, trough=False, trace_median_frac=0.01, trace_thresh=10.0, fwhm_uniform=3.0, fwhm_gaussian=3.0, maxshift=None, maxerror=None, function='legendre', order=5, maxdev=5.0, maxiter=25, niter_uniform=9, niter_gaussian=6, bitmask=None, debug=False)[source]

Find and trace features in an image by identifying peaks/troughs after collapsing along the spectral axis.

The image is either compressed directly or after rectification using the supplied trace_map. The provided trace data must have the same shape as the input flux image and map each spatial position as a function of spectral position. This can be the output of pca_predict() where the provided coordinates are np.arange(flux.shape[1]); see also predict(). The rectification of the input flux data is done using a boxcar extraction along the provided traces with a width of extract_width; see moment1d().

The (rectified) image is collapsed spectrally (see smash_range) giving the sigma-clipped mean flux as a function of spatial position. Peaks are then isolated in this vector (see detect_lines()).

Traces that pass through these peak positions are then passed to two iterations of fit_trace(), which both remeasures the centroids of the trace and fits a polynomial to those trace data. The first iteration determines the centroids with uniform weighting, passing fwhm=fwhm_uniform to fit_trace(), and the second uses Gaussian weighting for the centroid measurements (passing fwhm=fwhm_gaussian to fit_trace()). The results of this second iteration of fit_trace() are the data returned.

Troughs in the image can also be traced, which is done by flipping the sign of the image about its median and then repeating the “peak” finding and fit_trace() iterations. If troughs are fit, the traces are ordered with the set of peak traces first (the number of which is given by the last returned object of the function), followed by the trough traces.

Parameters:

flux (numpy.ndarray) – Image to use for tracing.
ivar (numpy.ndarray, optional) – Inverse variance of the image intensity. If not provided, unity variance is used. If provided, must have the same shape as flux.
bpm (numpy.ndarray, optional) – Boolean array with the input bad-pixel mask for the image. If not provided, all values in flux are considered valid. If provided, must have the same shape as flux.
trace_map (numpy.ndarray, optional) – Trace data that maps the spatial position of all spectra as a function of spectral row. For example, this can be the output of pca_predict() where the provided coordinates are np.arange(flux.shape[1]); see also predict(). This is used to rectify the input image so that spectra are identically organized along image rows (i.e., to select the i``th spectrum, one would slice with ``[:,i]). Shape must be identical to flux. If None, flux is assumed to be rectified on input.
extract_width (float, optional) – The width of the extract aperture to use when rectifying the flux image. If None, set to fwhm_gaussian.
smash_range (tuple, optional) – Spectral range over which to collapse the input image into the 1D flux as a function of spatial position. This 1D vector is used to detect features for tracing. This is useful (and recommended) for defining the relevant detector range for data with spectra that do not span the length of the detector. The tuple gives the minimum and maximum in the fraction of the full spectral length (nspec). If None, the full image is collapsed.
peak_thresh (float, optional) – The threshold for detecting peaks in the image. See the input_thresh parameter for detect_lines().
peak_clip (float, optional) – Sigma-clipping threshold used to clip peaks with small values; no large values are clipped. If None, no clipping is performed. Generally, if the peak detection algorithm is finding insignificant peaks, one should instead raise the value of peak_thresh.
trough (bool, optional) – Trace both peaks and troughs in the input image. This is done by flipping the value of the smashed image about its median value, such that troughs can be identified as peaks.
trace_median_frac (float, optional) – After rectification of the image and before refitting the traces, the rectified image is median filtered with a kernel width of trace_median_frac*nspec along the spectral dimension.
trace_thresh (float, optional) – After rectification and median filtering of the image (see trace_median_frac), values in the resulting image that are below this threshold are masked in the refitting of the trace using fit_trace().
fwhm_uniform (float, optional) – The fwhm parameter to use when using uniform weighting in the calls to fit_trace(). See description of the algorithm above.
fwhm_gaussian (float, optional) – The fwhm parameter to use when using Gaussian weighting in the calls to fit_trace(). See description of the algorithm above.
maxshift (float, optional) – Maximum shift allowed between the input and recalculated centroid (see fit_trace()).
maxerror (float, optional) – Maximum error allowed in the calculated centroid (see fit_trace()).
function (str, optional) – The type of polynomial to fit to the trace data. See fit_trace().
order (int, optional) – Order of the polynomial to fit to each trace. See fit_trace().
maxdev (float, optional) – See fit_trace(). If provided, reject points with abs(data-model) > maxdev when fitting the trace. If None, no points are rejected.
maxiter (int, optional) – Maximum number of rejection iterations allowed during the fitting. See fit_trace().
niter_uniform (int, optional) – The number of iterations for fit_trace() when edge measurements are based on uniform weighting. See description above.
niter_gaussian (int, optional) – The number of iterations for fit_trace() when edge measurements are based on Gaussian weighting. See description above.
bitmask (BitMask, optional) – Object used to toggle the returned bit masks in edge centroid measurements; see masked_centroid().
debug (bool, optional) – Show plots useful for debugging.

Returns:

Returns four numpy.ndarray objects and the number of peak traces. The number of peak traces should be used to separate peak from trough traces; if trough is False, this will just be the total number of traces. The four numpy.ndarray objects provide:

The best-fitting positions of each trace determined by the polynomial fit.

The centroids of the trace determined by the Gaussian-weighting iteration, to which the polynomial is fit.

The errors in the Gaussian-weighted centroids.

Boolean flags for each centroid measurement (see moment1d()).

Return type:

tuple

Raises:

ValueError – Raised if the input flux is not two-dimensional or if the shape of ivar, bpm, or trace_map is not identical to flux.

pypeit.core.trace.predicted_center_difference(lower_spat, spat, width_fit, gap_fit)[source]

Return the difference between the predicted and true location of an order center.

This is specifically implemented for extrapolate_orders() and its use of an optimization algorithm to extrapolate the order locations to lower spatial pixel values.

Parameters:

lower_spat (numpy.ndarray) – Optimization parameter. Must be an array with a single element giving the predicted spatial location of the order toward lower spatial pixels compared to the known order (true).
spat (float) – The true spatial location of the known order.
width_fit (PypeItFit) – Model of the order width as a function of the order center.
gap_fit (PypeItFit) – Model of the order gap after each order as a function of the order center.

Returns:

The absolute value of the difference between the prediction and the measure location of the order.

Return type:

float

pypeit.core.trace.prepare_sobel_for_trace(sobel_sig, bpm=None, boxcar=5, side='left')[source]

Prepare the Sobel filtered image for tracing.

This method:

Flips and/or truncates the pixel values based on the edge side to be traced (see side).
Smooths along rows (spatially)

Parameters:

sobel_sig (numpy.ndarray) – Image with the significance of the edge detection; see detect_slit_edges().
bpm (numpy.ndarray, optional) – Boolean bad-pixel mask (bad pixels are True). If None, all pixels are considered good. Must have the same shape as sobel_sig.
boxcar (int, optional) – Boxcar smooth the detection image along rows before recentering the edge centers; see boxcar_smooth_rows(). If less than 1, no smoothing is performed.
side (str, optional) – The side that the image will be used to trace. In the Sobel image, positive values are for left traces, negative for right traces. If 'left', the image is clipped at a minimum value of -0.1. If 'right', the image sign is flipped and then clipped at a minimum of -0.1. If None, the image is not flipped or clipped, only smoothed.

Returns:

The smoothed image.

Return type:

numpy.ndarray