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:
- 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 objectsimage (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 ordersplate_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 leastnabove_min_snr
orders (see below).nabove_min_snr (
int
, optional) – The required number of orders that an object must have with median SNR greater thanmin_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 methodbox_radius
is converted into pixels usingplate_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 inslitmask
with non-negative values are considered good.
- Returns:
The final set of objects
- Return type:
- 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 farslit_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 benp.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:
- 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 benp.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 ifspecobj_dict
is None.inmask (numpy.ndarray, optional) – Good-pixel mask for input image. Must have the same shape as
image
. If None, all pixels inslitmask
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 methodbox_radius
is converted into pixels usingplate_scale
.box_radius
is also used for SNR calculation and trimming.fwhm (
float
, optional) – Estimated fwhm of the objects in pixelsuse_user_fwhm (
bool
, optional) – If True,PypeIt
will use the spatial profile FWHM input by the user (seefwhm
) 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 thenperorder
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:
- 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:
- 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:
Runs object finding on each order individually
Links the objects found together using a friends-of-friends algorithm on fractional order position.
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.
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 theslit_left
andslit_righ
slit edge arrays must only contain these slits. The number of orders inorder_vec
,spec_min_max
,slit_spat_id
, andplate_scale
must also match the number of slits in theslit_left
andslit_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 benp.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 ifspecobj_dict
is None.inmask (numpy.ndarray, optional) – Good-pixel mask for input image. Must have the same shape as
image
. If None, all pixels inslitmask
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, seepca_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 leastnabove_min_snr
orders (see below).nabove_min_snr (
int
, optional) – The required number of orders that an object must have with median SNR greater thanmin_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 (seenpca
). Ignored ifnpca
is provided directly; seepca_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 methodbox_radius
is converted into pixels usingplate_scale
.box_radius
is also used for SNR calculation and trimming.fwhm (
float
, optional) – Estimated fwhm of the objects in pixelsuse_user_fwhm (
bool
, optional) – If True,PypeIt
will use the spatial profile FWHM input by the user (seefwhm
) 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; seeManualExtractionObj
.nperorder (
int
, optional) – Maximum number of objects allowed per order. If there are more detections than this number, the code will select thenperorder
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; Seeobjs_in_slit()
andlocal_skysub_extract()
.snr_thresh (
float
, optional) – SNR threshold for finding objectsspecobj_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 forshow_peaks
,show_trace
, andshow_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:
- 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 tracingimage (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 inslitmask
with non-negative values are considered good.order_vec (numpy.ndarray) –
int
array of good ordersspec_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, seepca_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 (seenpca
). Ignored ifnpca
is provided directly; seepca_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 pixelsshow_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:
- 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 theflux_smash_smth
array has values provided bysmash_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:
- 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,)
, wherenpeaks
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,)
, wherensamp
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 matchspat_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()
parameternperslit
) 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 usingdetect_lines()
. Ignore peaks found near the slit edges, and limit the number of peaks to the number requested (seenperslit
).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 (seeuse_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 asthismask
.fwhm (
float
, optional) – Estimated FWHM of the objects in pixelssigclip_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 (seefwhm
) 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 fromthismask
. 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 fromthismask
.hand_extract_dict (
dict
, optional) – Dictionary with info on manual extraction; seeManualExtractionObj
.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 thenperslit
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 objectstrim_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; Seeobjs_in_slit()
andlocal_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 fromspec_min_max
in thatspec_min_max
indicates the range of the slit/order on the detector, whereasfind_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 ofspec_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 forshow_peaks
,show_fits
, andshow_trace
, setting them to True.qa_title (
str
, optional) – Title to be printed in the QA plotsobjfindQA_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:
- 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:
Runs object finding on each order individually
Links the objects found together using a friends-of-friends algorithm on fractional order position.
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.
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 benp.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 ifspecobj_dict
is None.inmask (numpy.ndarray, optional) – Good-pixel mask for input image. Must have the same shape as
image
. If None, all pixels inslitmask
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, seepca_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 leastnabove_min_snr
orders (see below).nabove_min_snr (
int
, optional) – The required number of orders that an object must have with median SNR greater thanmin_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 (seenpca
). Ignored ifnpca
is provided directly; seepca_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 methodbox_radius
is converted into pixels usingplate_scale
.box_radius
is also used for SNR calculation and trimming.fwhm (
float
, optional) – Estimated fwhm of the objects in pixelsuse_user_fwhm (
bool
, optional) – If True,PypeIt
will use the spatial profile FWHM input by the user (seefwhm
) 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; seeManualExtractionObj
.nperorder (
int
, optional) – Maximum number of objects allowed per order. If there are more detections than this number, the code will select thenperorder
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; Seeobjs_in_slit()
andlocal_skysub_extract()
.snr_thresh (
float
, optional) – SNR threshold for finding objectsspecobj_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 forshow_peaks
,show_trace
, andshow_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: