PyGMT: Software Submission for Review

# 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