Craterpy API Documentation

CraterDatabase

class craterpy.classes.CraterDatabase(dataset: str | DataFrame, body: str, input_crs: str | CRS = 'default', units: str = 'm', *, lat_col: str | None = None, lon_col: str | None = None, rad_col: str | None = None, diam_col: str | None = None)[source]

Database of crater locations and shapefiles.

data

Dataframe containing the crater data.

Type:

geopandas.GeoDataFrame

lat

Crater latitudes.

Type:

pandas.Series

lon

Crater longitudes.

Type:

pandas.Series

rad

Crater radii.

Type:

pandas.Series

center

Crater centers.

Type:

geopandas.GeoSeries of shapely.geometry.Point objects

copy()[source]

Return a deepcopy of a CraterDatabase.

add_annuli(name, inner, outer, **kwargs)[source]

Generate annular geometries for each crater in database.

(slower but more precise than using global, Npolar and Spolar stereo)

Parameters:

  • name (str) – Name of geometry column.

  • inner (int or float) – Distance from center to inner edge of annulus in crater radii.

  • outer (int or float) – Distance from center to outer edge of annulus in crater radii.

Examples

>>> cdb.add_annuli("name", 1, 2)  # generates annuli from each crater rim to 1 crater radius beyond the rim.
>>> cdb.add_annuli("name", 1, 3)  # generates annuli from each crater rim to 1 crater diameter beyond the rim.
>>> cdb.add_annuli("name", 0, 1)  # generates a cicle capturing the interior of the crater rim.
add_circles(name='', size=1.0, **kwargs)[source]

Generate circluar geometries for each crater in database.

Parameters:

  • name (str) – Name of geometry column (default: circle_{size}).

  • size (int or float) – Radius of circle around each crater in crater radii (default: 1).

get_stats(rasters, regions, stats=('mean', 'std', 'count'), nodata=None, n_jobs=-2)[source]

Compute stats on polygons in a GeoDataFrame in parallel.

Parameters:

  • rasters (str, rasterio.DatasetReader, or dict of {str: str or rasterio.DatasetReader}) – Single raster path or open raster dataset, or a mapping of names to rasters. If a single raster is provided, it will be wrapped in a dict with key ‘_’.

  • regions (str or list of str) – Name or list of names of geometry columns in the crater database to use as regions.

  • stats (tuple of str, optional) – Statistics to compute for each raster-region combination. Default is (“mean”, “std”, “count”).

  • nodata (number, None, or dict of {str: number}, optional) – Nodata value to use for masking, or mapping of raster names to their nodata values. If None, no nodata masking is applied.

  • n_jobs (int, optional) – Number of parallel worker processes to use. Default is 1.

Returns:

DataFrame containing the original crater columns along with appended statistics columns for each raster and region combination.

Return type:

pandas.DataFrame

get_arrays(rasters, regions, nodata=None, n_jobs=-2)[source]

Return the masked pixel arrays underlying zonal stats for each region.

Like get_stats(), but returns the raw clipped raster values rather than computed statistics, so you can do your own analysis on the underlying data.

Parameters:

  • rasters (str, rasterio.DatasetReader, or dict of {str: str or rasterio.DatasetReader}) – Single raster path or open raster dataset, or a mapping of names to rasters.

  • regions (str or list of str) – Name or list of names of geometry columns in the crater database to use as regions.

  • nodata (number, None, or dict of {str: number}, optional) – Nodata value to use for masking, or mapping of raster names to their nodata values.

  • n_jobs (int, optional) – Number of parallel worker processes to use.

Returns:

DataFrame with the original crater columns plus one column per raster-region combination; each cell is the numpy.ma.MaskedArray of pixel values clipped to that geometry.

Return type:

pandas.DataFrame

plot(fraster=None, region='', ax=None, size=7.5, dpi=100, band=1, alpha=0.5, color='tab:blue', savefig=None, savefig_kwargs=None, **kwargs)[source]

Plot crater geometries.

Parameters:

  • fraster (str) – A path to raster image data to overlay craters on.

  • region (str) – The CraterDatabase region geometries to plot (default: crater rims).

  • ax (matplotlib.Axes) – Axes on which to plot data.

  • size (int, float, or 2-tuple) – Width of plot in inches or figsize tuple (width, height).

  • dpi (int) – Resolution of plot (dots/inch). Lower resolutions load faster.

  • band (int) – Band to use from fraster (default: first).

  • alpha (float) – Transparancy of the ROI geometries (0-1, default: 0.2).

  • color (str) – Color of the ROI geometries.

  • savefig (str, optional) – If provided, save the figure to this path.

  • savefig_kwargs (dict, optional) – Additional keyword arguments to pass to plt.savefig().

  • **kwargs – Keyword arguments supplied to GeoSeries.plot().

