Craterpy: Impact crater data science in Python

Overview

Craterpy makes it easier to work with impact crater data in Python. Highlights:

• convert a table of crater coordinates and sizes to a GeoDataFrame or GIS-ready shapefile
• extract zonal statistics associated with each crater in circlular or annular regions (with rasterstats)
• eliminate some pain points of planetary GIS analysis (antimeridian wrapping, projection conversions, etc.)
• supports all roughly spherical cratered bodies (examples)

Note: Craterpy is not a crater detection algorithm (e.g. PyCDA), nor is it a crater count age dating tool (see craterstats).

Note: Craterpy is in development. We appreciate bug reports and feature requests on the issues board.

Quickstart

Install with pip install craterpy then see example usage at Getting Started.

Demo

Quickly import tabluar crater data from a CSV and visualize it on a geotiff in 2 lines of code:

from craterpy import CraterDatabase, sample_data as sd

cdb = CraterDatabase(sd['vesta_craters_km.csv'], 'Vesta', units='km')
cdb.plot(sd['vesta.tif'], alpha=0.5, color='tab:green', savefig='readme_vesta_cdb.png')

Clip and plot targeted regions around each crater from large raster datasets.

cdb.add_circles('crater_roi', 1.5)
cdb.plot_rois(sd['vesta.tif'], 'crater_roi', range(3, 12))

Extract zonal statistics for crater regions of interest.

import pandas as pd
from craterpy import CraterDatabase, sample_data as sd
df = df = pd.read_csv(sd["moon_craters_km.csv"])
cdb = CraterDatabase(df[df["Diameter (km)"] < 60], "Moon", units="km")

# Define regions for crater floor, rim (sizes in crater radii)
cdb.add_annuli("floor", 0.4, 0.6)  # crater floor, excluding possible central peak
cdb.add_annuli("rim", 0.99, 1.01)  # thin annulus at rim

# Pull statistics from a Lunar Digital Elevation Model (DEM) GeoTiff
stats = cdb.get_stats(sd["moon_dem.tif"], regions=['floor', 'rim'], stats=['mean'])

# Use mean elevations to compute depth (rim to floor)
stats['crater_depth (m)'] = (stats.mean_rim - stats.mean_floor)
print(stats.head().to_string(float_format='%.1f', index=False))

#  Diameter (km)  Latitude  Longitude  mean_floor  mean_rim  crater_depth (m)
#           60.0      19.4     -146.5      6070.0   10792.9            4722.9
#           60.0      44.2      145.3      -976.4    3114.0            4090.4
#           60.0     -43.6       -7.5     -3617.5     186.8            3804.4
#           60.0      -9.6      134.7      1843.4    6127.9            4284.4
#           59.9     -25.3        2.4     -2634.2    -945.0            1689.1

Cite This Repository

If you use this project in your research, please cite the JOSS paper as below:

Tai Udovicic et al., (2025). Craterpy: Impact crater data science in Python. Journal of Open Source Software, 10(113), 8663, https://doi.org/10.21105/joss.08663

@article{craterpy2025, 
doi = {10.21105/joss.08663},
author = {Tai Udovicic, Christian J. and Essunfeld, Ari and Costello, Emily S.},
title = {Craterpy: Impact crater data science in Python},
journal = {Journal of Open Source Software},
url = {https://doi.org/10.21105/joss.08663},
year = {2025},
publisher = {The Open Journal},
volume = {10},
number = {113},
pages = {8663}}

Documentation

Full API documentation and usage examples are available at ReadTheDocs.

Installation

We recommend pip installing craterpy into a virtual environment, e.g. with conda or venv:

pip install craterpy

• Note: Craterpy is tested on latest long-term support versions of Windows, OS X and Ubuntu, and Python version 3.10 and up.

Contributing

There are two major ways you can help improve craterpy:

• Report bugs or request new features on the issues board.

• Contributing directly. See CONTRIBUTING.rst for full details. First time open source contributors are welcome!