PyGMT: A Python interface for the Generic Mapping Tools

**This note is no longer updated since we have moved to Google Docs.** # PyGMT: A Python interface for the Generic Mapping Tools ## Abstract ## Plain Language Summary ## 1. Introduction The Generic Mapping Tools (GMT) is a widely-used toolset for visualizing and performing operations on geospatial data, with a focus on the Earth science community. Originally published in 1988 by Paul Wessel and Walter Smith, GMT has had numerous releases, up to the most recent major one, GMT 6, which was released in 2019. The software is written in the C programming language, and included an Application Program Interface (API) beginning with the 2013 release of GMT 5. The Python programming language was originally created in 1991. Since then, it has become a popular tool for data analytics and visualization. The GMT/Python API (PyGMT) was created to integrate the GMT capabilities with the tools in the Python data ecosystem. ## 2. Philosophy and Design The GMT syntax is not easily readable to those unfamiliar with its format, with many of the settings controlled by a flagged letter followed by the desired information. PyGMT aims to use Python's classes and functions to create more intuitive and readable code while still producing the same visualizations and figures as GMT. Both GMT and PyGMT are able to import flat files to work with gridded and tabular data, but PyGMT extends this to work with common Python data structures, such as numpy arrays, pandas DataFrames, and xarray DataArrays. Creating a figure in GMT typically involves calling multiple commands that can additively change the plot for the given session. To emulate this feature, PyGMT plots are created using the ``Figure`` class, creating a Python object that can be used to call plotting functions. The ``Figure`` object is also used when displaying a figure in a notebook environment, or saving it as an image. In addition to the plotting functions, PyGMT has wrapped some of GMT's mathetmatical operations. GMT typically writes its outputs to a file, and while this capability is retained for PyGMT, outputs can also be stored in standard Python data structures. ## 3. Integration with the PyData ecosystem > Comparison to other python plotting libraries with a focus on mapping like cartopy (built on top of matplotlib) or geopandas. > * ``numpy.ndarray`` or ``pandas.DataFrame`` for data tables > * ``xarray.DataArray`` for grids > * ``geopandas.GeoDataFrame`` for geographical data ## 4. Examples > [name=willschlitzer] Are we looking for producing actual figures for this HackMD script, or is that for later in the process? I can produces figures if need be, but not sure what we're prioritizing. ## 5. Community > * Summary of contribution/community guidelines/philosophy? > * Outreach: > * SciPy sprints > * Remote Online Sessions for Emerging Seismologists units > * Other workshops (others please add, I know there are lots!) > * Diversity and inclusion: Where we're at and our goals moving forward ## 6. Future development ## Acknowledgments ## References - Wessel, P., & Smith, W.H.F. (1991), Free software helps map and display data, *Eos Trans. AGU*, 72( 41), 441–446, https://doi.org/10.1029/90EO00319. - Wessel, P., Luis, J.F., Uieda, L., Scharroo, R., Wobbe, F., Smith, W.H.F., & Tian, D. (2019), The Generic Mapping Tools version 6, *Geochemistry, Geophysics, Geosystems*, 20(11), 5556-5564, https://doi.org/10.1029/2019GC008515.