pypeit.core.findobj_skymask module

Methods to find objects

pypeit.core.findobj_skymask.create_skymask(sobjs, thismask, slit_left, slit_righ, box_rad_pix=None, trim_edg=(5, 5), skymask_snr_thresh=1.0)[source]

Creates a sky mask from a SpecObjs using the fwhm of each object and/or the boxcar radius.

Parameters:

  • sobjs (SpecObjs) – Objects for which you would like to create the mask.

  • thismask (numpy.ndarray) – Boolean image selecting pixels that are on the slit. Shape is \((N_{\rm spec}, N_{\rm spat})\).

  • slit_left (numpy.ndarray) – Left boundary of slit/order to be extracted (given as floating point pixels). This a 1-d array with shape \((N_{\rm spec}, 1)\) or \((N_{\rm spec},)\)

  • slit_righ (numpy.ndarray) – Right boundary of slit/order to be extracted (given as floating point pixels). This a 1-d array with shape \((N_{\rm spec}, 1)\) or \((N_{\rm spec},)\)

  • box_rad_pix (float, optional) – If set, the sky mask will be as wide as this radius in pixels.

  • trim_edg (tuple, optional) – A two-tuple of integers or floats used to ignore objects within this many pixels of the left and right slit boundaries, respectively.

  • skymask_snr_thresh (float, optional) – The multiple of the final object finding SNR threshold used to create the sky mask via a Gaussian model of the SNR profile. The (spatial) Gaussian model is determined from the image after collapsing along the spectral dimension.

Returns:

Boolean image with shape \((N_{\rm spec}, N_{\rm spat})\) (same as thismask) indicating which pixels are usable for global sky subtraction (True means the pixel is usable for sky subtraction, False means it should be masked when subtracting sky).

Return type:

numpy.ndarray

pypeit.core.findobj_skymask.ech_cutobj_on_snr(sobjs_align, image: ndarray, ivar: ndarray, slitmask: ndarray, order_vec: ndarray, plate_scale_ord: ndarray, max_snr: float = 2.0, nperorder: int = 2, min_snr: float = 1.0, nabove_min_snr: int = 2, box_radius: float = 2.0, inmask: ndarray | None = None)[source]

Cut down objects based on S/N

This routine:

  • Loops over the objects and perform a quick and dirty extraction to assess S/N.

  • Purge objects with low SNR that don’t show up in enough orders, sort the list of objects with respect to obj_id and orderindx.

  • Loop over objects from highest SNR to lowest SNR. Apply the S/N constraints. Once we hit the maximum number objects requested exit, except keep any hand apertures that were requested.

Parameters:

  • sobjs_align (SpecObj) – Previously found objects

  • image (numpy.ndarray) – (Floating-point) Image to use for object search with shape (nspec, nspat). The first dimension (nspec) is spectral, and second dimension (nspat) is spatial. Note this image can either have the sky background in it, or have already been sky subtracted. Object finding works best on sky-subtracted images. Ideally, object finding is run in another routine, global sky-subtraction performed, and then this code should be run. However, it is also possible to run this code on non-sky-subtracted images.

  • ivar (numpy.ndarray) – Floating-point inverse variance image for the input image. Shape must match image, (nspec, nspat).

  • slitmask (numpy.ndarray) – Integer image indicating the pixels that belong to each order. Pixels that are not on an order have value -1, and those that are on an order have a value equal to the slit number (i.e. 0 to nslits-1 from left to right on the image). Shape must match image, (nspec, nspat).

  • order_vec (numpy.ndarray) – int array of good orders

  • plate_scale_ord (numpy.ndarray) – An array with shape (norders,) providing the plate scale of each order in arcsec/pix,

  • max_snr (float, optional) – For an object to be included in the output object, it must have a max S/N ratio above this value.

  • min_snr (float, optional) – For an object to be included in the output object, it must have a a median S/N ratio above this value for at least nabove_min_snr orders (see below).

  • nabove_min_snr (int, optional) – The required number of orders that an object must have with median SNR greater than min_snr in order to be included in the output object.

  • box_radius (float, optional) – Box_car extraction radius in arcseconds to assign to each detected object and to be used later for boxcar extraction. In this method box_radius is converted into pixels using plate_scale. box_radius is also used for SNR calculation and trimming.

  • inmask (numpy.ndarray, optional) – Good-pixel mask for input image. Must have the same shape as image. If None, all pixels in slitmask with non-negative values are considered good.

Returns:

The final set of objects

Return type:

SpecObjs

pypeit.core.findobj_skymask.ech_fill_in_orders(sobjs: SpecObjs, slit_left: ndarray, slit_righ: ndarray, slit_spat_id: ndarray, order_vec: ndarray, obj_id: ndarray, std_trace: SpecObjs | None = None, show: bool = False)[source]
For objects which were only found on some orders, the standard (or

the slit boundaries) are placed at the appropriate fractional position along the order.

This routine:

  • Assigns each specobj a fractional order position and an obj_id number.

  • Fills in missing objects. Fit the fraction slit position of the good orders where an object was found and use that fit to predict the fractional slit position on the bad orders where no object was found.

  • Now loop over the orders and add objects on the orders for which the current object was not found.

