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 data to a GeoDataFrame or GIS-ready shapefile
extract zonal statistics associated with each crater in circlular or annular regions (rasterstats)
eliminate some pain points of planetary GIS analysis (antimeridian wrapping, projection conversions, etc.)

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

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

Examples

All craters on the Moon > 2km.

from craterpy import CraterDatabase
cdb = CraterDatabase('lunar_crater_database_robbins_2018.csv', "Moon", units="km")
cdb.plot(linewidth=0.25, alpha=0.25, color='gray')

Lunar craters plot

Define cicular/annular regions and export to GIS-ready shapefiles:

cdb.add_circles("craters", size=1)  # Crater interiors
cdb.add_annuli("ejecta", inner=1, outer=3)  # Annulus from rim to 2 radii past the rim (excludes interior)
cdb.craters.to_file("lunar_craters.geojson")
cdb.ejecta.to_file("lunar_ejecta.geojson")

Plot on a raster

cdb = CraterDatabase('vesta_craters.csv', "Vesta", units="m")
im = plt.imread('vesta.tif')
ax = cdb.plot(alpha=0.5, color='tab:green')
ax.imshow(im, extent=(-180, 180, -90, 90), cmap='gray')

Vesta map plot

Compute raster image statistics on each crater geometry.

import pandas as pd
df = pd.DataFrame({'Name': ["Orientale", "Copernicus", "Tycho"],
                    'Lat': [-19.9, 9.62, -43.35],
                    'Lon': [-94.7, -20.08, -11.35],
                    'Rad': [250., 48., 42.]})
cdb = CraterDatabase(df, "Moon", units="km")
# Define regions for central peak, crater floor, and rim (sizes in crater radii)
cdb.add_annuli("peak", 0, 0.1)
cdb.add_annuli("floor", 0.3, 0.6)
cdb.add_annuli("rim", 1.0, 1.2)
# DEM is a geotiff with elevation relative to reference Moon in meters
stats = cdb.get_stats("dem.tif", regions=['floor', 'peak', 'rim'], stats=['mean', 'std'])
print(stats)

Name	Lat	Lon	Rad	mean_floor	std_floor	mean_peak	std_peak	mean_rim	std_rim
Orientale	-19.90	-94.70	250.0	-2400.0	400.0	-2800.0	100.0	400.0	1100.0
Compernicus	9.62	-20.08	48.0	-3400.0	200.0	-3400.0	100.0	-0.0	200.0
Tycho	-43.35	-11.35	42.0	-3200.0	400.0	-2100.0	500.0	900.0	400.0

See the full craterpy documentation on Read the Docs.

Installation

With pip:

pip install craterpy

From the repo with poetry (for latest version & to contribute). First fork and clone the repository, then:

# Install craterpy with poetry
$ cd craterpy
$ poetry install
# Check installation version
poetry version
# Activate the venv 
$ poetry shell
$ which python
# Or open a Jupyter notebook
$ poetry run jupyter notebook

Note: Craterpy is currently only tested on Ubuntu and OS X. If you would like to use craterpy on Windows, check out the Windows Subsystem for Linux (WSL).

Trouble installing craterpy? Let us know on the issues board.

Documentation

Full API documentation and usage examples are available at readthedocs.

Contributing

There are two major ways you can help improve craterpy:

Bug Reporting and Feature Requests

You can report bugs or request new features on the issues board.

Contributing Directly

Want to fix a bug / implement a feature / fix some documentation? We welcome pull requests from all new contributors! You (yes you!) can help us make craterpy as good as it can be! See CONTRIBUTING.rst for details on how to get started - first time GitHub contributors welcome - and encouraged!

Citing craterpy

Craterpy is MIT Licenced and is free to use with attribution. Citation information can be found here.