Counting

The Counting class contains methods for counting craters and tracking size-frequency distributions.

Available Implementations

Class	Argument name	Example Usage
DepthCount	“depthcount”	counting = Counting.maker(“depthcount”)

class cratermaker.components.counting.Counting(surface, reset=True, **kwargs)

Bases: ComponentBase

Base class for all crater counting models. It defines the interface for tallying the observable craters on a surface.

classmethod maker(counting=None, surface=None, Crater=None, reset=True, **kwargs)

Initialize a Counting model with the given name or instance.

Parameters:

• counting (str, Counting or None, default=None) – The name of the counting model to initialize. If None, the default model is used.

• surface (Surface | LocalSurface) – The surface or local surface view to be counted.

• Crater (type[Crater], optional) – The Crater class associated with this counting model. This is used to ensure that the correct variable properties for from a specialized Crater class are available (such as one associated with a Morphology class) when importing craters from file. If not supplied, then the base Crater class is used.

• reset (bool, optional) – Flag to indicate whether to reset the count and delete any old output files. Default is True

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

Counting – An instance of the specified counting model.

Raises:

• KeyError – If the specified counting model name is not found in the registry.

• TypeError – If the specified counting model is not a string or a subclass of Scaling.

Available models:

• depthcount

reset(**kwargs)

Remove all craters count records from the surface and delete any output files.

Parameters:

**kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

add(crater, **kwargs)

Add a crater to the surface.

Parameters:

• crater (Crater) – The crater to be added to the surface.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

remove(crater_id)

Remove all instances of a crater id from the surface.

Parameters:

crater_id (int) – The ID of the crater to be removed.

fit_rim(crater, tol=0.01, nloops=4, score_quantile=0.95, fit_center=False, fit_ellipse=False, **kwargs)

Find the rim region of a crater on the surface.

Parameters:

• crater (Crater) – The crater for which to find the rim region.

• tol (float, optional) – The tolerance for the rim fitting algorithm. Default is 0.01.

• nloops (int, optional) – The number of iterations for the rim fitting algorithm. Default is 4.

• score_quantile (float, optional) – The quantile of rim scores to consider. Default is 0.95.

• fit_center (bool, optional) – If True, fit the crater center as well. Default is False.

• fit_ellipse (bool, optional) – If True, fit an ellipse to the rim, otherwise fit a circle. Default is False.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

Crater – A new Crater object with updated measured rim parameters.

score_rim(crater, quantile=0.95, gradmult=1.0, curvmult=1.0, heightmult=1.0)

Score the rim region of a crater on the surface.

Parameters:

• crater (Crater) – The crater for which to score the rim region.

• quantile (float, optional) – The quantile of rim scores to consider. Default is 0.95.

• gradmult (float, optional) – Gradient multiplier for scoring. Default is 1.0.

• curvmult (float, optional) – Curvature multiplier for scoring. Default is 1.0.

• heightmult (float, optional) – Height multiplier for scoring. Default is 1.0.

Returns:

Updates the attached surface object with the rim score for this crater.

tally(region=None, measure_rim=False, quiet=False, **kwargs)

Tally the craters on the surface using the method of Minton et al. (2019) [1].

Parameters:

• region (LocalSurface, optional) – A LocalSurface region to count. If not supplied, then the associated surface property is used.

• measure_rim (bool, optional) – If True, measure the rim of each crater. Default is False.

• quiet (bool, optional) – If True, suppress progress output. Default is False.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

References

[1]

Minton, D.A., Fassett, C.I., Hirabayashi, M., Howl, B.A., Richardson, J.E., (2019). The equilibrium size-frequency distribution of small craters reveals the effects of distal ejecta on lunar landscape morphology. Icarus 326, 63-87. https://doi.org/10.1016/j.icarus.2019.02.021

abstractmethod measure_degradation_state(crater, **kwargs)

abstractmethod visibility_function(crater, Kv1=0.17, gamma=2.0, **kwargs)

static to_xarray(craters)

Convert a list or dictionary of Crater objects to an xarray Dataset.

Parameters:

craters (dict[int, Crater] | list[Crater]) – A dictionary or list of Crater objects to convert.