Parameters:

  • sobjs (SpecObj) – Objects found on some orders thus far

  • slit_left (numpy.ndarray) – Left boundary of orders to be extracted (given as floating point pixels). Shape is (nspec, norders), where norders is the total number of traced echelle orders.

  • slit_righ (numpy.ndarray) – Right boundary of orders to be extracted (given as floating point pixels). Shape is (nspec, norders), where norders is the total number of traced echelle orders.

  • slit_spat_id (numpy.ndarray) – slit_spat values (spatial position 1/2 way up the detector) for the orders

  • order_vec (numpy.ndarray) – Vector identifying the Echelle orders for each pair of order edges found. This is saved to the output SpecObj objects. If the orders are not known, this can be np.arange(norders) (but this is not recommended).

  • obj_id (numpy.ndarray) – Object IDs of the objects linked together.

  • std_trace (SpecObjs, optional) – Standard star objects (including the traces) Defaults to None.

  • show (bool, optional) – Plot diagnostics related to filling the missing orders

Returns:

A new SpecObjs object with the filled in orders

Return type:

SpecObjs

pypeit.core.findobj_skymask.ech_findobj_ineach_order(image, ivar, slitmask, slit_left, slit_righ, slit_spats, order_vec, spec_min_max, plate_scale_ord, det='DET01', inmask=None, std_trace=None, ncoeff=5, hand_extract_dict=None, box_radius=2.0, fwhm=3.0, use_user_fwhm=False, maxdev=2.0, nperorder=2, extract_maskwidth=3.0, snr_thresh=10.0, specobj_dict=None, trim_edg=(5, 5), show_peaks=False, show_single_fits=False, show_single_trace=False, objfindQA_filename=None)[source]

Find objects in each echelle order, individually.

This routine:

  • Loops over the good orders

  • Calls the objs_in_slit() method to find objects in the order. See that method for further details.

Parameters:

  • image (numpy.ndarray) – (Floating-point) Image to use for object search with shape (nspec, nspat). The first dimension (nspec) is spectral, and second dimension (nspat) is spatial. Note this image can either have the sky background in it, or have already been sky subtracted. Object finding works best on sky-subtracted images. Ideally, object finding is run in another routine, global sky-subtraction performed, and then this code should be run. However, it is also possible to run this code on non-sky-subtracted images.

  • ivar (numpy.ndarray) – Floating-point inverse variance image for the input image. Shape must match image, (nspec, nspat).

  • slitmask (numpy.ndarray) – Integer image indicating the pixels that belong to each order. Pixels that are not on an order have value -1, and those that are on an order have a value equal to the slit number (i.e. 0 to nslits-1 from left to right on the image). Shape must match image, (nspec, nspat).

  • slit_left (numpy.ndarray) – Left boundary of orders to be extracted (given as floating point pixels). Shape is (nspec, norders), where norders is the total number of traced echelle orders.

  • slit_righ (numpy.ndarray) – Right boundary of orders to be extracted (given as floating point pixels). Shape is (nspec, norders), where norders is the total number of traced echelle orders.

  • slit_spats (numpy.ndarray) – slit_spat values (spatial position 1/2 way up the detector) for the orders

  • order_vec (numpy.ndarray) – Vector identifying the Echelle orders for each pair of order edges found. This is saved to the output SpecObj objects. If the orders are not known, this can be np.arange(norders) (but this is not recommended).

  • spec_min_max (numpy.ndarray) – 2D array defining the minimum and maximum pixel in the spectral direction with useable data for each order. Shape must be (2, norders). This should only be used for echelle spectrographs for which the orders do not entirely cover the detector. PCA tracing will re-map the traces such that they all have the same length, compute the PCA, and then re-map the orders back. This improves performance for echelle spectrographs by removing the nonlinear shrinking of the orders so that the linear pca operation can better predict the traces. If None, the minimum and maximum values will be determined automatically from slitmask.

  • plate_scale_ord (numpy.ndarray) – An array with shape (norders,) providing the plate scale of each order in arcsec/pix,

  • det (str, optional) – The name of the detector containing the object. Only used if specobj_dict is None.

  • inmask (numpy.ndarray, optional) – Good-pixel mask for input image. Must have the same shape as image. If None, all pixels in slitmask with non-negative values are considered good.

  • std_trace (numpy.ndarray, optional) – Vector with the standard star trace, which is used as a crutch for tracing. Shape must be (nspec,). If None, the slit boundaries are used as the crutch.

  • ncoeff (int, optional) – Order of polynomial fit to traces.

  • box_radius (float, optional) – Box_car extraction radius in arcseconds to assign to each detected object and to be used later for boxcar extraction. In this method box_radius is converted into pixels using plate_scale. box_radius is also used for SNR calculation and trimming.

  • fwhm (float, optional) – Estimated fwhm of the objects in pixels

  • use_user_fwhm (bool, optional) – If True, PypeIt will use the spatial profile FWHM input by the user (see fwhm) rather than determine the spatial FWHM from the smashed spatial profile via the automated algorithm.

  • maxdev (float, optional) – Maximum deviation of pixels from polynomial fit to trace used to reject bad pixels in trace fitting.

  • nperorder (int, optional) – Maximum number of objects allowed per order. If there are more detections than this number, the code will select the nperorder most significant detections. However, hand apertures will always be returned and do not count against this budget.

  • specobj_dict (dict, optional) –

    Dictionary containing meta-data for the objects that will be propagated into the SpecObj objects. The expected components are:

    • SLITID: The slit ID number

    • DET: The detector identifier

    • OBJTYPE: The object type

    • PYPELINE: The class of pipeline algorithms applied

    If None, the dictionary is filled with the following placeholders:

    specobj_dict = {'SLITID': 999, 'DET': det, 'ECH_ORDERINDX': 999,
                'OBJTYPE': 'unknown', 'PYPELINE': 'Echelle'}

  • trim_edg (tuple, optional) – A two-tuple of integers or floats used to ignore objects within this many pixels of the left and right slit boundaries, respectively.

  • show_peaks (bool, optional) – Plot the QA of the object peak finding in each order.

  • show_single_fits (bool, optional) – Plot trace fitting for single order fits.

  • show_single_trace (bool, optional) – Display the object traces on top of the single order.

  • objfindQA_filename (str, optional) – Full path (directory and filename) for the object profile QA plot. If None, not plot is produced and saved.

