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:

  • image (ndarray) – Input image.

  • header (astropy.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_header (astropy.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_keys (list, optional) – See save_image_header_keys. Default is an empty list (nothing saved from image_header).

  • processes (int, optional) – See processes. The default is 2.

  • min_length (int, optional) – See min_length. The default is 25 pixels.

  • max_width (int, optional) – See max_width. The default is 75 pixels.

  • buffer (int, optional) – See buffer. The default is 250 pixels on each side.

  • threshold (float, optional) – See threshold. The default is 5.

  • theta (ndarray, optional) – See theta. The default is None, which sets to numpy.arange(0, 180, 0.5).

  • kernels (list, 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_status (list, optional) – See mask_include_status. The default is [2].

  • plot (bool, 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_dir (str, optional) – See output_dir. The default is '.' (current directory).

  • output_root (string, optional) – See root. The default is '' (no prefix).

  • check_persistence (bool, optional) – See check_persistence. The default is True.

  • min_persistence (float, optional) – See min_persistence. Must be between 0 and 1. The default is 0.5.

  • ignore_theta_range (list of tuples or None, optional) – See ignore_theta_range. Default is None.

  • save_catalog (bool, optional) – See save_catalog. Default is True.

  • save_diagnostic (bool, optional) – See save_diagnostic. Default is True.

  • save_mrt (bool, optional) – See save_mrt. Default is False.

  • save_mask (bool, 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_catalog (bool, optional) – Flag to remove all filtered trails from the source catalog. The default is False.

  • plot_streak (bool, 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_list – Catalog of identified satellite trails with additional measured parameters appended. This is the same info as self.source_list.

Return type:

QTable or None

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_list – Catalog containing information about detected trails, if applicable. This is the same info as self.source_list.

Return type:

QTable or None

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:

  • ax (matplotlib.axes.Axes, optional) – A matplotlib subplot where the image should be shown. The default is None (one will be created for you).

  • scale (tuple 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_mask (bool, optional) – Overlay the trail mask, if already calculated. Default is False.

plot_mask()

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

Returns:

ax – The matplotlib subplot containing the mask image.

Return type:

matplotlib.axes.Axes

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

Plot the MRT.

Parameters:

  • ax (matplotlib.axes.Axes, optional) – A matplotlib subplot where MRT should be shown. The default is None (one will be created for you).

  • scale (tuple 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_sources (bool) – Mark the positions of the detected sources. Default is False.

Returns:

ax – Matplotlib subplot where the MRT is plotted.

Return type:

matplotlib.axes.Axes

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

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

Parameters:

  • ax (matplotlib.axes.Axes, optional) – A matplotlib subplot where the SNR should be shown. The default is None (one will be created for you).

  • scale (tuple 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_map – A map of the SNR.

Return type:

array-like

plot_segment()

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

Returns:

ax – A matplotlib subplot containing the segmentation map.

Return type:

matplotlib.axes.Axes

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:

  1. run_mrt()

  2. find_mrt_sources()

  3. filter_sources()

  4. make_mask()

  5. 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:

  1. MRT

  2. Mask/segementation image

  3. Catalog

  4. Trail catalog

Parameters:

close_plot (bool) – Close the plot instance after save_diagnostic is done.