Returns:

ax

Return type:

matplotlib.Axes, cartopy.mpl.geoaxes.GeoAxes

to_geojson(filename, region=None, crs=None, keep_cols=None, keep_all=False)[source]

Export the crater database to GeoJSON file.

Parameters:

  • filename (str) – Path to output GeoJSON file.

  • region (str, optional) – Name of the region geometries to export. Default: crater centers point geometry.

  • crs (str or pyproj.CRS, optional) – Target coordinate reference system. If None, uses the current CRS.

  • keep_cols (list, optional) – List of column names to keep. If None, includes all original columns and excludes region geometries.

  • keep_all (bool, optional) – If True, keep hidden columns (e.g. all region geometries). Default is False. Only if keep_cols is None (specific columns requested take precedence).

to_crs(crs, inplace: bool = False)[source]

Convert the crater database to a different coordinate reference system.

Parameters:

  • crs (str or pyproj.CRS) – Target coordinate reference system.

  • inplace (bool, optional) – If True, modifies the current instance. If False, returns a new instance. Default is False.

Returns:

A new CraterDatabase instance with the converted data if inplace is False. Otherwise, modifies the current instance.

Return type:

CraterDatabase

plot_rois(fraster, region, index=9, grid_kw=None, savefig=None, savefig_kwargs=None, **kwargs)[source]

Plot CraterDatabase regions of interest (ROIs) clipped from raster.

Plots the first 9 craters supplied in index.

Parameters:

  • cdb (object) – A CraterDatabase with region defined, e.g., with add_annuli().

  • fraster (str) – A path to raster to clip rois from.

  • region (str) – The name of the CraterDatabase region geometry to plot.

  • index (int, pd.Index, or iterable, optional) – Specifies which ROIs to plot. If an integer, take first n, otherwise plot all given indices. Default is 9.

  • grid_kw (dict, optional) – Keyword args for gridlines (see matplotlib.axes.gridlines()).

  • savefig (str, optional) – If provided, save the figure to this path.

  • **kwargs (dict, optional) – Additional keyword arguments for customizing the plot. These can overwrite default settings for the raster image (cmap, vmin, vmax) or the ROI geometries (color, facecolor, lw, alpha, etc.).

Returns:

axes

Return type:

array of matplotlib.axes._subplots.AxesSubplot

Examples

>>> cdb = CraterDatabase(craters.csv, body="Moon")
>>> cdb.add_circles("crater", 1.5)
>>> cdb.plot_rois("moon.tif", region='crater', index=(1, 6, 9), alpha=0.2)
classmethod merge(cdb1, cdb2)[source]

Return a new CraterDatabase with duplicate crater rows and no ROIs.

Parameters:
Returns:

A new CraterDatabase instance with craters.

Return type:

CraterDatabase

Raises:

ValueError – If CraterDatabase objects are from different bodies.

classmethod read_shapefile(filename, body: str = 'Moon', units: str = 'm')[source]

Read crater data from a shapefile or GeoJSON file.

Parameters:

  • filename (str) – Path to the shapefile or GeoJSON file.

  • body (str, optional) – Planetary body, e.g. Moon, Vesta (default: None). If None, will attempt to determine from the file’s CRS.

  • units (str, optional) – Length units of radius/diameter, m or km (default: m).

Return type:

CraterDatabase

Notes

This method assumes the file was previously created by CraterDatabase.to_geojson() or has a compatible format with lat/lon coordinates and radius or diameter information.

CRS handling

Planetary coordinate reference systems for craterpy.

Standard planetocentric/planetographic CRS come from planetarypy.crs.body_crs(). This module adds the cases planetarypy does not produce: Vesta Claudia frames and the west-positive planetographic for bodies with no IAU ographic code (see _SPECIAL_CRS).

body_crs is always called with an integer NAIF id (_BODY_NAIF), never a name, to avoid planetarypy’s name-resolution path importing planetarypy.constants (which can trigger a one-time archive download).

craterpy.crs.get_crs(body: str, system: str | CRS = 'default') → CRS[source]

Retrieve a CRS for a body, or pass through any valid pyproj CRS.