Returns:

Object containing the objects detected.

Return type:

SpecObjs

pypeit.core.findobj_skymask.ech_fof_sobjs(sobjs: SpecObjs, slit_left: ndarray, slit_righ: ndarray, order_vec: ndarray, plate_scale_ord: ndarray, fof_link: float = 1.5)[source]

Links together objects previously found using a friends-of-friends algorithm on fractional order position.

Each source from each order is then assigned an obj_id value

Parameters:

  • sobjs (SpecObj) – Previously found objects. There needs to be at least 1.

  • slit_left (numpy.ndarray) – Left boundary of orders to be extracted (given as floating point pixels). Shape is (nspec, norders), where norders is the total number of traced echelle orders.

  • slit_righ (numpy.ndarray) – Right boundary of orders to be extracted (given as floating point pixels). Shape is (nspec, norders), where norders is the total number of traced echelle orders.

  • order_vec (numpy.ndarray) – Vector identifying the Echelle orders for each pair of order edges found.

  • plate_scale_ord (numpy.ndarray) – An array with shape (norders,) providing the plate scale of each order in arcsec/pix,

  • fof_link (float, optional) – Friends-of-friends linking length in arcseconds used to link together traces across orders. The routine links together at the same fractional slit position and links them together with a friends-of-friends algorithm using this linking length.

Returns:

An array containing the object IDs of the objects linked together. This array is aligned with sobjs

Return type:

numpy.ndarray

pypeit.core.findobj_skymask.ech_objfind(image, ivar, slitmask, slit_left, slit_righ, slit_spat_id, order_vec, spec_min_max, det='DET01', inmask=None, fof_link=1.5, plate_scale=0.2, std_trace=None, ncoeff=5, npca=None, coeff_npoly=None, max_snr=2.0, min_snr=1.0, nabove_min_snr=2, pca_explained_var=99.0, box_radius=2.0, fwhm=3.0, use_user_fwhm=False, maxdev=2.0, nperorder=2, extract_maskwidth=3.0, snr_thresh=10.0, specobj_dict=None, trim_edg=(5, 5), show_peaks=False, show_fits=False, show_single_fits=False, show_trace=False, show_single_trace=False, show_pca=False, debug_all=False, objfindQA_filename=None, manual_extract_dict=None)[source]

Object finding routine for Echelle spectrographs.

This routine:

  1. Runs object finding on each order individually

  2. Links the objects found together using a friends-of-friends algorithm on fractional order position.

  3. For objects which were only found on some orders, the standard (or the slit boundaries) are placed at the appropriate fractional position along the order.

  4. A PCA fit to the traces is performed using the routine above pca_fit

Note on masking: This routine requires that all masking be performed in the upstream calling routine (pypeit.find_objects.FindObjects) and thus the slit_left and slit_righ slit edge arrays must only contain these slits. The number of orders in order_vec, spec_min_max, slit_spat_id, and plate_scale must also match the number of slits in the slit_left and slit_righ arrays.

