Craterpy: Impact crater data science in Python.

Overview

Craterpy simplifies the extraction and statistical analysis of impact craters in planetary datasets. It can:

• work with tables of crater data in Python (using pandas)
• load and manipulate planetary image data in Python (using rasterio)
• extract, mask, filter, and compute stats on craters located in planetary imagery
• plot crater regions of interest

Craterpy currently only supports simple cylindrical images and requires you to provide a table of crater locations and sizes (e.g. it isn't a crater detection program). See the example below!

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

Example

Craterpy in action:

import pandas as pd
from craterpy import dataset, stats
df = pd.DataFrame({'Name': ["Orientale", "Langrenus", "Compton"],
                    'Lat': [-19.9, -8.86, 55.9],
                    'Lon': [-94.7, 61.0, 104.0],
                    'Rad': [147.0, 66.0, 82.3]})
moon = dataset.CraterpyDataset("moon.tif")
stat_df = cs.ejecta_stats(df, moon, 4, ['mean', 'median', 'std'], plot=True)

stats_df.head()

New users should start with the Jupyter notebook tutorial for typical usage with examples. See also craterpy documentation on Read the Docs.

Note: This package currently only accepts image data in simple-cylindrical (Plate Caree) projection. If your data is in another projection, please reproject it to simple-cylindrical before importing it with craterpy. If you would like add reprojection functionality to craterpy, consider Contributing.

Installation

With pip:

pip install craterpy
python -c "import craterpy; print(craterpy.__version__)"

In a new conda environment:

# Create and activate a new conda environment called "craterpy"
conda create -n craterpy python=3.9
conda activate craterpy

# Install craterpy with pip
pip install craterpy
python -c "import craterpy; print(craterpy.__version__)"

With git and poetry (for latest version & development):

# Clone this repository
$ cd ~
$ git clone https://github.com/cjtu/craterpy.git

# Enter the repository
$ cd craterpy

# Configure poetry
poetry config virtualenvs.create true --local
poetry config virtualenvs.in-project true --local

# Install craterpy with poetry
$ poetry install

# Check installation
poetry version

# Either open a Jupyter server
$ poetry run jupyter notebook

# Or activate the venv from your Python editor of choice
# The venv is path is ~/craterpy/.venv/bin/python

On Windows (see rasterio installation for Windows):

• Note: Craterpy is tested on Ubuntu and OS X. If you would like to use craterpy on Windows, we recommend getting the Windows Subsystem for Linux (WSL) and installing into a Linux distribution. However, the following may also work for a native Windows installation and depends on a working installation of rasterio from pre-compiled binaries (see link above).

# Windows requires gdal binaries specific to the OS (32/64-bit) and python version
# First download the rasterio and GDAL binaries for your system (link above)
# If rasterio imports with no error then craterpy should be pip installable
pip install GDAL-X.Y.Z-...-win.whl
pip install rasterio-X.Y.Z-...-win.whl
python -c "import rasterio"
pip install craterpy
python -c "import craterpy; print(craterpy.__version__)"

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

Dependencies

Craterpy requires python >3.7.7 and is tested on Ubuntu and OS X. It's core dependencies are:

• rasterio
• pandas
• numpy
• matplotlib

Documentation

Full API documentation is 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.

Contact

If you have comments/question/concerns or just want to get in touch, you can email Christian at [email protected] or follow @TaiUdovicic on Twitter.