Parameters:

  • body (str) – Planetary body name (case-insensitive), e.g. ‘Moon’, ‘mars’, ‘Vesta’.

  • system (str or pyproj.CRS) – A system alias (‘planetocentric’, ‘planetographic’, ‘default’, or a body-specific alias like ‘claudia_dp’), or any valid pyproj CRS object or string (e.g. an EPSG code), which is returned as-is.

Helper

This file contains various helper functions for craterpy

craterpy.helper.bbox2extent(bbox)[source]

Convert rasterio/geopandas bounding box to matplotlib extent.

Parameters:

bbox (array-like of float) – Bounding box in the form (minx, miny, maxx, maxy).

Returns:

Extent in the form (xmin, xmax, ymin, ymax).

Return type:

tuple of float

craterpy.helper.lon360(lon)[source]

Return longitude in range [0, 360).

Parameters:

lon (float or array-like) – Longitude values in degrees.

Returns:

Corresponding longitude values in the [0, 360] range.

Return type:

float or array-like

craterpy.helper.lon180(lon)[source]

Return longitude in range (-180, 180].

Parameters:

lon (float or array-like) – Longitude values in degrees.

Returns:

Corresponding longitude values in the (-180, 180] range.

Return type:

float or array-like

craterpy.helper.deg2pix(degrees, ppd)[source]

Return degrees converted to pixels at ppd pixels/degree.

Parameters:

  • degrees (float) – Angular distance in degrees.

  • ppd (float) – Pixels per degree resolution.

Returns:

Equivalent number of pixels.

Return type:

int

craterpy.helper.get_ind(value, array)[source]

Return closest index of a value from array.

Parameters:

  • value (float) – Target value to find.

  • array (array-like) – Array of values.

Returns:

Index of the nearest array element to value.

Return type:

int

craterpy.helper.km2deg(dist, mpp, ppd)[source]

Return dist converted from kilometers to degrees.

Parameters:

  • dist (float) – Distance in kilometers.

  • mpp (float) – Meters per pixel.

  • ppd (float) – Pixels per degree.

Returns:

Equivalent angular distance in degrees.

Return type:

float

craterpy.helper.km2pix(dist, mpp)[source]

Return dist converted from kilometers to pixels

Parameters:

  • dist (float) – Distance in kilometers.

  • mpp (float) – Meters per pixel.

Returns:

Equivalent number of pixels.

Return type:

int

craterpy.helper.greatcircdist(lat1, lon1, lat2, lon2, radius)[source]

Return great circle distance between two points on a spherical body.

Uses Haversine formula for great circle distances.

Parameters:

  • lat1 (float) – Latitude of the first point in degrees.

  • lon1 (float) – Longitude of the first point in degrees.

  • lat2 (float) – Latitude of the second point in degrees.

  • lon2 (float) – Longitude of the second point in degrees.

  • radius (float) – Radius of the sphere (same units for output).

Returns:

Great circle distance between the points.

Return type:

float

Examples

>>> greatcircdist(36.12, -86.67, 33.94, -118.40, 6372.8)
2887.259950607111
craterpy.helper.inglobal(lat, lon)[source]

True if lat and lon within global coordinates.

Default coords: lat in (-90, 90) and lon in (-180, 180). mode=’pos’: lat in (-90, 90) and lon in (0, 360).

Parameters:

  • lat (float) – Latitude in degrees.

  • lon (float) – Longitude in degrees.

Returns:

True if latitude is between -90 and 90 and longitude normalized to 0-360.

Return type:

bool

Examples

>>> inglobal(0, 0)
True
>>> inglobal(91, 0)
False
>>> inglobal(0, -50)
True
craterpy.helper.gen_annuli(centers: list, rads: list, inner: float, outer: float, crs, **kwargs)[source]

Generate annular polygons for a set of crater centers using a local azimuthal equidistant projection.

Each annulus is generated by projecting to a local coordinate system, buffering, and then transforming back to geodetic coordinates.

Processes in parallel with joblib.

Parameters:

  • centers (list of shapely.geometry.Point) – List of crater center points (latitude/longitude).

  • rads (list of float) – List of crater radii (in projection units).

  • inner (float) – Inner radius scaling factor (relative to crater radius).

  • outer (float) – Outer radius scaling factor (relative to crater radius).

  • crs (pyproj.CRS) – Geodetic coordinate reference system for output polygons.

  • **kwargs – Additional keyword arguments passed to annulus creation (e.g., n_jobs, nvert).

Returns:

List of annular polygons in geodetic coordinates.

Return type:

list of shapely.geometry.Polygon

