TrailFinder

class acstools.findsat_mrt.TrailFinder(image, header=None, image_header=None, save_image_header_keys=None, processes=2, min_length=25, max_width=75, buffer=250, threshold=5, theta=None, kernels=None, mask_include_status=[2], plot=False, output_dir='.', output_root='', check_persistence=True, min_persistence=0.5, ignore_theta_range=None, save_catalog=True, save_diagnostic=True, save_mrt=False, save_mask=False)

Bases: object

Top-level class to handle trail identification and masking.

Parameters:

imagendarray: Input image.
headerastropy.io.fits.Header, optional: The primary header for the input data (usually the 0th extension). This is not used for anything during the analysis, but it is saved with the output mask and satellite trail catalog so information about the original observation can be easily retrieved. Default is None.
image_headerastropy.io.fits.Header, optional: The specific header for the FITS extension being used. This is added onto the catalog. Default is None.
save_image_header_keyslist, optional: See save_image_header_keys. Default is an empty list (nothing saved from image_header).
processesint, optional: See processes. The default is 2.
min_lengthint, optional: See min_length. The default is 25 pixels.
max_widthint, optional: See max_width. The default is 75 pixels.
bufferint, optional: See buffer. The default is 250 pixels on each side.
thresholdfloat, optional: See threshold. The default is 5.
thetandarray, optional: See theta. The default is None, which sets to numpy.arange(0, 180, 0.5).
kernelslist, optional: See kernels. The default is None, which reverts to using the 3-, 7-, and 15-pixel wide kernels included with this package.
mask_include_statuslist, optional: See mask_include_status. The default is [2].
plotbool, optional: Plot all intermediate steps. When set, plots of the input image, MRT with identified sources, and resulting image mask will be generated after running the constructor, acstools.findsat_mrt.TrailFinder.run_mrt(), acstools.findsat_mrt.TrailFinder.find_mrt_sources(), acstools.findsat_mrt.TrailFinder.filter_sources(), and acstools.findsat_mrt.TrailFinder.make_mask(). Users may also generate these plots manually by calling acstools.findsat_mrt.TrailFinder.plot_image(), acstools.findsat_mrt.TrailFinder.plot_mrt(), acstools.findsat_mrt.TrailFinder.plot_mask(), and acstools.findsat_mrt.TrailFinder.plot_segment(). The default is False.
output_dirstr, optional: See output_dir. The default is '.' (current directory).
output_rootstring, optional: See root. The default is '' (no prefix).
check_persistencebool, optional: See check_persistence. The default is True.
min_persistencefloat, optional: See min_persistence. Must be between 0 and 1. The default is 0.5.
ignore_theta_rangelist of tuples or None, optional: See ignore_theta_range. Default is None.
save_catalogbool, optional: See save_catalog. Default is True.
save_diagnosticbool, optional: See save_diagnostic. Default is True.
save_mrtbool, optional: See save_mrt. Default is False.
save_maskbool, optional: See save_mask. Default is False.

Attributes Summary

`buffer`	Size of cutout region extending perpendicularly outward on each side from a streak/trail when analyzing its properties.
`check_persistence`	Calculate the persistence of all identified streaks.
`ignore_theta_range`	List of ranges in `theta` to ignore when identifying satellite trails.
`kernels`	Paths to each kernel to be used for source finding in the MRT.
`mask_include_status`	List indicating trails with which status should be considered when making the mask.
`max_width`	Maximum streak width allowed.
`min_length`	Minimum streak length allowed.
`min_persistence`	Minimum persistence of a "true" satellite trail to be considered robust.
`output_dir`	Path in which to save output.
`processes`	Number of processes to use when calculating MRT.
`root`	A prefix for all output files.
`save_catalog`	Save the catalog of identified trails to a FITS table.
`save_diagnostic`	Save a diagnotic plot showing the input image and identified trails to a PNG file.
`save_image_header_keys`	List of header keys from `self.image_header` to save in the output trail catalog header.
`save_mask`	Save the trail mask in a FITS file.
`save_mrt`	Save the MRT in a FITS file.
`theta`	Angles at which to calculate the MRT.
`threshold`	Minimum SNR when extracting sources from the MRT.

Methods Summary

`filter_sources`([trim_catalog, plot_streak])	Filters catalog of trails based on SNR, width, and persistence.
`find_mrt_sources`()	Finds sources in the MRT consistent with satellite trails/streaks.
`make_mask`()	Makes a satellite trail mask (bool) and a segmentation map.
`plot_image`([ax, scale, overlay_mask])	Plot the input image.
`plot_mask`()	Generates a plot of the trail mask (`self.mask`).
`plot_mrt`([ax, scale, show_sources])	Plot the MRT.
`plot_mrt_snr`([ax, scale])	Plots a map of the MRT signal-to-noise ratio (SNR).
`plot_segment`()	Generates a segmentation image of the identified trails (`self.segment`).
`run_all`([trim_catalog, plot_streak, close_plot])	Run the entire pipeline to identify, filter, and mask trails.
`run_mrt`()	Run the median radon transform on the input image.
`save_output`([close_plot])	Save output.

Attributes Documentation

buffer: Size of cutout region extending perpendicularly outward on each side from a streak/trail when analyzing its properties.

check_persistence: Calculate the persistence of all identified streaks.

