cjtu / craterpy

A python library for impact crater data science

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.

craterpy's Issues

Add Continuous Integration for OS X

Currently only testing on Windows (Appveyor) and Linux (Travis). Add OS X

greatcircdist breaking for abs(longitude) > 90

ValueError: Latitude or longitude out of bounds.

generated when the absolute value of the first longitude in the input pair is >90 deg.
Example: greatcircdist(10., -95., 50.,75, 1737)

Fix .environment.yml on OSX

Installing from provided .environment.yml on OSX throws error; attached version works (rename to .environment.yml using mv environment.txt .environment.yml)
environment.txt

Get Test Coverage Up

Test coverage is currently very low. Let's get it up to 90% or more and keep it there

Work on OSS Project Checklist

OSS Project Checklist

A checklist from https://github.com/scriptnull/oss-checklist to be a guide future open-source development of craterpy.

Pre-checks

• Able to explain your project in a tweet ?
• Choose a name for the project
• Check if domain name / App name is available ?
• List and learn tools required for the project
• Prepare mock-up and one page design document, if needed to explain to collaborators
• List previous / similar implementations and learn from them
• Start a blog post to document the journey ( if time permits ) Mention idea + helpful resources.
• Ask if project could be solved in a modular way by dividing into sub-problems and creating a separate project for the sub-problems.

Project Creation

• Create a Repository in Github
• Create a README.rst (check below for more)
• Create a LICENSE file (choose one before)
• Create a CONTRIBUTING.rst
• Create a .gitignore

README.md Checklist

• Title
• Logo
• Badges
• Description
• Prerequisite for using software ( if any )
• Install
• Example Usage
• Screenshots and GIFs
• Contributors
• Attributions ( mention 3rd party libs used etc. )

Coding Phase

• Install required developer tools
  • Compiler
  • Linter
  • Build Tools
  • Other
• Organize files and folders that will help readers to find code easily
• Basic code complete
• Write tests and keep watch on code coverage
• Setup CI
  • Setup CI on Linux (Travis CI)
  • Setup CI on Windows (AppVeyor)
  • Setup CI on OS X (tricky with anaconda, explore further)
• Host the documentation of the code on ReadTheDocs
• Use Github issues ( or other tools ) for tracking backlogs
• Encourage OSS culture by having labels like "help wanted" "easy-to-contribute" etc.
• Contribute to other OSS projects on which the current project is dependent on ( if possible )
  • File bug reports
  • Improve docs
  • Suggest feature
  • Learn by reading code

Release Phase

• Package software in CI or manually in local
• Publish in registries (PyPI, conda-forge, etc.)
• Create the release version, description, link for downloading the release etc. in release page ( example: Github release page)

Post-release

• Publish the blog post
• Tweet
• Hackernews
• Product Hunt
• Send PR to awesome-* github repository
• Reddit
• Hashnode
• Linkedin
• Edit Wikipedia pages (if related)
• Prepare slides and give talks (if possible)

Fix README

• Code snippet (syntax error at index, need to be run inside data folder)
• Tutorial link
• Clean up quick installation section, should not need to install dependencies manually as pip install should handle that
• Create section for building from source (for contributors), using environment.yml to install dependencies, running tests
• Rename "Citing ACERIM" to "Citing craterpy"

Custom Exceptions

Replace current exceptions like "ValueError" or "ImportError" with custom exceptions defined in a file called exceptions.py. They should have useful names and inherit from the Exception they replace

Improve Docstrings

Docstrings

Docstings are important for auto-building API docs for craterpy. We use the numpy style guide which has a great summary here

TODO:

• Give all modules, classes, functions, and methods a docstring (min 1 line description).
• "Attributes" and "methods" sections for all classes
• "Parameters" section for all functions, methods (where applicable)
• "Returns" section for all functions, methods (where applicable)
• "Raises" section if Exceptions are raised
• "Examples" section and update existing examples

Investigate releasing on conda-forge

As noted in (#8), quick installation is bulky right now due to gdal dependency issues that arise with pip that are mitigated by conda.

1. What would it take to get craterpy hosted on conda-forge?
2. Would this simplify installation instructions (e.g., would dependencies be correctly built with conda install -c conda-forge craterpy)?

Teach SSXG lab how to contribute to craterpy

Demo for spooky Haloween lab meeting