<h1 align="center">
<strong>Craterpy:</strong><em> Impact crater data science in Python</em>
</h1>
<div align="center">
<!-- PYPI version -->
<a href="https://badge.fury.io/py/craterpy">
<img src="https://badge.fury.io/py/craterpy.svg"
alt="PYPI version" />
</a>
<!-- Code quality and testing (CI) -->
<a href="https://github.com/cjtu/craterpy/actions">
<img src="https://github.com/cjtu/craterpy/workflows/Code%20Quality%20Checks/badge.svg"
alt="Code Quality Checks" />
</a>
<!-- Test Coverage (codecov) -->
<a href="https://codecov.io/gh/cjtu/craterpy">
<img src="https://codecov.io/gh/cjtu/craterpy/branch/main/graph/badge.svg?token=9K567x0YUJ"
alt="Code Coverage" />
</a>
</div>
<div align="center">
<!-- Zenodo citation -->
<a href="https://zenodo.org/badge/latestdoi/88457986">
<img src="https://zenodo.org/badge/88457986.svg"
alt="Cite on Zenodo" />
</a>
<!-- ReadTheDocs -->
<a href="http://craterpy.readthedocs.io/en/latest/?badge=latest">
<img src="http://readthedocs.org/projects/craterpy/badge/?version=latest"
alt="Cite on Zenodo" />
</a>
<!-- Code of Conduct -->
<a href="CODE_OF_CONDUCT.md">
<img src="https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg"
alt="Contributor Covenant" />
</a>
<!-- Code Style -->
<a href="https://github.com/psf/black">
<img src="https://img.shields.io/badge/code%20style-black-000000.svg"
alt="Code Style: Black" />
</a>
</div>
# 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 crater detection algorithm (e.g. [PyCDA](https://github.com/AlliedToasters/PyCDA)), nor is it a crater count age dating tool (see [craterstats](https://github.com/ggmichael/craterstats)).
**Note:** *Craterpy is in development. We appreciate bug reports and feature requests on the [issues board](https://github.com/cjtu/craterpy/issues).*
## Quickstart
Install with `pip install craterpy` then follow the full worked example in the docs [Getting Started](https://craterpy.readthedocs.io/en/latest/getting_started.html).
## Demo
Quickly import tabluar crater data from a CSV and visualize it on a geotiff in 2 lines of code:
```python
from craterpy import CraterDatabase, sample_data
cdb = CraterDatabase(sample_data['vesta_craters.csv'], 'Vesta', units='m')
cdb.plot(sample_data['vesta.tif'], alpha=0.5, color='tab:green')
```
Clip and plot targeted regions around each crater from large raster datasets.
```python
cdb.add_circles('crater_rois', 3)
cdb.plot_rois(sample_data['vesta.tif'], 'crater_rois', range(1500, 1503))
```
Extract zonal statistics for crater regions of interest.
```python
# Import lunar crater and define the floor and rim
cdb = CraterDatabase(sample_data['moon_craters.csv'], 'Moon', units='km')
cdb.add_annuli("floor", 0.4, 0.8) # Crater floor (exclude central peak and rim)
cdb.add_annuli("rim", 0.9, 1.1) # Thin annulus at crater rim
# Compute summary statistics for every ROI see docs for supported stats
stats = cdb.get_stats(sample_data['moon_dem.tif'], regions=['floor', 'rim'], stats=['median'])
# Compute crater depth as rim elevation - floor elevation
stats['depth (m)'] = (stats.median_rim - stats.median_floor)
print(stats.head(3).round(2))
# Name Rad Lat Lon median_floor median_rim depth (m)
# Olbers D 50.015 10.23 -78.03 -1452.50 -1322.88 129.62
# Schuster 50.04 4.44 146.42 445.58 1976.97 1531.39
# Gilbert 50.125 -3.20 76.16 -2213.66 -731.64 1482.02
```
## Documentation
Full API documentation and usage examples are available at [ReadTheDocs](https://craterpy.readthedocs.io/).
## Installation
We recommend pip installing craterpy into a virtual environment, e.g. with `conda` or `venv`:
```bash
pip install craterpy
```
- **Note**: Craterpy is currently only tested on Ubuntu and OS X but may work on some versions of Windows.
## Contributing
There are two major ways you can help improve craterpy:
- Report bugs or request new features on the [issues](https://github.com/cjtu/craterpy/issues) board.
- Contributing directly. See [CONTRIBUTING.rst](https://github.com/cjtu/craterpy/blob/main/CONTRIBUTING.rst) for full details. First time open source contributors are welcome!
## Citing craterpy
Craterpy is [MIT Licenced](https://github.com/cjtu/craterpy/blob/master/LICENSE.txt) and is free to use with attribution. Citation information can be found [here](https://zenodo.org/badge/latestdoi/88457986).
Raw data
{
"_id": null,
"home_page": null,
"name": "craterpy",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "crater, data analysis, moon, planetary, python",
"author": null,
"author_email": "\"Christian J. Tai Udovicic\" <cj.taiudovicic@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e8/42/5df244c974ff162df24a83cb029c7f6734a2a4972c9f94216a82a0dfba87/craterpy-0.9.4.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\n <strong>Craterpy:</strong><em> Impact crater data science in Python</em>\n</h1>\n\n<div align=\"center\">\n <!-- PYPI version -->\n <a href=\"https://badge.fury.io/py/craterpy\">\n <img src=\"https://badge.fury.io/py/craterpy.svg\"\n alt=\"PYPI version\" />\n </a>\n <!-- Code quality and testing (CI) -->\n <a href=\"https://github.com/cjtu/craterpy/actions\">\n <img src=\"https://github.com/cjtu/craterpy/workflows/Code%20Quality%20Checks/badge.svg\"\n alt=\"Code Quality Checks\" />\n </a>\n <!-- Test Coverage (codecov) -->\n <a href=\"https://codecov.io/gh/cjtu/craterpy\">\n <img src=\"https://codecov.io/gh/cjtu/craterpy/branch/main/graph/badge.svg?token=9K567x0YUJ\"\n alt=\"Code Coverage\" />\n </a>\n</div>\n<div align=\"center\">\n <!-- Zenodo citation -->\n <a href=\"https://zenodo.org/badge/latestdoi/88457986\">\n <img src=\"https://zenodo.org/badge/88457986.svg\"\n alt=\"Cite on Zenodo\" />\n </a>\n <!-- ReadTheDocs -->\n <a href=\"http://craterpy.readthedocs.io/en/latest/?badge=latest\">\n <img src=\"http://readthedocs.org/projects/craterpy/badge/?version=latest\"\n alt=\"Cite on Zenodo\" />\n </a>\n <!-- Code of Conduct -->\n <a href=\"CODE_OF_CONDUCT.md\">\n <img src=\"https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg\"\n alt=\"Contributor Covenant\" />\n </a>\n <!-- Code Style -->\n <a href=\"https://github.com/psf/black\">\n <img src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"\n alt=\"Code Style: Black\" />\n </a>\n</div>\n\n# Overview\n\nCraterpy makes it easier to work with impact crater data in Python. Highlights:\n\n- convert a table of crater data to a GeoDataFrame or GIS-ready shapefile\n- extract zonal statistics associated with each crater in circlular or annular regions (rasterstats)\n- eliminate some pain points of planetary GIS analysis (antimeridian wrapping, projection conversions, etc.)\n\nNote: Craterpy is not a crater detection algorithm (e.g. [PyCDA](https://github.com/AlliedToasters/PyCDA)), nor is it a crater count age dating tool (see [craterstats](https://github.com/ggmichael/craterstats)).\n\n**Note:** *Craterpy is in development. We appreciate bug reports and feature requests on the [issues board](https://github.com/cjtu/craterpy/issues).*\n\n\n## Quickstart\n\nInstall with `pip install craterpy` then follow the full worked example in the docs [Getting Started](https://craterpy.readthedocs.io/en/latest/getting_started.html).\n\n## Demo\n\nQuickly import tabluar crater data from a CSV and visualize it on a geotiff in 2 lines of code:\n\n```python\nfrom craterpy import CraterDatabase, sample_data\n\ncdb = CraterDatabase(sample_data['vesta_craters.csv'], 'Vesta', units='m')\ncdb.plot(sample_data['vesta.tif'], alpha=0.5, color='tab:green')\n```\n\n\n\nClip and plot targeted regions around each crater from large raster datasets.\n\n```python\ncdb.add_circles('crater_rois', 3)\ncdb.plot_rois(sample_data['vesta.tif'], 'crater_rois', range(1500, 1503))\n```\n\n\n\nExtract zonal statistics for crater regions of interest.\n\n```python\n# Import lunar crater and define the floor and rim\ncdb = CraterDatabase(sample_data['moon_craters.csv'], 'Moon', units='km')\ncdb.add_annuli(\"floor\", 0.4, 0.8) # Crater floor (exclude central peak and rim)\ncdb.add_annuli(\"rim\", 0.9, 1.1) # Thin annulus at crater rim\n\n# Compute summary statistics for every ROI see docs for supported stats\nstats = cdb.get_stats(sample_data['moon_dem.tif'], regions=['floor', 'rim'], stats=['median'])\n\n# Compute crater depth as rim elevation - floor elevation\nstats['depth (m)'] = (stats.median_rim - stats.median_floor)\nprint(stats.head(3).round(2))\n\n# Name Rad Lat Lon median_floor median_rim depth (m)\n# Olbers D 50.015 10.23 -78.03 -1452.50 -1322.88 129.62\n# Schuster 50.04 4.44 146.42 445.58 1976.97 1531.39\n# Gilbert 50.125 -3.20 76.16 -2213.66 -731.64 1482.02\n```\n\n## Documentation\n\nFull API documentation and usage examples are available at [ReadTheDocs](https://craterpy.readthedocs.io/).\n\n\n## Installation\n\nWe recommend pip installing craterpy into a virtual environment, e.g. with `conda` or `venv`:\n\n```bash\npip install craterpy\n```\n- **Note**: Craterpy is currently only tested on Ubuntu and OS X but may work on some versions of Windows. \n\n## Contributing\n\nThere are two major ways you can help improve craterpy:\n\n- Report bugs or request new features on the [issues](https://github.com/cjtu/craterpy/issues) board.\n\n- Contributing directly. See [CONTRIBUTING.rst](https://github.com/cjtu/craterpy/blob/main/CONTRIBUTING.rst) for full details. First time open source contributors are welcome!\n\n## Citing craterpy\n\nCraterpy is [MIT Licenced](https://github.com/cjtu/craterpy/blob/master/LICENSE.txt) and is free to use with attribution. Citation information can be found [here](https://zenodo.org/badge/latestdoi/88457986).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Impact crater data science in Python.",
"version": "0.9.4",
"project_urls": {
"Bug Tracker": "https://github.com/cjtu/craterpy/issues",
"documentation": "https://readthedocs.org/projects/craterpy/",
"homepage": "https://github.com/cjtu/craterpy",
"repository": "https://github.com/cjtu/craterpy"
},
"split_keywords": [
"crater",
" data analysis",
" moon",
" planetary",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4423a49c1d9aea692076122269f5b2f68afb4eeb63483c15be12eb4e7630fc5b",
"md5": "af310b3106beeca4e043e38a3798e67e",
"sha256": "4e7c11752d5f503e00c670d34dd36c3f113f8799a594ef9e0e86b29979a84149"
},
"downloads": -1,
"filename": "craterpy-0.9.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af310b3106beeca4e043e38a3798e67e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 2165104,
"upload_time": "2025-08-19T22:33:33",
"upload_time_iso_8601": "2025-08-19T22:33:33.680463Z",
"url": "https://files.pythonhosted.org/packages/44/23/a49c1d9aea692076122269f5b2f68afb4eeb63483c15be12eb4e7630fc5b/craterpy-0.9.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e8425df244c974ff162df24a83cb029c7f6734a2a4972c9f94216a82a0dfba87",
"md5": "4b756a2ce4df4e21207c385049fad3bc",
"sha256": "71187adc6c16fa9cc7ea044df1481e4c8d7944344a2b6357921f967103830a17"
},
"downloads": -1,
"filename": "craterpy-0.9.4.tar.gz",
"has_sig": false,
"md5_digest": "4b756a2ce4df4e21207c385049fad3bc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 2325034,
"upload_time": "2025-08-19T22:33:34",
"upload_time_iso_8601": "2025-08-19T22:33:34.856535Z",
"url": "https://files.pythonhosted.org/packages/e8/42/5df244c974ff162df24a83cb029c7f6734a2a4972c9f94216a82a0dfba87/craterpy-0.9.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 22:33:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cjtu",
"github_project": "craterpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "craterpy"
}
JSON
