# Craterstats-III
This is a Python reimplementation and extension of the Craterstats-II software, a tool to analyse and plot crater count data for planetary surface dating.
[Gallery](https://github.com/ggmichael/craterstats/blob/main/docs/gallery.md)
[Quick reference](https://github.com/ggmichael/craterstats/blob/main/docs/manual.md)
# Installation
Craterstats can be now installed as a standalone executable for Windows.
Download the latest version [here](https://github.com/ggmichael/craterstats/releases),
unzip to wherever you prefer, and double-click `create_desktop_shortcut.bat` to create a start-up icon.
Executables could be provided for MacOS and Linux but are not yet tested: ask if interested.
Alternative installation methods (including MacOS and Linux) [here](https://github.com/ggmichael/craterstats/blob/main/docs/alternative_install.md).
# Quick demonstration and try-out
After installation, the following command will produce a series of example output plots as in the gallery,
demonstrating the main features of the software. Plot image files are placed into the subfolder `demo/` of the
current folder.
craterstats -demo
Visit the [Gallery](https://github.com/ggmichael/craterstats/blob/main/docs/gallery.md) and copy some of the commands there to recreate the example plots.
# Usage
The program operates through the command line to produce output in the form of publication or presentation ready graphics, or tabulated analysis results for further processing.
There are two parts to creating a Craterstats plot:
1. Specify the type of plot and any characteristics which apply to the analysis as a whole, e.g. whether differential, cumulative or other data presentation; the chronology system, displayed axis ranges
2. Specify the data to be overplotted, and which chronology model evaluations should be applied to it
In the following example, the first items define characteristics for the whole plot: `-cs neukumivanov` specifies the chronology system, *Mars, Neukum-Ivanov (2001)*
(any unambiguous abbreviation is acceptable, e.g. ni2001 or marsNI), and the `-title Example plot` adds the chosen title.
The `-p` indicates the start of an overplot definition. Following this, the path to the data source is given: this will produce a simple data plot with the default binning, colour and plot symbol
(note that %sample% is a special path abbreviation to a craterstats installation directory - it's not needed for your own data). After the second `-p`,
an additional overplot is specified: this time, a poisson age evaluation for the diameter range 0.2–0.7 km. Parameters within an overplot definition are separated by a `,`.
craterstats -cs neukumivanov -p source=%sample%/Pickering.scc -p type=poisson,range=[.2,.7]
Sometimes it is useful to be able to specify the diameter range in terms of the plotted data points. Here we plot from the 8th to the 5th-from-last bins:
craterstats -cs neukumivanov -p source=%sample%/Pickering.scc -p type=poisson,range=[b8,b-5]
Or it may be easier to use a temporary bin overlay by adding the option `--bins`
craterstats -cs neukumivanov -p source=%sample%/Pickering.scc -p type=poisson,range=[b8,b-5] --bins
A plot image file is created in the current folder with the same name `Pickering.png`. The output path or name can be changed with the `-o` option. Different file types can be produced by giving the appropriate extension or with the `-f` option.
Supported types are: png, tif, pdf, svg, csv, stat (multiple types can be specified, e.g. `-f png csv`)
An additional text file is created with the name `Pickering.cs` which contains the command line parameters used to create the plot. Often it is convenient
to edit this file to modify the plot, which can then be regenerated with the shorter command:
craterstats -i Pickering.cs
Another file, `Pickering.csv`, gives dating results in tabular form for further analysis or transfer to a manuscript.
Preformatted ages and N(1) values, e.g. $\mu630^{+37}_{-35}$ Ma, are provided in latex and in MathML (copy and paste into Word with CTRL-SHIFT-V to get formatted expression).
Tables of chronology systems, equilibrium functions and epoch systems – which can be used with the `-cs`, `-ef` and `-ep` options – may be listed with the following command:
craterstats -lcs
These items may specifed using any unambiguous abbreviated form, e.g. `-cs ida`. Thus, `-ef lunar` or `-ef trask` will obtain the `Lunar equilibrium (Trask, 1966)` equilibrium function.
Tables of plot symbols and colours – which can be used with the `psym=` and `colour=` options – may be listed with the following command:
craterstats -lpc
and can likewise be specified by name or abbreviation, e.g. `psym=circle` or `psym=o` select a circle; `colour=green` or `col=gr` select green.
Differential plots are the default data presentation. To switch to a different kind, e.g. cumulative, add `-pr cumulative` or `-pr cml`.
Other possibilities are: relative (R), Hartmann, chronology, rate, sequential or uncertainty.
The complete set of options can be seen with:
craterstats --help
To simplify the construction of the command line, certain plot properties are persistent. If, for example, you specify `source=C:\tmp\area1.scc` in the first overplot, this becomes the default for subsequent overplots until you specify a different source file. This also applies to other properties where it is useful, including `binning=`, `colour=` and `psym=`.
Uncertainty plots for the evaluation of small-area, low-number counts, assuming a complete count of craters larger than d_min can be generated
(plots for k, measured error and measured/actual age - see Michael & Liu, 2025):
craterstats -pr uncertainty -cs n83 -d_min 0.15
as well as plots for comparing a sequence of events (Michael, Zhang et al., 2025):
craterstats.py -pr seq -ep Wilhelms -xrange 4.2 1 -legend fAca -p src=%sample%/e1.diam,range=[0.24,1.5],type=poisson -p src=%sample%/e2.diam,rng=[0.25,1.5] -p src=%sample%/e3.diam,rng=[0.24,1.5] -p src=%sample%/w1.diam,rng=[0.21,1.2],colour=red
# References
Explanations of concepts and calculations used in the software are given in publications below.
#### Standardisation of crater count data presentation
>Arvidson, R.E., Boyce, J., Chapman, C., Cintala, M., Fulchignoni, M., Moore, H., Neukum,
G., Schultz, P., Soderblom, L., Strom, R., Woronow, A., Young, R. [<i>Standard
techniques for presentation and analysis of crater size–frequency data.</i>](https://doi.org/10.1016/0019-1035%2879%2990009-5) Icarus 37, 1979.
#### Formulation of a planetary surface chronology model
>Neukum G., [<i>Meteorite bombardment and dating of planetary surfaces</i>](http://ntrs.nasa.gov/search.jsp?R=19840027189) (English translation, 1984). [<i>Meteoritenbombardement und Datierung planetarer Oberflächen</i>](http://www.planet.geo.fu-berlin.de/public/Neukum-Thesis%201983.pdf) (German original) Habilitation Thesis, Univ. of Munich, 186pp, 1983.
#### Resurfacing correction for cumulative fits; production function differential forms
>Michael G.G., Neukum G., [<i>Planetary surface dating from crater size-frequency distribution measurements: Partial resurfacing events and statistical age uncertainty.</i>](http://doi.org/10.1016/j.epsl.2009.12.041) Earth and Planetary Science Letters 294, 2010.
#### Differential fitting; binning bias correction; revised Mars epoch boundaries
>Michael G.G., [<i>Planetary surface dating from crater size-frequency distribution measurements: Multiple resurfacing episodes and differential isochron fitting.</i>](http://doi.org/10.1016/j.icarus.2013.07.004) Icarus 2013.
#### Poisson timing analysis; <i>μ</i>-notation
>Michael G.G., Kneissl T., Neesemann A., [<i>Planetary surface dating from crater size-frequency distribution measurements: Poisson timing analysis.</i>](https://doi.org/10.1016/j.icarus.2016.05.019) Icarus, 2016.
#### Poisson calculation for buffered crater count
>Michael G.G., Yue Z., Gou S., Di K., [<i>Dating individual several-km lunar impact craters from the rim annulus in region of planned Chang’E-5 landing Poisson age-likelihood calculation.</i>](https://doi.org/10.1016/j.epsl.2021.117031) EPSL 568, 2021.
#### Small-area and low number counts: age-area-uncertainty plots
>Michael G., Liu J., [<i>Planetary surface dating from crater size–frequency distribution measurements: interpretation of small-area and low number counts.</i>](https://doi.org/10.1016/j.icarus.2025.116489) Icarus 431, 2025.
#### Sequence probability and simultaneous formation
>Michael G., Zhang L., Wu C., Liu J. [<i>Planetary surface dating from crater size–frequency distribution measurements: Sequence probability and simultaneous formation. Did the close Chang’E-6 mare units form simultaneously?](https://doi.org/10.1016/j.icarus.2025.116644) Icarus 438, 2025.
Full references for specific chronology or other functions are listed with the function definitions in `config/functions.txt`.
A set of introductory slides to the methods and an earlier version of the software is [here](https://github.com/ggmichael/craterstats/tree/main/docs),
as well an update on this python version. Note that some command syntax has changed since the slides were produced.
Raw data
{
"_id": null,
"home_page": "https://github.com/ggmichael/craterstats",
"name": "craterstats",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "planetary, chronology, crater",
"author": "Greg Michael",
"author_email": "ggmichael@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/01/fc/ef42481d1a83b58957daf0303640784ed58a5a070e294e4f73da383a5190/craterstats-3.5.3.tar.gz",
"platform": null,
"description": "\n# Craterstats-III\n\nThis is a Python reimplementation and extension of the Craterstats-II software, a tool to analyse and plot crater count data for planetary surface dating.\n\n[Gallery](https://github.com/ggmichael/craterstats/blob/main/docs/gallery.md)\n\n[Quick reference](https://github.com/ggmichael/craterstats/blob/main/docs/manual.md)\n\n# Installation\n\nCraterstats can be now installed as a standalone executable for Windows. \nDownload the latest version [here](https://github.com/ggmichael/craterstats/releases), \nunzip to wherever you prefer, and double-click `create_desktop_shortcut.bat` to create a start-up icon.\n\nExecutables could be provided for MacOS and Linux but are not yet tested: ask if interested. \n\nAlternative installation methods (including MacOS and Linux) [here](https://github.com/ggmichael/craterstats/blob/main/docs/alternative_install.md).\n \n# Quick demonstration and try-out\n\nAfter installation, the following command will produce a series of example output plots as in the gallery, \ndemonstrating the main features of the software. Plot image files are placed into the subfolder `demo/` of the \ncurrent folder.\n \n craterstats -demo\n\nVisit the [Gallery](https://github.com/ggmichael/craterstats/blob/main/docs/gallery.md) and copy some of the commands there to recreate the example plots.\n\n\n# Usage\n\nThe program operates through the command line to produce output in the form of publication or presentation ready graphics, or tabulated analysis results for further processing.\n\nThere are two parts to creating a Craterstats plot:\n\n1. Specify the type of plot and any characteristics which apply to the analysis as a whole, e.g. whether differential, cumulative or other data presentation; the chronology system, displayed axis ranges\n\n2. Specify the data to be overplotted, and which chronology model evaluations should be applied to it\n\nIn the following example, the first items define characteristics for the whole plot: `-cs neukumivanov` specifies the chronology system, *Mars, Neukum-Ivanov (2001)* \n(any unambiguous abbreviation is acceptable, e.g. ni2001 or marsNI), and the `-title Example plot` adds the chosen title.\n\nThe `-p` indicates the start of an overplot definition. Following this, the path to the data source is given: this will produce a simple data plot with the default binning, colour and plot symbol\n(note that %sample% is a special path abbreviation to a craterstats installation directory - it's not needed for your own data). After the second `-p`, \nan additional overplot is specified: this time, a poisson age evaluation for the diameter range 0.2\u20130.7 km. Parameters within an overplot definition are separated by a `,`. \n\n craterstats -cs neukumivanov -p source=%sample%/Pickering.scc -p type=poisson,range=[.2,.7]\n\nSometimes it is useful to be able to specify the diameter range in terms of the plotted data points. Here we plot from the 8th to the 5th-from-last bins:\n\n craterstats -cs neukumivanov -p source=%sample%/Pickering.scc -p type=poisson,range=[b8,b-5]\n\nOr it may be easier to use a temporary bin overlay by adding the option `--bins`\n\n craterstats -cs neukumivanov -p source=%sample%/Pickering.scc -p type=poisson,range=[b8,b-5] --bins\n\nA plot image file is created in the current folder with the same name `Pickering.png`. The output path or name can be changed with the `-o` option. Different file types can be produced by giving the appropriate extension or with the `-f` option. \nSupported types are: png, tif, pdf, svg, csv, stat (multiple types can be specified, e.g. `-f png csv`)\n\nAn additional text file is created with the name `Pickering.cs` which contains the command line parameters used to create the plot. Often it is convenient \nto edit this file to modify the plot, which can then be regenerated with the shorter command:\n\n craterstats -i Pickering.cs\n\nAnother file, `Pickering.csv`, gives dating results in tabular form for further analysis or transfer to a manuscript. \nPreformatted ages and N(1) values, e.g. $\\mu630^{+37}_{-35}$ Ma, are provided in latex and in MathML (copy and paste into Word with CTRL-SHIFT-V to get formatted expression). \n \nTables of chronology systems, equilibrium functions and epoch systems \u2013 which can be used with the `-cs`, `-ef` and `-ep` options \u2013 may be listed with the following command:\n\n craterstats -lcs\n\nThese items may specifed using any unambiguous abbreviated form, e.g. `-cs ida`. Thus, `-ef lunar` or `-ef trask` will obtain the `Lunar equilibrium (Trask, 1966)` equilibrium function. \n\nTables of plot symbols and colours \u2013 which can be used with the `psym=` and `colour=` options \u2013 may be listed with the following command:\n\n craterstats -lpc\n\nand can likewise be specified by name or abbreviation, e.g. `psym=circle` or `psym=o` select a circle; `colour=green` or `col=gr` select green. \n\nDifferential plots are the default data presentation. To switch to a different kind, e.g. cumulative, add `-pr cumulative` or `-pr cml`. \nOther possibilities are: relative (R), Hartmann, chronology, rate, sequential or uncertainty.\n\nThe complete set of options can be seen with:\n\n craterstats --help\n\nTo simplify the construction of the command line, certain plot properties are persistent. If, for example, you specify `source=C:\\tmp\\area1.scc` in the first overplot, this becomes the default for subsequent overplots until you specify a different source file. This also applies to other properties where it is useful, including `binning=`, `colour=` and `psym=`.\n\nUncertainty plots for the evaluation of small-area, low-number counts, assuming a complete count of craters larger than d_min can be generated \n(plots for k, measured error and measured/actual age - see Michael & Liu, 2025):\n\n craterstats -pr uncertainty -cs n83 -d_min 0.15\n\nas well as plots for comparing a sequence of events (Michael, Zhang et al., 2025):\n\n craterstats.py -pr seq -ep Wilhelms -xrange 4.2 1 -legend fAca -p src=%sample%/e1.diam,range=[0.24,1.5],type=poisson -p src=%sample%/e2.diam,rng=[0.25,1.5] -p src=%sample%/e3.diam,rng=[0.24,1.5] -p src=%sample%/w1.diam,rng=[0.21,1.2],colour=red \n\n# References\n\nExplanations of concepts and calculations used in the software are given in publications below.\n\n#### Standardisation of crater count data presentation\n\n>Arvidson, R.E., Boyce, J., Chapman, C., Cintala, M., Fulchignoni, M., Moore, H., Neukum,\nG., Schultz, P., Soderblom, L., Strom, R., Woronow, A., Young, R. [<i>Standard\ntechniques for presentation and analysis of crater size\u2013frequency data.</i>](https://doi.org/10.1016/0019-1035%2879%2990009-5) Icarus 37, 1979.\n\n#### Formulation of a planetary surface chronology model\n\n>Neukum G., [<i>Meteorite bombardment and dating of planetary surfaces</i>](http://ntrs.nasa.gov/search.jsp?R=19840027189) (English translation, 1984). [<i>Meteoritenbombardement und Datierung planetarer Oberfl\u00e4chen</i>](http://www.planet.geo.fu-berlin.de/public/Neukum-Thesis%201983.pdf) (German original) Habilitation Thesis, Univ. of Munich, 186pp, 1983.\n\n#### Resurfacing correction for cumulative fits; production function differential forms\n\n>Michael G.G., Neukum G., [<i>Planetary surface dating from crater size-frequency distribution measurements: Partial resurfacing events and statistical age uncertainty.</i>](http://doi.org/10.1016/j.epsl.2009.12.041) Earth and Planetary Science Letters 294, 2010.\n\n#### Differential fitting; binning bias correction; revised Mars epoch boundaries\n\n>Michael G.G., [<i>Planetary surface dating from crater size-frequency distribution measurements: Multiple resurfacing episodes and differential isochron fitting.</i>](http://doi.org/10.1016/j.icarus.2013.07.004) Icarus 2013.\n\n#### Poisson timing analysis; <i>\u03bc</i>-notation\n\n>Michael G.G., Kneissl T., Neesemann A., [<i>Planetary surface dating from crater size-frequency distribution measurements: Poisson timing analysis.</i>](https://doi.org/10.1016/j.icarus.2016.05.019) Icarus, 2016.\n\n#### Poisson calculation for buffered crater count\n \n>Michael G.G., Yue Z., Gou S., Di K., [<i>Dating individual several-km lunar impact craters from the rim annulus in region of planned Chang\u2019E-5 landing Poisson age-likelihood calculation.</i>](https://doi.org/10.1016/j.epsl.2021.117031) EPSL 568, 2021.\n\n#### Small-area and low number counts: age-area-uncertainty plots\n>Michael G., Liu J., [<i>Planetary surface dating from crater size\u2013frequency distribution measurements: interpretation of small-area and low number counts.</i>](https://doi.org/10.1016/j.icarus.2025.116489) Icarus 431, 2025.\n\n#### Sequence probability and simultaneous formation\n>Michael G., Zhang L., Wu C., Liu J. [<i>Planetary surface dating from crater size\u2013frequency distribution measurements: Sequence probability and simultaneous formation. Did the close Chang\u2019E-6 mare units form simultaneously?](https://doi.org/10.1016/j.icarus.2025.116644) Icarus 438, 2025.\n\nFull references for specific chronology or other functions are listed with the function definitions in `config/functions.txt`.\n\nA set of introductory slides to the methods and an earlier version of the software is [here](https://github.com/ggmichael/craterstats/tree/main/docs),\nas well an update on this python version. Note that some command syntax has changed since the slides were produced.\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "BSD license",
"summary": "Craterstats - a tool to analyse and plot crater count data for planetary surface dating",
"version": "3.5.3",
"project_urls": {
"Homepage": "https://github.com/ggmichael/craterstats"
},
"split_keywords": [
"planetary",
" chronology",
" crater"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0acecd00c60444128de05e8e06d04f9a7fe1467a5100ae546b8291b5f9138f7b",
"md5": "56515723282aaf8f615aef6521e703f2",
"sha256": "500f730c6c5701a7f3dbe854e22c147caff295c34a40dc943c241bde0cc117ab"
},
"downloads": -1,
"filename": "craterstats-3.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "56515723282aaf8f615aef6521e703f2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 1233323,
"upload_time": "2025-08-26T06:52:02",
"upload_time_iso_8601": "2025-08-26T06:52:02.510509Z",
"url": "https://files.pythonhosted.org/packages/0a/ce/cd00c60444128de05e8e06d04f9a7fe1467a5100ae546b8291b5f9138f7b/craterstats-3.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "01fcef42481d1a83b58957daf0303640784ed58a5a070e294e4f73da383a5190",
"md5": "5ad773477d5ae029fb50b7748e2d2274",
"sha256": "86374c426b7c252440ad84f283fb91c6d54caeb00390cc42c44577537e3d8c29"
},
"downloads": -1,
"filename": "craterstats-3.5.3.tar.gz",
"has_sig": false,
"md5_digest": "5ad773477d5ae029fb50b7748e2d2274",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 1204332,
"upload_time": "2025-08-26T06:52:04",
"upload_time_iso_8601": "2025-08-26T06:52:04.049456Z",
"url": "https://files.pythonhosted.org/packages/01/fc/ef42481d1a83b58957daf0303640784ed58a5a070e294e4f73da383a5190/craterstats-3.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 06:52:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ggmichael",
"github_project": "craterstats",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "colorama",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "palettable",
"specs": []
},
{
"name": "progressbar2",
"specs": []
},
{
"name": "pyproj",
"specs": []
},
{
"name": "pyshp",
"specs": []
},
{
"name": "scipy",
"specs": [
[
">=",
"1.14"
]
]
},
{
"name": "shapely",
"specs": []
},
{
"name": "spherely",
"specs": []
}
],
"lcname": "craterstats"
}
JSON