Parameters:

  • image (numpy.ndarray) – (Floating-point) Image to use for object search with shape (nspec, nspat). The first dimension (nspec) is spectral, and second dimension (nspat) is spatial. Note this image can either have the sky background in it, or have already been sky subtracted. Object finding works best on sky-subtracted images. Ideally, object finding is run in another routine, global sky-subtraction performed, and then this code should be run. However, it is also possible to run this code on non-sky-subtracted images.

  • ivar (numpy.ndarray) – Floating-point inverse variance image for the input image. Shape must match image, (nspec, nspat).

  • slitmask (numpy.ndarray) – Integer image indicating the pixels that belong to each order. Pixels that are not on an order have value -1, and those that are on an order have a value equal to the slit number (i.e. 0 to nslits-1 from left to right on the image). Shape must match image, (nspec, nspat).

  • slit_left (numpy.ndarray) – Left boundary of orders to be extracted (given as floating point pixels). Shape is (nspec, norders), where norders is the total number of traced echelle orders.

  • slit_righ (numpy.ndarray) – Right boundary of orders to be extracted (given as floating point pixels). Shape is (nspec, norders), where norders is the total number of traced echelle orders.

  • slit_spat_id (numpy.ndarray) – slit_spat values (spatial position 1/2 way up the detector) for the orders

  • order_vec (numpy.ndarray) – Vector identifying the Echelle orders for each pair of order edges found. This is saved to the output SpecObj objects. If the orders are not known, this can be np.arange(norders) (but this is not recommended).

  • slits_bpm (numpy.ndarray) – Boolean array selecting orders that should be ignored (i.e., good orders are False, bad orders are True). Shape must be (norders,).

  • spec_min_max (numpy.ndarray) – A 2D array defining the minimum and maximum pixel in the spectral direction with useable data for each order. Shape must be (2, norders). This should only be used for echelle spectrographs for which the orders do not entirely cover the detector. PCA tracing will re-map the traces such that they all have the same length, compute the PCA, and then re-map the orders back. This improves performance for echelle spectrographs by removing the nonlinear shrinking of the orders so that the linear pca operation can better predict the traces. Otherwise set the values to -1 and nspec where nspec is the number of pixels in the spectral direction.

  • det (str, optional) – The name of the detector containing the object. Only used if specobj_dict is None.

  • inmask (numpy.ndarray, optional) – Good-pixel mask for input image. Must have the same shape as image. If None, all pixels in slitmask with non-negative values are considered good.

  • fof_link (float, optional) – Friends-of-friends linking length in arcseconds used to link together traces across orders. The routine links together at the same fractional slit position and links them together with a friends-of-friends algorithm using this linking length.

  • plate_scale (float, numpy.ndarray, optional) – Plate scale in arcsec/pix. This can either be a single float for every order, or an array with shape (norders,) providing the plate scale of each order.

  • std_trace (numpy.ndarray, optional) – Vector with the standard star trace, which is used as a crutch for tracing. Shape must be (nspec,). If None, the slit boundaries are used as the crutch.

  • ncoeff (int, optional) – Order of polynomial fit to traces.

  • npca (int, optional) – Number of PCA components to keep during PCA decomposition of the object traces. If None, the number of components set by requiring the PCA accounts for approximately 99% of the variance.

  • coeff_npoly (int, optional) – Order of polynomial used for PCA coefficients fitting. If None, value set automatically, see pca_trace_object().

  • max_snr (float, optional) – For an object to be included in the output object, it must have a max S/N ratio above this value.

  • min_snr (float, optional) – For an object to be included in the output object, it must have a a median S/N ratio above this value for at least nabove_min_snr orders (see below).

  • nabove_min_snr (int, optional) – The required number of orders that an object must have with median SNR greater than min_snr in order to be included in the output object.

  • pca_explained_var (float, optional) – The percentage (i.e., not the fraction) of the variance in the data accounted for by the PCA used to truncate the number of PCA coefficients to keep (see npca). Ignored if npca is provided directly; see pca_trace_object().

  • box_radius (float, optional) – Box_car extraction radius in arcseconds to assign to each detected object and to be used later for boxcar extraction. In this method box_radius is converted into pixels using plate_scale. box_radius is also used for SNR calculation and trimming.

  • fwhm (float, optional) – Estimated fwhm of the objects in pixels

  • use_user_fwhm (bool, optional) – If True, PypeIt will use the spatial profile FWHM input by the user (see fwhm) rather than determine the spatial FWHM from the smashed spatial profile via the automated algorithm.

  • maxdev (float, optional) – Maximum deviation of pixels from polynomial fit to trace used to reject bad pixels in trace fitting.

  • hand_extract_dict (dict, optional) – Dictionary with info on manual extraction; see ManualExtractionObj.

  • nperorder (int, optional) – Maximum number of objects allowed per order. If there are more detections than this number, the code will select the nperorder most significant detections. However, hand apertures will always be returned and do not count against this budget.

  • extract_maskwidth (float, optional) – Determines the initial size of the region in units of FWHM that will be used for local sky subtraction; See objs_in_slit() and local_skysub_extract().

  • snr_thresh (float, optional) – SNR threshold for finding objects

  • specobj_dict (dict, optional) –

    Dictionary containing meta-data for the objects that will be propagated into the SpecObj objects. The expected components are:

    • SLITID: The slit ID number

    • DET: The detector identifier

    • OBJTYPE: The object type

    • PYPELINE: The class of pipeline algorithms applied

    If None, the dictionary is filled with the following placeholders:

    specobj_dict = {'SLITID': 999, 'DET': 'DET01',
                'OBJTYPE': 'unknown', 'PYPELINE': 'unknown'}

  • trim_edg (tuple, optional) – A two-tuple of integers or floats used to ignore objects within this many pixels of the left and right slit boundaries, respectively.

  • show_peaks (bool, optional) – Plot the QA of the object peak finding in each order.

  • show_fits (bool, optional) – Plot trace fitting for final fits using PCA as crutch.

  • show_single_fits (bool, optional) – Plot trace fitting for single order fits.

  • show_trace (bool, optional) – Display the object traces on top of the image.

  • show_single_trace (bool, optional) – Display the object traces on top of the single order.

  • show_pca (bool, optional) – Display debugging plots for the PCA decomposition.

  • debug_all (bool, optional) – Show all the debugging plots. If True, this also overrides any provided values for show_peaks, show_trace, and show_pca, setting them to True.

  • objfindQA_filename (str, optional) – Full path (directory and filename) for the object profile QA plot. If None, not plot is produced and saved.

  • manual_extract_dict – dict, optional Dict guiding the manual extraction