Returns:

xr.Dataset – An xarray Dataset containing the crater data.

save(crater_type='both', interval=0, craters=None, **kwargs)

Dump the crater lists to a file and reset the emplaced crater list.

Parameters:

• crater_type (str, optional) – The type of craters to export. Options are “observed”, “emplaced”, and “both”. Default is “observed”.

• interval (int, default=0) – The interval number for the output file naming.

• craters (list[Crater] | None, optional) – An arbitrary list of craters to save. If None, then the current observed and/or emplaced tallies are used. Default is None.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

from_file(filename, **kwargs)

Load the component data from a file.

This is a stub that acts as a pass-through for components that don’t have a from_file method defined.

Parameters:

• filename (str or Path) – The path to the file to load the component data from.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

export(crater_type='observed', interval=None, driver='SCC', ask_overwrite=None, **kwargs)

Exports crater lists to a file.

Parameters:

• crater_type (str, optional) – The type of craters to export. Options are “observed”, “emplaced”, and “both”. Default is “observed”.

• interval (int | None, optional) – The interval number to export. If None, all intervals currently saved will be exported. Default is None.

• driver (str, default=’SCC’) – The export driver used to save. The valid drivers are given by the valid_drivers attribute of this object.

• ask_overwrite (bool, optional) – If True, the user will be prompted to confirm before overwriting any existing files. If False, existing files will be overwritten without confirmation. If None, the default behavior of the class will be used. This will only persist for the duration of the export, and will be reset to its original value afterwards.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

plot(interval=None, observed_color='white', observed_original_color=None, emplaced_color=None, plot_style='map', variable_name=None, cmap=None, show=True, save=True, ax=None, **kwargs)

Plot an image of the local region.

Parameters:

• interval (int | None, optional) – The interval number to load the emplaced crater data from. if None, then all emplaced data currently saved to file is used. Default is None.

• observed_color (str | None, optional) – The color to use for observed craters using their measured properties. If None, observed craters will not be plotted. Default is “white”.

• observed_original_color (str | None, optional) – The color to use for observed craters using their original properties. If None, observed craters will not be plotted. Default is None.

• emplaced_color (str | None, optional) – The color to use for emplaced craters. If None, emplaced craters will not be plotted. Default is None.

• plot_style (str, optional) – The style of the plot. Options are “map” and “hillshade”. In “map” mode, the variable is displayed as a colored map. In “hillshade” mode, a hillshade image is generated using “face_elevation” data. If a different variable is passed to variable, then the hillshade will be overlayed with that variable’s data. Default is “map”.

• variable_name (str | None, optional) – The variable to plot. If None is provided then “face_elevation” is used in “map” mode.

• cmap (str, optional) – The colormap to use for the plot. If None, a default colormap will be used (“cividis” by default and “grey” when plot_style==”hillshade” and variable==”face_elevation”).

• show (bool, optional) – If True, the plot will be displayed. Default is True.

• save (bool, optional) – If True, the plot will be saved to the default plot directory. Default is True

• ax (matplotlib.axes.Axes, optional) – An existing Axes object to plot on. If None, a new figure and axes will be created.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

matplotlib.image.Axes object created by the surface plot method, with crater counts plotted on top if specified. If show is True, the plot will also be displayed. – The Axes object

show_pyvista(surface=None, observed_color='white', emplaced_color='red', interval=None, **kwargs)

Passes through to the surface show_pyvista method and adds crater counts to it.

Parameters:

• surface (Surface | LocalSurface, optional) – The surface or local surface view to be displayed. If None, uses the associated surface property

• observed_color (str, optional) – The color to use for observed craters. Default is “white”.

• emplaced_color (str, optional) – The color to use for emplaced craters. Default is “red”.

• interval (int, optional) – The interval number to load the emplaced crater data from. if None, then all emplaced data currently saved to file is used. Default is None.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

plotter (pyvista.Plotter) – The pyvista plotter with the crater counts added.

show3d(engine='pyvista', observed_color='white', emplaced_color='red', **kwargs)

Passes through to the surface show method and adds crater counts to it.

Parameters:

• engine (str, optional) – The engine to use for plotting. Currently, only “pyvista” is supported. Default is “pyvista”.

