|
| 1 | +# PyGMT |
| 2 | + |
| 3 | +> A Python interface for the Generic Mapping Tools |
| 4 | +
|
| 5 | +[Documentation (development version)](https://www.pygmt.org/dev) | [Contact](https://forum.generic-mapping-tools.org) | [TryOnline](https://github.com/GenericMappingTools/try-gmt) |
| 6 | + |
| 7 | +[](https://pypi.python.org/pypi/pygmt) |
| 8 | +[](https://anaconda.org/conda-forge/pygmt) |
| 9 | +[](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests.yaml) |
| 10 | +[](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml) |
| 11 | +[](https://github.com/astral-sh/ruff) |
| 12 | +[](https://app.codecov.io/gh/GenericMappingTools/pygmt) |
| 13 | +[](https://codspeed.io/GenericMappingTools/pygmt) |
| 14 | +[](https://pypi.python.org/pypi/pygmt) |
| 15 | +[](https://forum.generic-mapping-tools.org) |
| 16 | +[](https://doi.org/10.5281/zenodo.3781524) |
| 17 | +[](https://github.com/pyOpenSci/software-review/issues/43) |
| 18 | +[](https://github.com/GenericMappingTools/pygmt/blob/main/LICENSE.txt) |
| 19 | +[](CODE_OF_CONDUCT.md) |
| 20 | + |
| 21 | +<!-- doc-index-start-after --> |
| 22 | + |
| 23 | +## Why PyGMT? |
| 24 | + |
| 25 | +A beautiful map is worth a thousand words. To truly understand how powerful PyGMT is, play with it online on |
| 26 | +[Binder](https://github.com/GenericMappingTools/try-gmt)! For a quicker introduction, check out our |
| 27 | +[3 minute overview](https://youtu.be/4iPnITXrxVU)! |
| 28 | + |
| 29 | +Afterwards, feel free to look at our [Tutorials](https://www.pygmt.org/latest/tutorials), visit the |
| 30 | +[Gallery](https://www.pygmt.org/latest/gallery), and check out some |
| 31 | +[external PyGMT examples](https://www.pygmt.org/latest/external_resources.html)! |
| 32 | + |
| 33 | + |
| 34 | + |
| 35 | +## About |
| 36 | + |
| 37 | +PyGMT is a library for processing geospatial and geophysical data and making publication-quality |
| 38 | +maps and figures. It provides a Pythonic interface for the |
| 39 | +[Generic Mapping Tools (GMT)](https://github.com/GenericMappingTools/gmt), a command-line program |
| 40 | +widely used across the Earth, Ocean, and Planetary sciences and beyond. |
| 41 | + |
| 42 | +## Project goals |
| 43 | + |
| 44 | +- Make GMT more accessible to new users. |
| 45 | +- Build a Pythonic API for GMT. |
| 46 | +- Interface with the GMT C API directly using ctypes (no system calls). |
| 47 | +- Support for rich display in the Jupyter notebook. |
| 48 | +- Integration with the [PyData ecosystem](https://pydata.org/): `numpy.ndarray` or `pandas.DataFrame` for |
| 49 | + data tables, `xarray.DataArray` for grids, and `geopandas.GeoDataFrame` for geographical data. |
| 50 | + |
| 51 | +## Quickstart |
| 52 | + |
| 53 | +### Installation |
| 54 | + |
| 55 | +Simple installation using [mamba](https://mamba.readthedocs.org/): |
| 56 | + |
| 57 | +```bash |
| 58 | +mamba install --channel conda-forge pygmt |
| 59 | +``` |
| 60 | + |
| 61 | +If you use [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/index.html): |
| 62 | + |
| 63 | +```bash |
| 64 | +conda install --channel conda-forge pygmt |
| 65 | +``` |
| 66 | + |
| 67 | +For other ways to install `pygmt`, see the [full installation instructions](https://www.pygmt.org/latest/install.html). |
| 68 | + |
| 69 | +### Getting started |
| 70 | + |
| 71 | +As a starting point, you can open a [Python interpreter](https://docs.python.org/3/tutorial/interpreter.html) |
| 72 | +or a [Jupyter notebook](https://docs.jupyter.org/en/latest/running.html), and try the following example: |
| 73 | + |
| 74 | +``` python |
| 75 | +import pygmt |
| 76 | +fig = pygmt.Figure() |
| 77 | +fig.coast(projection="H10c", region="g", frame=True, land="gray") |
| 78 | +fig.show() |
| 79 | +``` |
| 80 | + |
| 81 | +For more examples, please have a look at the [Gallery](https://www.pygmt.org/latest/gallery/index.html) and |
| 82 | +[Tutorials](https://www.pygmt.org/latest/tutorials/index.html). |
| 83 | + |
| 84 | +## Contacting us |
| 85 | + |
| 86 | +- Most discussion happens [on GitHub](https://github.com/GenericMappingTools/pygmt). |
| 87 | + Feel free to [open an issue](https://github.com/GenericMappingTools/pygmt/issues/new) or comment on any open |
| 88 | + issue or pull request. |
| 89 | +- We have a [Discourse forum](https://forum.generic-mapping-tools.org/c/questions/pygmt-q-a) where you can ask |
| 90 | + questions and leave comments. |
| 91 | + |
| 92 | +## Contributing |
| 93 | + |
| 94 | +### Code of conduct |
| 95 | + |
| 96 | +Please note that this project is released with a |
| 97 | +[Contributor Code of Conduct](https://github.com/GenericMappingTools/.github/blob/main/CODE_OF_CONDUCT.md). |
| 98 | +By participating in this project you agree to abide by its terms. |
| 99 | + |
| 100 | +### Contributing guidelines |
| 101 | + |
| 102 | +Please read our [Contributing Guide](https://github.com/GenericMappingTools/pygmt/blob/main/CONTRIBUTING.md) |
| 103 | +to see how you can help and give feedback. |
| 104 | + |
| 105 | +### Imposter syndrome disclaimer |
| 106 | + |
| 107 | +**We want your help.** No, really. |
| 108 | + |
| 109 | +There may be a little voice inside your head that is telling you that you're not ready to be an open source |
| 110 | +contributor; that your skills aren't nearly good enough to contribute. What could you possibly offer? |
| 111 | + |
| 112 | +We assure you that the little voice in your head is wrong. |
| 113 | + |
| 114 | +**Being a contributor doesn't just mean writing code.** Equally important contributions include: writing or |
| 115 | +proof-reading documentation, suggesting or implementing tests, or even giving feedback about the project |
| 116 | +(including giving feedback about the contribution process). If you're coming to the project with fresh eyes, |
| 117 | +you might see the errors and assumptions that seasoned contributors have glossed over. If you can write any |
| 118 | +code at all, you can contribute code to open source. We are constantly trying out new skills, making mistakes, |
| 119 | +and learning from those mistakes. That's how we all improve and we are happy to help others learn. |
| 120 | + |
| 121 | +*This disclaimer was adapted from the* [MetPy project](https://github.com/Unidata/MetPy). |
| 122 | + |
| 123 | +## Citing PyGMT |
| 124 | + |
| 125 | +PyGMT is a community developed project. See the |
| 126 | +[AUTHORS.md](https://github.com/GenericMappingTools/pygmt/blob/main/AUTHORS.md) file on GitHub for a list of |
| 127 | +the people involved and a definition of the term "PyGMT Developers". Feel free to cite our work in your |
| 128 | +research using the following BibTeX: |
| 129 | + |
| 130 | +``` |
| 131 | +@software{ |
| 132 | + pygmt_2024_10578540, |
| 133 | + author = {Tian, Dongdong and |
| 134 | + Uieda, Leonardo and |
| 135 | + Leong, Wei Ji and |
| 136 | + Schlitzer, William and |
| 137 | + Fröhlich, Yvonne and |
| 138 | + Grund, Michael and |
| 139 | + Jones, Max and |
| 140 | + Toney, Liam and |
| 141 | + Yao, Jiayuan and |
| 142 | + Magen, Yohai and |
| 143 | + Tong, Jing-Hui and |
| 144 | + Materna, Kathryn and |
| 145 | + Belem, Andre and |
| 146 | + Newton, Tyler and |
| 147 | + Anant, Abhishek and |
| 148 | + Ziebarth, Malte and |
| 149 | + Quinn, Jamie and |
| 150 | + Wessel, Paul}, |
| 151 | + title = {{PyGMT: A Python interface for the Generic Mapping Tools}}, |
| 152 | + month = feb, |
| 153 | + year = 2024, |
| 154 | + publisher = {Zenodo}, |
| 155 | + version = {0.11.0}, |
| 156 | + doi = {10.5281/zenodo.10578540}, |
| 157 | + url = {https://doi.org/10.5281/zenodo.10578540} |
| 158 | +} |
| 159 | +``` |
| 160 | + |
| 161 | +To cite a specific version of PyGMT, go to our Zenodo page at <https://doi.org/10.5281/zenodo.3781524> |
| 162 | +and use the "Export to BibTeX" function there. It is also strongly recommended to cite the |
| 163 | +[GMT 6 paper](https://doi.org/10.1029/2019GC008515) (which PyGMT wraps around). Note that some modules |
| 164 | +like `dimfilter`, `surface`, and `x2sys` also have their dedicated citations. Further information for |
| 165 | +all these can be found at <https://www.generic-mapping-tools.org/cite>. |
| 166 | + |
| 167 | +## License |
| 168 | + |
| 169 | +PyGMT is free software: you can redistribute it and/or modify it under the terms of the |
| 170 | +**BSD 3-clause License**. A copy of this license is provided in |
| 171 | +[LICENSE.txt](https://github.com/GenericMappingTools/pygmt/blob/main/LICENSE.txt). |
| 172 | + |
| 173 | +## Support |
| 174 | + |
| 175 | +The development of PyGMT has been supported by NSF grants |
| 176 | +[OCE-1558403](https://www.nsf.gov/awardsearch/showAward?AWD_ID=1558403) and |
| 177 | +[EAR-1948603](https://www.nsf.gov/awardsearch/showAward?AWD_ID=1948602). |
| 178 | + |
| 179 | +## Related projects |
| 180 | + |
| 181 | +Other official wrappers for GMT: |
| 182 | + |
| 183 | +- [GMT.jl](https://github.com/GenericMappingTools/GMT.jl): A Julia wrapper for GMT. |
| 184 | +- [gmtmex](https://github.com/GenericMappingTools/gmtmex): A Matlab/Octave wrapper for GMT. |
| 185 | + |
| 186 | +Other non-official Python wrappers for GMT (not maintained): |
| 187 | + |
| 188 | +- [gmtpy](https://github.com/emolch/gmtpy) by [Sebastian Heimann](https://github.com/emolch) |
| 189 | +- [pygmt](https://github.com/ian-r-rose/pygmt) by [Ian Rose](https://github.com/ian-r-rose) |
| 190 | +- [PyGMT](https://github.com/glimmer-cism/PyGMT) by [Magnus Hagdorn](https://github.com/mhagdorn) |
| 191 | + |
| 192 | +<!-- doc-index-end-before --> |
| 193 | + |
| 194 | +## Minimum supported versions |
| 195 | + |
| 196 | +PyGMT has adopted [SPEC0](https://scientific-python.org/specs/spec-0000/) alongside the rest of the |
| 197 | +Scientific Python ecosystem, and therefore: |
| 198 | + |
| 199 | +- Support for Python versions be dropped 3 years after their initial release. |
| 200 | +- Support for core package dependencies (NumPy/Pandas/Xarray) be opped 2 years after their initial release. |
| 201 | + |
| 202 | +For the supported GMT versions as well as the minimum required versions of Python and core package |
| 203 | +dependencies, please see [Minimum Supported Versions](https://www.pygmt.org/dev/minversions.html). |
0 commit comments