Returns:

Object containing the objects detected.

Return type:

SpecObjs

pypeit.core.findobj_skymask.ech_pca_traces(sobjs_final: SpecObjs, image: ndarray, slitmask: ndarray, inmask: ndarray, order_vec: ndarray, spec_min_max, npca: int | None = None, coeff_npoly: int | None = None, pca_explained_var: float = 99.0, ncoeff: int = 5, maxdev: float = 2.0, fwhm: float = 3.0, show_trace: bool = False, show_fits: bool = False, show_pca: bool = False)[source]

A PCA fit to the traces is performed using the routine pca_fit It then applies iterative flux-weighted centroiding to refine the traces

Parameters:

  • sobjs_final (SpecObj) – Final set of objects ready for tracing

  • image (numpy.ndarray) – (Floating-point) Image to use for object search with shape (nspec, nspat). The first dimension (nspec) is spectral, and second dimension (nspat) is spatial. Note this image can either have the sky background in it, or have already been sky subtracted. Object finding works best on sky-subtracted images. Ideally, object finding is run in another routine, global sky-subtraction performed, and then this code should be run. However, it is also possible to run this code on non-sky-subtracted images.

  • slitmask (numpy.ndarray) – Integer image indicating the pixels that belong to each order. Pixels that are not on an order have value -1, and those that are on an order have a value equal to the slit number (i.e. 0 to nslits-1 from left to right on the image). Shape must match image, (nspec, nspat).

  • inmask (numpy.ndarray, optional) – Good-pixel mask for input image. Must have the same shape as image. If None, all pixels in slitmask with non-negative values are considered good.

  • order_vec (numpy.ndarray) – int array of good orders

  • spec_min_max (numpy.ndarray) – _description_ float array of shape (2, norders) with the minimum and maximum spectral value for each order

  • npca (int, optional) – Number of PCA components to keep during PCA decomposition of the object traces. If None, the number of components set by requiring the PCA accounts for approximately 99% of the variance.

  • coeff_npoly (int, optional) – Order of polynomial used for PCA coefficients fitting. If None, value set automatically, see pca_trace_object().

  • pca_explained_var (float, optional) – The percentage (i.e., not the fraction) of the variance in the data accounted for by the PCA used to truncate the number of PCA coefficients to keep (see npca). Ignored if npca is provided directly; see pca_trace_object().

  • ncoeff (int, optional) – Order of polynomial fit to traces.

  • maxdev (float, optional) – Maximum deviation of pixels from polynomial fit to trace used to reject bad pixels in trace fitting.

  • fwhm (float, optional) – Estimated fwhm of the objects in pixels

  • show_trace (bool, optional) – Display the object traces on top of the image.

  • show_fits (bool, optional) – Plot trace fitting for final fits using PCA as crutch.

  • show_pca (bool, optional) – Display debugging plots for the PCA decomposition.

Returns:

Final set of objects, traced

Return type:

SpecObj

pypeit.core.findobj_skymask.get_fwhm(fwhm_in, nsamp, smash_peakflux, spat_fracpos, flux_smash_smth)[source]

Utility routine to measure the FWHM of an object trace from the spectrally collapsed flux profile by determining the locations along the spatial direction where this profile reaches have its peak value.

Parameters:

  • fwhm_in (float) – Best guess for the FWHM of this object.

  • nsamp (int) – Number of pixels along the spatial direction.

  • smash_peakflux (float) – The peak flux in the 1d (spectrally collapsed) flux profile at the object location.

  • spat_fracpos (float) – Fractional spatial position along the slit where the object is located and at which the flux_smash_smth array has values provided by smash_peakflux (see above and below).

  • flux_smash_smth (numpy.ndarray) – A 1D array with the flux averaged along the spectral direction at each location along the slit in the spatial direction location. Shape is (nsamp,).

Returns:

The FWHM determined from the object flux profile, unless the FWHM could not be found from the profile, in which case the input guess (fwhm_in) is simply returned.

Return type:

float

pypeit.core.findobj_skymask.objfind_QA(spat_peaks, snr_peaks, spat_vector, snr_vector, snr_thresh, qa_title, peak_gpm, near_edge_bpm, nperslit_bpm, objfindQA_filename=None, show=False)[source]

Utility routine for making object finding QA plots.