• observed_color (str, optional) – The color to use for observed craters. Default is “white”.

• emplaced_color (str, optional) – The color to use for emplaced craters. Default is “red”.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

plotter (pyvista.Plotter or other engine-specific plotter object)

to_geoseries(craters=None, use_measured_properties=True, split_antimeridian=False, **kwargs)

to_vector_file(name='observed', crater_ds=None, interval=None, driver='GPKG', use_measured_properties=True, **kwargs)

Export the crater data to a vector file and stores it in the default export directory.

Parameters:

• name (Literal[“observed”, “emplaced”], optional) – The name of the crater dataset to export, either “observed” or “emplaced

• crater_ds (xr.Dataset | list[Crater] | dict[int, Crater] | None, optional) – The crater data to export. Can be provided as an xarray Dataset, a list of Crater objects, or a dictionary mapping interval numbers to Crater objects. If None, the crater data will be the attribute of the class corresponding to the name parameter (self.observed or self.emplaced). Default is None.

• interval (int | None, optional) – The interval number to export. If None, all intervals currently saved will be exported. Default is None.

• driver (str, optional) – The file format to save. Supported formats are ‘GPKG’, ‘ESRI Shapefile’, etc. Default is ‘GPKG’.

• use_measured_properties (bool, optional) – If True, use the current measured crater properties (semimajor_axis, semiminor_axis, location, orientation) instead of the initial ones, by default True.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

to_vtk_mesh(craters, use_measured_properties=True, **kwargs)

Convert the crater data to a VTK PolyData mesh.

Parameters:

• craters (list[Crater]) – A list of Crater objects to convert.

• use_measured_properties (bool, optional) – If True, use the current measured crater properties (semimajor_axis, semiminor_axis, location, orientation) instead of the initial ones, by default True.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

vtkPolyData – A VTK PolyData object representing the crater geometries.

to_vtk_file(name='observed', crater_ds=None, interval=None, **kwargs)

Export the crater data to a VTK file and stores it in the default export directory.

Notes: In order for the crater and surface to be synced up when saving to VTK/VTP format, the initial conditions (no craters) must be saved. Otherwise, saving to file only occurs if there are craters to save.

Parameters:

• name (Literal[“observed”, “emplaced”], optional) – The name of the crater dataset to export, either “observed” or “emplaced

• crater_ds (xr.Dataset | list[Crater] | dict[int, Crater] | None, optional) – The crater data to export. Can be provided as an xarray Dataset, a list of Crater objects, or a dictionary mapping interval numbers to Crater objects. If None, the crater data will be the attribute of the class corresponding to the name parameter (self.observed or self.emplaced). Default is None.

• interval (int | None, optional) – The interval number to export. If None, all intervals currently saved will be exported. Default is None.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

to_csv_file(name='observed', crater_ds=None, interval=None, **kwargs)

Export the crater data to a CSV file and stores it in the default export directory.

Parameters:

• name (Literal[“observed”, “emplaced”], optional) – The name of the crater dataset to export, either “observed” or “emplaced

• crater_ds (xr.Dataset | list[Crater] | dict[int, Crater] | None, optional) – The crater data to export. Can be provided as an xarray Dataset, a list of Crater objects, or a dictionary mapping interval numbers to Crater objects. If None, the crater data will be the attribute of the class corresponding to the name parameter (self.observed or self.emplaced). Default is None.

• interval (int | None, optional) – The interval number to export. If None, all intervals currently saved will be exported. Default is None.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

from_csv_file(input_file)

Import crater data from a CSV file.

Parameters:

input_file (Path | str) – The path to the CSV file containing crater data.

Returns:

list[Crater] – A list of Crater objects imported from the CSV file.

to_scc_file(name='observed', crater_ds=None, interval=None, **kwargs)

Export the crater data to Craterstats and OpenCraterTools-compatible SCC file and stores it in the default export directory.

Parameters:

• name (Literal[“observed”, “emplaced”], optional) – The name of the crater dataset to export, either “observed” or “emplaced