craterpy.helper.create_single_annulus(center: Point, rad: float, inner: float, outer: float, geodetic_crs, **kwargs) → Polygon | MultiPolygon[source]

Create a geodetic annulus polygon for a single crater center.

Projects the center to a local azimuthal equidistant CRS, generates an annular buffer, and transforms the result back to the geodetic CRS. Handles antimeridian wrapping if needed.

Parameters:

  • center (shapely.geometry.Point) – Crater center point (latitude/longitude).

  • rad (float) – Crater radius in projection units.

  • inner (float) – Inner radius scaling factor (relative to crater radius).

  • outer (float) – Outer radius scaling factor (relative to crater radius).

  • geodetic_crs (pyproj.CRS) – Geodetic coordinate reference system for output polygon.

  • **kwargs – Additional keyword arguments for buffer creation.

Returns:

Annulus polygon in geodetic coordinates.

Return type:

shapely.geometry.Polygon

craterpy.helper.get_annular_buffer(point: Point, rad: float, inner: float, outer: float, **kwargs)[source]

Generate an annular buffer (ring-shaped polygon) around a point.

The annulus is defined by an outer and inner radius, both scaled by the crater radius. The polygon is created in a projected (flat) coordinate system.

Parameters:

  • point (shapely.geometry.Point) – Center point for the buffer (usually (0, 0) in local projection).

  • rad (float) – Crater radius in projection units.

  • inner (float) – Inner radius scaling factor (relative to crater radius).

  • outer (float) – Outer radius scaling factor (relative to crater radius).

  • **kwargs –

    nvertint, optional

    Number of vertices for the circular polygon (default: 32).

Returns:

Annular buffer polygon.

Return type:

shapely.geometry.Polygon

craterpy.helper.reproject_to_raster(geometries, raster)[source]

Return geometries reprojected to the raster’s CRS.

rasterstats samples a raster using the geometry coordinates as-is and does not reproject, so geometries must share the raster’s CRS. This is a no-op when the CRS already match or when either CRS is unknown.

Parameters:

  • geometries (geopandas.GeoSeries) – GeoSeries with a defined .crs.

  • raster (str or rasterio.DatasetReader) – Raster file path or open raster dataset.

Returns:

Geometries in the raster CRS (or unchanged if reprojection isn’t needed).

Return type:

geopandas.GeoSeries

craterpy.helper.compute_zonal_stats(geometries, raster, suffix: str = '', **kwargs) → DataFrame[source]

Compute zonal stats (e.g., mean, std, count) for each geometry in the raster.

See rasterstats.zonal_stats.

Parameters:

  • geometries (geopandas.GeoSeries) – GeoSeries of geometry objects (e.g., shapely.Polygons).

  • raster (str or rasterio.DatasetReader) – Raster file path or open raster dataset.

  • suffix (str, optional) – Suffix to append to output column names (default: “”).

  • **kwargs – Additional keyword arguments to pass to rasterstats.zonal_stats (e.g., stats, nodata).

Returns:

DataFrame containing computed statistics for each geometry.

Return type:

pandas.DataFrame

craterpy.helper.get_stats(gdf, rasters, regions, stats=('mean', 'std', 'count'), nodata=None, n_jobs=-2)[source]

Compute zonal stats on polygons in a GeoDataFrame for all rasters and regions in parallel.

Return a single DataFrame with columns <stat_raster_region> for all combinations.

Parameters:

  • gdf (geopandas.GeoDataFrame) – GeoDataFrame containing polygon regions as columns.

  • rasters (str, rasterio.DatasetReader, or dict of {str: str or rasterio.DatasetReader}) – Single raster path or open raster dataset, or a mapping of names to rasters.

  • regions (str or list of str) – Name or list of names of geometry columns in gdf to use as regions.

  • stats (tuple of str, optional) – Statistics to compute for each raster-region combination. Default: (“mean”, “std”, “count”).

  • nodata (number, None, or dict of {str: number}, optional) – Nodata value to use for masking, or mapping of raster names to their nodata values. If None, no nodata masking is applied.

  • n_jobs (int, optional) – Number of parallel worker processes to use. Default is 1.

Returns:

DataFrame containing the original crater columns along with appended statistics columns for each raster and region combination.

Return type:

pandas.DataFrame

craterpy.helper.compute_arrays(geometries, raster, suffix: str = '', **kwargs) → Series[source]

Return the masked pixel array clipped to each geometry from the raster.

See rasterstats.zonal_stats (raster_out=True).