Parameters:

  • spat_peaks (numpy.ndarray) – Array of locations in the spatial direction at which objects were identified. Shape is (npeaks,), where npeaks is the number of peaks identified.

  • snr_peaks (numpy.ndarray) – S/N ratio in the spectral direction after collapsing along the spectral direction, evaluated at the location of each spatial peak. Shape must match spat_peaks.

  • spat_vector (numpy.ndarray) – A 1D array of spatial locations along the slit. Shape is (nsamp,), where nsamp is the number of spatial pixels defined by the slit edges.

  • snr_vector (numpy.ndarray) – A 1D array with the S/N ratio sampled along the slit at each spatial location (i.e., spectral direction has been smashed out) defined by spat_vector. Shape must match spat_vector.

  • snr_thresh (float) – The threshold S/N ratio adopted by the object finding.

  • qa_title (str) – Title for the QA file plot.

  • peak_gpm (numpy.ndarray) – Boolean array containing a good pixel mask for each peak indicating whether it will be used as an object (True) or not (False). Shape must match spat_peaks.

  • near_edge_bpm (numpy.ndarray) – A bad pixel mask (True is masked, False is unmasked) indicating which objects are masked because they are near the slit edges. Shape must match spat_peaks.

  • nperslit_bpm (numpy.ndarray) – A bad pixel mask (True is masked, False is unmasked) indicating which objects are masked because they exceed the maximum number of objects (see objs_in_slit() parameter nperslit) that were specified as being on this slit.

  • objfindQA_filename (str, optional) – Output filename for the QA plot. If None, plot is not saved.

  • show (bool, optional) – If True, show the plot as a matplotlib interactive plot.

pypeit.core.findobj_skymask.objs_in_slit(image, ivar, thismask, slit_left, slit_righ, inmask=None, fwhm=3.0, sigclip_smash=5.0, use_user_fwhm=False, boxcar_rad=7.0, maxdev=2.0, spec_min_max=None, hand_extract_dict=None, std_trace=None, ncoeff=5, nperslit=None, snr_thresh=10.0, trim_edg=(5, 5), extract_maskwidth=4.0, specobj_dict=None, find_min_max=None, show_peaks=False, show_fits=False, show_trace=False, debug_all=False, qa_title='objfind', objfindQA_filename=None)[source]

Find the location of objects in a slitmask slit or a echelle order.

The algorithm for this function is:

  • Rectify the image by extracting along the edge traces.

  • Compute the sigma-clipped mean spatial profile and its variance by collapsing the image along the spectral direction to constuct a S/N spatial profile of the slit/order.

  • Smooth the S/N profile by a Gaussian with the provided FWHM (see fwhm) and detect peaks in the smoothed profile using detect_lines(). Ignore peaks found near the slit edges, and limit the number of peaks to the number requested (see nperslit).

  • Instantiate a SpecObj object for each valid detection, construct preliminary spectral traces for them, and estimate the object spatial FWHM if one is not provided (see use_user_fwhm).

  • For automatically identified objects (i.e., not manual extractions), improve the object trace by fitting the spatial position of the peak as a function of wavelength. For manual apertures, use either the form of the brightest object on the slit, the trace of a standard star (see std_trace), or the left edge trace to set the trace for the object. Finally, remove automatically identified objects that overlap with manually defined extraction apertures.

At the end of this function, the list of objects is ready for extraction.

Revision History:

  • 10-Mar-2005 – First version written by D. Schlegel, LBL

  • 2005-2018 – Improved by J. F. Hennawi and J. X. Prochaska

  • 23-June-2018 – Ported to python by J. F. Hennawi and significantly improved

  • 01-Feb-2022 – Skymask stripped out by JXP