• crater_ds (xr.Dataset | list[Crater] | dict[int, Crater] | None, optional) – The crater data to export. Can be provided as an xarray Dataset, a list of Crater objects, or a dictionary mapping interval numbers to Crater objects. If None, the crater data will be the attribute of the class corresponding to the name parameter (self.observed or self.emplaced). Default is None.

• interval (int | None, optional) – The interval number to export. If None, all intervals currently saved will be exported. Default is None.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

from_scc_file(input_file)

Import crater data from a Spatial Crater Count file.

Parameters:

input_file (Path | str) – The path to the SCC file containing crater data.

Returns:

list[Crater] – A list of Crater objects imported from the SCC file.

from_xarray(dataset, interval=None)

Import crater data from an xarray Dataset.

Parameters:

dataset (xr.Dataset | dict) – The xarray Dataset containing crater data or a dictionary of xarray Datasets keyed by interval number.

Returns:

list[Crater] – A list of Crater objects imported from the xarray Dataset.

remove_complex_data()

Remove complex data from all observed and emplaced craters to free up memory. This is typically called after the tally step to clear out things like the affect node and face index sets.

property surface

The Surface object associated with this Counting object.

property n_layer

Number of layers in the counting model.

property observed

Dictionary of observed craters on the surface keyed to the crater id.

property emplaced

List of craters that have been emplaced in the simulation in the current interval in chronological order.

property n_emplaced

Number of craters that have been emplaced in the simulation in the current interval.

property n_observed

Number of craters that have been observed on the surface in the current interval.

property Crater

The Crater class used for this counting component, which is determined by the morphology component.

property morphology

The morphology component associated with this counting component, which determines the Crater class and the crater properties that are tracked in the simulation.

DepthCount

See Counting for inherited methods and attributes.

class cratermaker.components.counting.depthcount.DepthCount(surface, **kwargs)

Bases: Counting

A basic crater counting model that uses depth-to-diameter values to estimate degradation states of craters for counting.

Parameters:

• surface (Surface | LocalSurface) – The surface or local surface view to be counted.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

measure_degradation_state(crater, **kwargs)

Measure the degradation state of a crater by using a variation of the depth-to-diameter proxy for degradation state from Minton et al. (2019) [2] and Riedel et al. (2020) [3].

Parameters:

• crater (Crater) – The crater to measure.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

float – The estimated degradation state of the crater in m². The crater object will also have its degradation state value updated in place

References

[2]

Minton, D.A., Fassett, C.I., Hirabayashi, M., Howl, B.A., Richardson, J.E., (2019). The equilibrium size-frequency distribution of small craters reveals the effects of distal ejecta on lunar landscape morphology. Icarus 326, 63-87. https://doi.org/10.1016/j.icarus.2019.02.021

[3]

Riedel, C., Minton, D.A., Michael, G., Orgel, C., Bogert, C.H. van der, Hiesinger, H., 2020. Degradation of Small Simple and Large Complex Lunar Craters: Not a Simple Scale Dependence. Journal of Geophysical Research: Planets 125, e2019JE006273. https://doi.org/10.1029/2019JE006273

Notes

The technique used here is a major improvement over the one used previously in CTEM. Rather than using the depth-to-diameter directly, it instead uses the ratio of the measured depth-to-diameter to the initial computed depth-to-diameter of the crater. Fitting functions for both simple and complex craters were developed using this metric.

visibility_function(crater, Kv1=0.3, gamma=2.0, **kwargs)

Calculate the visibility function for a crater using eq. 7 from Minton et al. (2019) [4].

Parameters:

• crater (Crater) – The crater to calculate the visibility function for.

• Kv1 (float) – The visibility function parameter Kv1 from Minton et al. (2019). Default value is 0.30 based on recalibration with Cratermaker.

• gamma (float) – The visibility function parameter gamma from Minton et al. (2019). Default value is 2.0.

• **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

float – The visibility function value for the crater in units of m².

References

[4]

Minton, D.A., Fassett, C.I., Hirabayashi, M., Howl, B.A., Richardson, J.E., (2019). The equilibrium size-frequency distribution of small craters reveals the effects of distal ejecta on lunar landscape morphology. Icarus 326, 63-87. https://doi.org/10.1016/j.icarus.2019.02.021