ignore_theta_range: List of ranges in theta to ignore when identifying satellite trails. This parameter is most useful for avoiding false positives due to diffraction spikes that always create streaks around the same angle for a given telescope/instrument. Format should be a list of tuples, e.g., [(theta0_a, theta1_a), (theta0_b, theta1_b)].

kernels: Paths to each kernel to be used for source finding in the MRT.

mask_include_status

List indicating trails with which status should be considered when making the mask. Statuses are generated by acstools.utils_findsat_mrt.filter_sources():

1 = Failed SNR or width requirements.
2 = Passed SNR and width requirements but failed persistence test.
3 = Passed SNR, width, and persistence requirements.

max_width: Maximum streak width allowed. This is the maximum width of a trail to be considered robust.

min_length: Minimum streak length allowed. This is the minimum allowed length of a satellite trail.

min_persistence: Minimum persistence of a “true” satellite trail to be considered robust. Note that this does not reject satellite trails from the output catalog, but highlights them in a different color in the output plot.

output_dir: Path in which to save output.

processes: Number of processes to use when calculating MRT.

root: A prefix for all output files.

save_catalog: Save the catalog of identified trails to a FITS table.

save_diagnostic: Save a diagnotic plot showing the input image and identified trails to a PNG file.

save_image_header_keys: List of header keys from self.image_header to save in the output trail catalog header.

save_mask: Save the trail mask in a FITS file.

save_mrt: Save the MRT in a FITS file.

theta: Angles at which to calculate the MRT.

threshold: Minimum SNR when extracting sources from the MRT.

Methods Documentation

filter_sources(trim_catalog=False, plot_streak=False)

Filters catalog of trails based on SNR, width, and persistence. This uses threshold, max_width, min_length, buffer, check_persistence, and min_persistence for calculations, so update them first, if needed.

Parameters:

trim_catalogbool, optional: Flag to remove all filtered trails from the source catalog. The default is False.
plot_streakbool, optional: Set to plot diagnostics for each trail. Only works in interactive mode. Warning: this can generate a lot of plots depending on how many trails are found. Default is False.

Returns:

source_listQTable or None: Catalog of identified satellite trails with additional measured parameters appended. This is the same info as self.source_list.

find_mrt_sources()

Finds sources in the MRT consistent with satellite trails/streaks. This uses kernels and threshold for calculations, so update them first, if needed.

Returns:

source_listQTable or None: Catalog containing information about detected trails, if applicable. This is the same info as self.source_list.

make_mask()

Makes a satellite trail mask (bool) and a segmentation map. This uses mask_include_status, so update it first, if needed.

The segmentation map is an image where pixels belonging to a given trail have values equal to the trail ID number.

This updates self.segment and self.mask.

plot_image(ax=None, scale=(-1, 5), overlay_mask=False)

Plot the input image.

Parameters:

axmatplotlib.axes.Axes, optional: A matplotlib subplot where the image should be shown. The default is None (one will be created for you).
scaletuple of floats, optional: A two element array with the minimum and maximum image values used to set the color scale, in units of the image median absolute deviation (MAD). The default is (-1, 5).
overlay_maskbool, optional: Overlay the trail mask, if already calculated. Default is False.

plot_mask()

Generates a plot of the trail mask (self.mask).

Returns:

axmatplotlib.axes.Axes: The matplotlib subplot containing the mask image.

plot_mrt(ax=None, scale=(0, 10), show_sources=False)

Plot the MRT.

Parameters:

axmatplotlib.axes.Axes, optional: A matplotlib subplot where MRT should be shown. The default is None (one will be created for you).
scaletuple of floats, optional: A two element array with the minimum and maximum image values used to set the color scale, in units of the MRT median absolute deviation (MAD). The default is (-1, 5).
show_sourcesbool: Mark the positions of the detected sources. Default is False.

Returns:

axmatplotlib.axes.Axes: Matplotlib subplot where the MRT is plotted.

plot_mrt_snr(ax=None, scale=(1, 25))

Plots a map of the MRT signal-to-noise ratio (SNR).

Parameters:

axmatplotlib.axes.Axes, optional: A matplotlib subplot where the SNR should be shown. The default is None (one will be created for you).
scaletuple of floats, optional: A two element array with the minimum and maximum image values used to set the color scale. The default is (1, 25).

Returns:

snr_maparray-like: A map of the SNR.

plot_segment()

Generates a segmentation image of the identified trails (self.segment).

Returns:

axmatplotlib.axes.Axes: A matplotlib subplot containing the segmentation map.

run_all(trim_catalog=False, plot_streak=False, close_plot=True)

Run the entire pipeline to identify, filter, and mask trails. This calls the following methods in the given order:

run_mrt()
find_mrt_sources()
filter_sources()
make_mask()
save_output()

See the documentation for methods above on how to use the keyword options.

run_mrt(): Run the median radon transform on the input image. This uses theta and processes for calculations, so update them first, if needed.

save_output(close_plot=True)

Save output. Any existing file will be overwritten. This uses root, output_dir, save_mrt, save_catalog, and save_diagnostic, so update them first, if needed. Output includes optionally:

MRT
Mask/segementation image
Catalog
Trail catalog

Parameters:

close_plotbool: Close the plot instance after save_diagnostic is done.