Parameters:

  • image (numpy.ndarray) – (Floating-point) Image to use for object search with shape (nspec, nspat). The first dimension (nspec) is spectral, and second dimension (nspat) is spatial. Note this image can either have the sky background in it, or have already been sky subtracted. Object finding works best on sky-subtracted images. Ideally, object finding is run in another routine, global sky-subtraction performed, and then this code should be run. However, it is also possible to run this code on non-sky-subtracted images.

  • ivar (numpy.ndarray) – Floating-point inverse variance image for the input image. Shape must match image, (nspec, nspat).

  • thismask (numpy.ndarray) – Boolean mask image selecting pixels associated with the slit/order to search for objects on (True means on the slit/order). Shape must match image.

  • slit_left (numpy.ndarray) – Left boundary of a single slit/orders to be extracted (given as floating point pixels). Shape is (nspec,).

  • slit_righ (numpy.ndarray) – Right boundary of a single slit/orders to be extracted (given as floating point pixels). Shape is (nspec,).

  • inmask (numpy.ndarray, optional) – Good-pixel mask for input image. Shape must match image. If None, set to be the same as thismask.

  • fwhm (float, optional) – Estimated FWHM of the objects in pixels

  • sigclip_smash (float, optional) – Sigma clipping threshold passed to astropy.stats.sigma_clipped_stats to compute average slit emission profile by averaging the (rectified) image along the spatial direction.

  • use_user_fwhm (bool, optional) – If True, PypeIt will use the spatial profile FWHM input by the user (see fwhm) rather than determine the spatial FWHM from the smashed spatial profile via the automated algorithm.

  • boxcar_rad (float, optional) – Box_car extraction radius in pixels to assign to each detected object and to be used later for boxcar extraction.

  • maxdev (float, optional) – Maximum deviation of pixels from polynomial fit to trace used to reject bad pixels in trace fitting.

  • spec_min_max (tuple, optional) – 2-tuple defining the minimum and maximum pixel in the spectral direction with useable data for this slit/order. If None, the values will be determined automatically from thismask. Either element of the tuple can also None, which will then default to using the full min or max over which the slit is defined from thismask.

  • hand_extract_dict (dict, optional) – Dictionary with info on manual extraction; see ManualExtractionObj.

  • std_trace (numpy.ndarray, optional) – Vector with the standard star trace, which is used as a crutch for tracing. Shape must be (nspec,). If None, the slit boundaries are used as the crutch.

  • ncoeff (int, optional) – Order of polynomial fit to traces.

  • nperslit (int, optional) – Maximum number of objects to find. If there are more detections than this number, the code will select the nperslit most significant detections. However, hand apertures will always be returned and do not count against this budget.

  • snr_thresh (float, optional) – SNR threshold for finding objects

  • trim_edg (tuple, optional) – A two-tuple of integers or floats used to ignore objects within this many pixels of the left and right slit boundaries, respectively.

  • extract_maskwidth (float, optional) – Determines the initial size of the region in units of FWHM that will be used for local sky subtraction; See objs_in_slit() and local_skysub_extract().

  • specobj_dict (dict, optional) –

    Dictionary containing meta-data for the objects that will be propagated into the SpecObj objects. The expected components are:

    • SLITID: The slit ID number

    • DET: The detector identifier

    • OBJTYPE: The object type

    • PYPELINE: The class of pipeline algorithms applied

    If None, the dictionary is filled with the following placeholders:

    specobj_dict = {'SLITID': 999, 'DET': 'DET01',
                'OBJTYPE': 'unknown', 'PYPELINE': 'Multislit'}

  • find_min_max (tuple, optional) – 2-tuple of integers that defines the minimum and maximum pixel location of your object in the spectral direction on the detector. It is only used for object finding. This parameter is helpful if your object only has emission lines or at high redshift and the trace only shows in part of the detector. Either element of the tuple can be None, which will then default to using the full range over which the slit is defined. This is distinct from spec_min_max in that spec_min_max indicates the range of the slit/order on the detector, whereas find_min_max indicates the range to be used for object finding. If None or if either member of the tuple is None, it will default to the values of spec_min_max.

  • show_peaks (bool, optional) – Plot the QA of the object peak finding in each order.

  • show_fits (bool, optional) – Plot trace fitting for final fits using PCA as crutch.

  • show_trace (bool, optional) – Display the object traces on top of the image.

  • debug_all (bool, optional) – Show all the debugging plots. If True, this also overrides any provided values for show_peaks, show_fits, and show_trace, setting them to True.

  • qa_title (str, optional) – Title to be printed in the QA plots

  • objfindQA_filename (str, optional) – Full path (directory and filename) for the object profile QA plot. If None, not plot is produced and saved.

Returns:

Object containing the objects detected.

Return type:

SpecObjs

pypeit.core.findobj_skymask.orig_ech_objfind(image, ivar, slitmask, slit_left, slit_righ, order_vec, maskslits, det='DET01', inmask=None, spec_min_max=None, fof_link=1.5, plate_scale=0.2, std_trace=None, ncoeff=5, npca=None, coeff_npoly=None, max_snr=2.0, min_snr=1.0, nabove_min_snr=2, pca_explained_var=99.0, box_radius=2.0, fwhm=3.0, use_user_fwhm=False, maxdev=2.0, hand_extract_dict=None, nperorder=2, extract_maskwidth=3.0, snr_thresh=10.0, specobj_dict=None, trim_edg=(5, 5), show_peaks=False, show_fits=False, show_single_fits=False, show_trace=False, show_single_trace=False, show_pca=False, debug_all=False, objfindQA_filename=None)[source]

Object finding routine for Echelle spectrographs.

This routine:

  1. Runs object finding on each order individually

  2. Links the objects found together using a friends-of-friends algorithm on fractional order position.

  3. For objects which were only found on some orders, the standard (or the slit boundaries) are placed at the appropriate fractional position along the order.

  4. A PCA fit to the traces is performed using the routine above pca_fit

Parameters:

  • image (numpy.ndarray) – (Floating-point) Image to use for object search with shape (nspec, nspat). The first dimension (nspec) is spectral, and second dimension (nspat) is spatial. Note this image can either have the sky background in it, or have already been sky subtracted. Object finding works best on sky-subtracted images. Ideally, object finding is run in another routine, global sky-subtraction performed, and then this code should be run. However, it is also possible to run this code on non-sky-subtracted images.

  • ivar (numpy.ndarray) – Floating-point inverse variance image for the input image. Shape must match image, (nspec, nspat).

  • slitmask (numpy.ndarray) – Integer image indicating the pixels that belong to each order. Pixels that are not on an order have value -1, and those that are on an order have a value equal to the slit number (i.e. 0 to nslits-1 from left to right on the image). Shape must match image, (nspec, nspat).

  • slit_left (numpy.ndarray) – Left boundary of orders to be extracted (given as floating point pixels). Shape is (nspec, norders), where norders is the total number of traced echelle orders.

  • slit_righ (numpy.ndarray) – Right boundary of orders to be extracted (given as floating point pixels). Shape is (nspec, norders), where norders is the total number of traced echelle orders.

  • order_vec (numpy.ndarray) – Vector identifying the Echelle orders for each pair of order edges found. This is saved to the output SpecObj objects. If the orders are not known, this can be np.arange(norders) (but this is not recommended).

  • maskslits (numpy.ndarray) – Boolean array selecting orders that should be ignored (i.e., good orders are False, bad orders are True). Shape must be (norders,).

  • det (str, optional) – The name of the detector containing the object. Only used if specobj_dict is None.

  • inmask (numpy.ndarray, optional) – Good-pixel mask for input image. Must have the same shape as image. If None, all pixels in slitmask with non-negative values are considered good.

  • spec_min_max (numpy.ndarray, optional) – 2D array defining the minimum and maximum pixel in the spectral direction with useable data for each order. Shape must be (2, norders). This should only be used for echelle spectrographs for which the orders do not entirely cover the detector. PCA tracing will re-map the traces such that they all have the same length, compute the PCA, and then re-map the orders back. This improves performance for echelle spectrographs by removing the nonlinear shrinking of the orders so that the linear pca operation can better predict the traces. If None, the minimum and maximum values will be determined automatically from slitmask.

  • fof_link (float, optional) – Friends-of-friends linking length in arcseconds used to link together traces across orders. The routine links together at the same fractional slit position and links them together with a friends-of-friends algorithm using this linking length.

  • plate_scale (float, numpy.ndarray, optional) – Plate scale in arcsec/pix. This can either be a single float for every order, or an array with shape (norders,) providing the plate scale of each order.

  • std_trace (numpy.ndarray, optional) – Vector with the standard star trace, which is used as a crutch for tracing. Shape must be (nspec,). If None, the slit boundaries are used as the crutch.

  • ncoeff (int, optional) – Order of polynomial fit to traces.

  • npca (int, optional) – Number of PCA components to keep during PCA decomposition of the object traces. If None, the number of components set by requiring the PCA accounts for approximately 99% of the variance.

  • coeff_npoly (int, optional) – Order of polynomial used for PCA coefficients fitting. If None, value set automatically, see pca_trace_object().

  • max_snr (float, optional) – For an object to be included in the output object, it must have a max S/N ratio above this value.

  • min_snr (float, optional) – For an object to be included in the output object, it must have a a median S/N ratio above this value for at least nabove_min_snr orders (see below).

  • nabove_min_snr (int, optional) – The required number of orders that an object must have with median SNR greater than min_snr in order to be included in the output object.

  • pca_explained_var (float, optional) – The percentage (i.e., not the fraction) of the variance in the data accounted for by the PCA used to truncate the number of PCA coefficients to keep (see npca). Ignored if npca is provided directly; see pca_trace_object().

  • box_radius (float, optional) – Box_car extraction radius in arcseconds to assign to each detected object and to be used later for boxcar extraction. In this method box_radius is converted into pixels using plate_scale. box_radius is also used for SNR calculation and trimming.

  • fwhm (float, optional) – Estimated fwhm of the objects in pixels

  • use_user_fwhm (bool, optional) – If True, PypeIt will use the spatial profile FWHM input by the user (see fwhm) rather than determine the spatial FWHM from the smashed spatial profile via the automated algorithm.

  • maxdev (float, optional) – Maximum deviation of pixels from polynomial fit to trace used to reject bad pixels in trace fitting.

  • hand_extract_dict (dict, optional) – Dictionary with info on manual extraction; see ManualExtractionObj.

  • nperorder (int, optional) – Maximum number of objects allowed per order. If there are more detections than this number, the code will select the nperorder most significant detections. However, hand apertures will always be returned and do not count against this budget.

  • extract_maskwidth (float, optional) – Determines the initial size of the region in units of FWHM that will be used for local sky subtraction; See objs_in_slit() and local_skysub_extract().

  • snr_thresh (float, optional) – SNR threshold for finding objects

  • specobj_dict (dict, optional) –

    Dictionary containing meta-data for the objects that will be propagated into the SpecObj objects. The expected components are:

    • SLITID: The slit ID number

    • DET: The detector identifier

    • OBJTYPE: The object type

    • PYPELINE: The class of pipeline algorithms applied

    If None, the dictionary is filled with the following placeholders:

    specobj_dict = {'SLITID': 999, 'DET': 'DET01',
                'OBJTYPE': 'unknown', 'PYPELINE': 'unknown'}

  • trim_edg (tuple, optional) – A two-tuple of integers or floats used to ignore objects within this many pixels of the left and right slit boundaries, respectively.

  • show_peaks (bool, optional) – Plot the QA of the object peak finding in each order.

  • show_fits (bool, optional) – Plot trace fitting for final fits using PCA as crutch.

  • show_single_fits (bool, optional) – Plot trace fitting for single order fits.

  • show_trace (bool, optional) – Display the object traces on top of the image.

  • show_single_trace (bool, optional) – Display the object traces on top of the single order.

  • show_pca (bool, optional) – Display debugging plots for the PCA decomposition.

  • debug_all (bool, optional) – Show all the debugging plots. If True, this also overrides any provided values for show_peaks, show_trace, and show_pca, setting them to True.

  • objfindQA_filename (str, optional) – Full path (directory and filename) for the object profile QA plot. If None, not plot is produced and saved.

Returns:

Object containing the objects detected.

Return type:

SpecObjs