# PyGMT: Software Submission for Review
Submitting Author: Name (@github_handle)
Package Name: PyGMT
One-Line Description of Package: A Python interface for the Generic Mapping Tools
Repository Link: https://github.com/GenericMappingTools/pygmt
Version submitted:
Editor: TBD
Reviewer 1: TBD
Reviewer 2: TBD
Archive: TBD
Version accepted: TBD
---
## Description
- Include a brief paragraph describing what your package does:
PyGMT is a library for processing geospatial and geophysical data and making publication quality maps and figures. It provides a Pythonic interface for the Generic Mapping Tools (GMT), a command-line program widely used in the Earth Sciences.
## Scope
- Please indicate which [category or categories][PackageCategories] this package falls under:
- [ ] Data retrieval
- [ ] Data extraction
- [x] Data munging
- [ ] Data deposition
- [ ] Reproducibility
- [x] Geospatial
- [ ] Education
- [x] Data visualization*
\* Please fill out a pre-submission inquiry before submitting a data visualization package. For more info, see [notes on categories][NotesOnCategories] of our guidebook.
- Explain how the and why the package falls under these categories (briefly, 1-2 sentences):
- Data munging :gear:: Several data processing modules are available to work on tabular and grid data (https://www.pygmt.org/v0.4.0/api/index.html#data-processing) including functions like `blockmedian`, `surface`, `grdtrack`, etc
- Data visualization :world_map:: Plotting publication quality maps and figures is a strong point of PyGMT (https://www.pygmt.org/v0.4.0/api/index.html#plotting). There is a comprehensive set of tools for plotting 2D and 3D data, both geospatial and non-geospatial. It is also possible to add standard map elements like a `colorbar` or `legend`, and make multi-panel `subplot` figures.
- Geospatial :globe_with_meridians:: PyGMT is inherently a geospatial package that can handle both vector and raster data. Several map projections are supported (https://www.pygmt.org/v0.4.0/projections/index.html), and there is support for plotting shapefiles and GeoTiff/NetCDF files.
- Who is the target audience and what are scientific applications of this package?
- The primary target audience of PyGMT is the geoscience community, including anybody working on fields like Earth Observation, Geophysics, Oceanography, Seismology, Planetary Sciences, etc. The package offers a way for users to perform general geoprocessing tasks and create high quality illustrations of their results for posters or publications.
- Are there other Python packages that accomplish the same thing? If so, how does yours differ?
Yes, there are several geospatial Python packages such as:
- [`cartopy`](https://github.com/SciTools/cartopy) for plotting vector data ([`matplotlib`](https://github.com/matplotlib/matplotlib) based)
- [`geopandas`](https://geopandas.org/index.html) for working with vector data
- [`rasterio`](https://github.com/mapbox/rasterio), [`rioxarray`](https://github.com/corteva/rioxarray) and [`xarray-spatial`](https://github.com/makepath/xarray-spatial) for working with raster data
These tools are typically focused on one thing only (e.g. plotting maps, vector data, raster data). PyGMT allows users to **mix** vector and raster data easily, so that users can:
- **Produce** a map with points/lines/polygons and raster grids in the same plot, e.g. plot weather station points on top of a raster Digital Elevation Model, while including map elements (e.g. scalebar, compass arrow, [colorbar](https://www.pygmt.org/v0.4.0/api/generated/pygmt.Figure.colorbar.html), [legend](https://www.pygmt.org/v0.4.0/api/generated/pygmt.Figure.legend.html), [inset](https://www.pygmt.org/v0.4.0/api/generated/pygmt.Figure.inset.html) overview maps etc)
- **Extract** a series of elevation values along a transect line (vector) from a NetCDF/GeoTiff grid (raster) using [`grdtrack`](https://www.pygmt.org/v0.4.0/api/generated/pygmt.grdtrack.html)
- **Convert** a table of xyz points (vector) to a 2D grid (raster) using [`surface`](https://www.pygmt.org/v0.4.0/api/generated/pygmt.surface.html) via a spline-based interpolation method.
PyGMT integrates with the [PyData](https://pydata.org) ecosystem. It allows users to process and plot data stored in [NumPy](https://numpy.org) arrays, [Pandas](https://pandas.pydata.org) DataFrames, [Xarray](https://xarray.pydata.org/en/stable) DataArray/Datasets, [GeoPandas](https://geopandas.readthedocs.io/en/latest/) GeoDataFrames, as well as from standard file formats like CSV and GeoTiff/NetCDF files. There are also plans to integrate with other scientific libraries like ObsPy (https://github.com/GenericMappingTools/pygmt/issues/967) in the future.
However, PyGMT can only produce **static** plots unlike packages like [Geoviews](https://geoviews.org) which allow for interactive plotting (e.g. panning and zooming). It is also non-trivial to scale out data processing tasks and/or plotting of big datasets (>10GB) that don't fit in RAM to multiple processors/clusters as with libraries like [`dask-geopandas`](https://github.com/geopandas/dask-geopandas) because of limitations in the [GMT](https://www.generic-mapping-tools.org/) C package that PyGMT wraps around.
- If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussion, or `@tag` the editor you contacted:
https://github.com/pyOpenSci/software-review/issues/43
## Technical checks
For details about the pyOpenSci packaging requirements, see our [packaging guide][PackagingGuide]. Confirm each of the following by checking the box. This package:
- [ ] does not violate the Terms of Service of any service it interacts with.
- [ ] has an [OSI approved license][OsiApprovedLicense].
- [ ] contains a README with instructions for installing the development version.
- [ ] includes documentation with examples for all functions.
- [ ] contains a vignette with examples of its essential functions and uses.
- [ ] has a test suite.
- [ ] has continuous integration, such as Travis CI, AppVeyor, CircleCI, and/or others.
## Publication options
- [ ] Do you wish to automatically submit to the [Journal of Open Source Software][JournalOfOpenSourceSoftware]? If so:
<details>
<summary>JOSS Checks</summary>
- [ ] The package has an **obvious research application** according to JOSS's definition in their [submission requirements][JossSubmissionRequirements]. Be aware that completing the pyOpenSci review process **does not** guarantee acceptance to JOSS. Be sure to read their submission requirements (linked above) if you are interested in submitting to JOSS.
- [ ] The package is not a "minor utility" as defined by JOSS's [submission requirements][JossSubmissionRequirements]: "Minor ‘utility’ packages, including ‘thin’ API clients, are not acceptable." pyOpenSci welcomes these packages under "Data Retrieval", but JOSS has slightly different criteria.
- [ ] The package contains a `paper.md` matching [JOSS's requirements][JossPaperRequirements] with a high-level description in the package root or in `inst/`.
- [ ] The package is deposited in a long-term repository with the DOI:
*Note: Do not submit your package separately to JOSS*
</details>
## Are you OK with Reviewers Submitting Issues and/or pull requests to your Repo Directly?
This option will allow reviewers to open smaller issues that can then be linked to PR's rather than submitting a more dense text based review. It will also allow you to demonstrate addressing the issue via PR links.
- [x] Yes I am OK with reviewers submitting requested changes as issues to my repo. Reviewers will then link to the issues in their submitted review.
## Code of conduct
- [ ] I agree to abide by [pyOpenSci's Code of Conduct][PyOpenSciCodeOfConduct] during the review process and in maintaining my package should it be accepted.
**P.S.** *Have feedback/comments about our review process? Leave a comment [here][Comments]
## Editor and Review Templates
[Editor and review templates can be found here][Templates]
[PackagingGuide]: https://www.pyopensci.org/contributing-guide/authoring/index.html#packaging-guide
[PackageCategories]: https://www.pyopensci.org/contributing-guide/open-source-software-peer-review/aims-and-scope.html?highlight=data#package-categories
[NotesOnCategories]: https://www.pyopensci.org/contributing-guide/open-source-software-peer-review/aims-and-scope.html?highlight=data#notes-on-categories
[JournalOfOpenSourceSoftware]: http://joss.theoj.org/
[JossSubmissionRequirements]: https://joss.readthedocs.io/en/latest/submitting.html#submission-requirements
[JossPaperRequirements]: https://joss.readthedocs.io/en/latest/submitting.html#what-should-my-paper-contain
[PyOpenSciCodeOfConduct]: https://www.pyopensci.org/contributing-guide/open-source-software-peer-review/code-of-conduct.html?highlight=code%20conduct
[OsiApprovedLicense]: https://opensource.org/licenses
[Templates]: https://www.pyopensci.org/contributing-guide/appendices/templates.html
[Comments]: https://github.com/pyOpenSci/governance/issues/8