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, 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.

• 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.

Returns:

MorphologyCrater – The emplacec crater

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, **kwargs)

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.

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

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. doi: 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, time_variables=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.

• time_variables (dict | None, optional) – A dictionary of time variables to include in the output file.

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

export(crater_type='both', 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, label=None, scalebar=None, colorbar=True, show=False, save=True, ax=None, close_when_done=True, minimum_plot_width=800, **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”).

• label (str | None, optional) – A label for the plot. If None, no label will be added.

• scalebar (bool, optional) – If True, a scalebar will be added to the plot. Default is True.

• colorbar (bool, optional) – If True, a colorbar will be added to the plot when using “map” plot_style or “hillshade” with a variable overlay. Default is True.

• 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.

• close_when_done (bool, optional) – If True, the figure will be closed after plotting. Default is True when save is True and show is False, and False otherwise.

• minimum_plot_width (float, optional) – Because the width of the plot is determined by the number of faces, small regions will generate small plots with labels that are hard to read. This parameter sets a lower limit to the width of the image that is generated by the plot. By default it is 800. Set to None to turn it off.

• **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

pyvista_plotter(crater_type='both', interval=None, enable_interactive=True, crater_color=('white', 'red'), crater_style='rings', surface=None, plotter=None, crater_size_scale_factor=1.0, **kwargs)

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

When enable_interactive is True (the default), this will add all saved crater data (observed and emplaced) with all plot styles (rings, points, and impacts) and allow them to be activated by key presses. If False, this will only plot one set of data with one style.

Parameters:

• crater_type (Literal[“observed”,”emplaced”,”both”] | list[Crater].) – This is only used if enable_interactive is False, in which case it controls which crater data will be plotted. Default is “both”.

• 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.

• enable_interactive (bool, optional) – If True, enables key events to toggle the visibility of all saved crater count types (observed and emplaced) with all styles (rings, points, and impacts), which are activated by keypresses (“c” for observed craters, and “t” for emplaced craters), and all are not visible on initialization. If False, only one set of data is plotted, and is visible on initialization.

• crater_color (str | tuple[str] = (“white”, “yellow”)) – The color to use for the plots. When used with enable_interactive or when craters is set to “both”, this is a tuple where the first element is the color of observed craters and the second is the color of emplaced craters. Default is (“white,”red”).

• crater_style (Literal[“rings”, “points”], optional) – Only used when enable_interactive is False. Sets the style of the mesh. Options are “rings”, which creates polyline circles over the rim of each crater or “points” which creates a point at the center.

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

• plotter (pyvista.Plotter, optional) – An existing pyvista Plotter to add the crater counts to. If None, a new Plotter will be created by the surface pyvista_plotter method. Default is None.

• crater_size_scale_factor (FloatLike, optional) – A factor to scale the size of the craters in “point”, “impacts”, or “spheres” styles. Default is 1.0.

• **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.

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

to_vector_file(crater_type='observed', craters=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:

• crater_type (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(crater_type=None, interval=None, craters=None, use_measured_properties=True, crater_style='rings', crater_size_scale_factor=1.0, **kwargs)

Convert the crater data to a VTK PolyData mesh.

Parameters:

• crater_type (Literal[“observed”, “emplaced”], optional) – The name of the crater dataset to convert, either “observed” or “emplaced. If None is provided, then a list of Crater objects must be provided directly to the craters parameter. Default is None.

• interval (int | None, optional) – The interval number to load if craters is not provided directly. If None, then the most recent interval will be used. Default is None.

• craters (list[Crater], optional) – A list of Crater objects to convert. If None is provided, then the crater dataset will be determined by the name parameter. Default is None.

• 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.

• crater_style (Literal[“rings”, “points”, “impacts”, “spheres”], optional) – Sets the style of the mesh. Options are “rings”, which creates polyline circles over the rim of each crater, “points” which creates a small sphere at the center of each crater, and “impacts” which places a point above the floor of the center of the crater and “spheres” which creates spheres with radius equal to the projectile radius at the location of each crater. Default is “rings”.

• crater_size_scale_factor (FloatLike, optional) – A factor to scale the size of the craters in “point”, “impacts”, or “spheres” styles, which places the center point of the actor above the surface by its radius. Default is 1.0.

• **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(crater_type=None, interval=None, craters=None, use_measured_properties=True, crater_style='rings', crater_size_scale_factor=1.0, **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:

• crater_type (Literal[“observed”, “emplaced”], optional) – The name of the crater dataset to convert, either “observed” or “emplaced. If None is provided, then a list of Crater objects must be provided directly to the craters parameter. Default is None.

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

• craters (list[Crater], optional) – A list of Crater objects to convert. If None is provided, then the crater dataset will be determined by the crater_type parameter. Default is None.

• 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.

• crater_style (Literal[“rings”, “points”, “impacts”, “spheres”], optional) – Sets the style of the mesh. Options are “rings”, which creates polyline circles over the rim of each crater, “points” which creates a small sphere at the center of each crater, and “impacts” which places a point above the floor of the center of the crater and “spheres” which creates spheres with radius equal to the projectile radius at the location of each crater. Default is “rings”.

• crater_size_scale_factor (FloatLike, optional) – A factor to scale the size of the craters in “point”, “impacts”, or “spheres” styles, which places the center point of the actor above the surface by its radius. Default is 1.0.

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

to_csv_file(crater_type='observed', craters=None, interval=None, **kwargs)

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

Parameters:

• crater_type (Literal[“observed”, “emplaced”], optional) – The type 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 crater_type 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_scc_file(crater_type='observed', craters=None, interval=None, **kwargs)

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

Parameters:

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

• craters (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 crater_type 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.

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.

Note

The Morphology component requires a Countinng component, so this property is set by the Morphology component on initialization, rather than by the Counting component itself.

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. doi: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. doi: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. doi: 10.1016/j.icarus.2019.02.021