Parameters:

  • geometries (geopandas.GeoSeries) – GeoSeries of geometry objects (e.g., shapely.Polygons).

  • raster (str or rasterio.DatasetReader) – Raster file path or open raster dataset.

  • suffix (str, optional) – Name to give the returned Series (default: “”).

  • **kwargs – Additional keyword arguments to pass to rasterstats.zonal_stats (e.g., nodata).

Returns:

Series of numpy.ma.MaskedArray, one clipped raster window per geometry.

Return type:

pandas.Series

craterpy.helper.get_arrays(gdf, rasters, regions, nodata=None, n_jobs=-2)[source]

Return the masked pixel arrays underlying zonal stats for all rasters and regions.

Each cell holds the numpy.ma.MaskedArray clipped to one geometry, so callers can compute anything beyond the built-in zonal statistics.

Parameters:

  • gdf (geopandas.GeoDataFrame) – GeoDataFrame containing polygon regions as columns.

  • rasters (str, rasterio.DatasetReader, or dict of {str: str or rasterio.DatasetReader}) – Single raster path or open raster dataset, or a mapping of names to rasters.

  • regions (str or list of str) – Name or list of names of geometry columns in gdf to use as regions.

  • nodata (number, None, or dict of {str: number}, optional) – Nodata value to use for masking, or mapping of raster names to their nodata values.

  • n_jobs (int, optional) – Number of parallel worker processes to use.

Returns:

DataFrame with one column per raster-region combination; each cell is the masked pixel array clipped to that geometry.

Return type:

pandas.DataFrame

craterpy.helper.tqdm_joblib(tqdm_object)[source]

Context manager to patch joblib to report into tqdm progress bar given as argument. See: https://stackoverflow.com/a/58936697

craterpy.helper.findcol(df, names, exact=False)[source]

Return first matching column in df matching a string given in names.

Case insensitive, ignores whitespace. Raises ValueError if none found.

Parameters:

  • df (pandas.DataFrame) – Dataframe object.

  • names (str or list of str) – Names to check against columns in df.

  • exact (bool) – Exact matches only (case-insensitive). Otherwise match on column substring (default: False).

Returns:

Name of the first matching column.

Return type:

str

Raises:

ValueError – If no matching column is found.

Examples

>>> df = pd.DataFrame({'Lat': [10, -20., 80.0],
                    'Lon': [14, -40.1, 317.2],
                    'Diam': [2, 12., 23.7]})
>>> findcol(df, ['Latitude', 'Lat'])
'Lat'
>>> findcol(df, ['Radius'])
Traceback (most recent call last):
...
ValueError: No column containing ['Radius'] found.
>>> findcol(df, 'diam')
'Diam'
craterpy.helper.find_rad_or_diam_col(df)[source]

Return the name of the radius or diameter column.

Parameters:

df (pandas.DataFrame) – DataFrame to search for radius/diameter column names.

Returns:

Name of the column representing radius or diameter.

Return type:

str

Raises:

ValueError – If no suitable column is found.

craterpy.helper.latlon_to_cartesian(lat, lon, radius)[source]

Convert lat, lon to cartesian (x, y, z)

Parameters:

  • lat (float or array-like) – Latitude in degrees.

  • lon (float or array-like) – Longitude in degrees.

  • radius (float) – Radius of the sphere.

Returns:

Cartesian coordinates (x, y, z).

Return type:

tuple of array-like or float

Examples

>>> latlon_to_cartesian(0, 0, 1)
(1.0, 0.0, 0.0)
craterpy.helper.merge(df1, df2, rbody=1737400.0, rtol=0.5, latcol='_lat', loncol='_lon', radcol='_radius_m')[source]

Spatial merge of craters in df1 and df2.

If a crater matches, keep lat, lon, rad and other col values from df1. If not a match, append to the end with lat, lon, rad from df2. Retains all columns from both dfs and fills in values if present.

Parameters:

  • df1 (pandas.DataFrame) – Left dataframe whose values will be preserved for any matches

  • df2 (pandas.DataFrame) – Right dataframe to merge

  • rbody (float) – Radius of the body in meters (default: Moon’s radius)

  • latcol (str) – Name of latitude column (default: ‘lat’)

  • loncol (str) – Name of longitude column (default: ‘lon’)

  • radcol (str) – Name of radius column (default: ‘rad’)

  • rtol (float) – Relative tolerance for radius matching (default: 0.5)

Returns:

Merged dataframe with lat/lon/rad from df1

Return type:

pandas.DataFrame