1. GMT / PyGMT Introduction and Installation#

1.1. What is [GMT][GMT-link]?#

Generic Mapping Tools, or [GMT][GMT-link] for short, is a software package for geographical mapping and other related tasks. The software was initiated in 1988 by Pål (Paul) Wessel and Walter H. F. Smith, who were graduate students at Lamont-Doherty Earth Observatory. The first version of GMT was released in 1991 [^1] and received a lot of positive feedback on how useful and powerful the package could be, which has motivated two authors and the whole GMT development team to continue the project. More than 30 years later, in November 2019, the development team released the sixth edition of GMT [^2], which would continue to take a major role in geographical mapping. Now GMT is a popular toolbox for plotting scientific data for academic fields such as geophysics or oceanography.

As a “generic” mapping toolbox, GMT is of course capable of making different types of scientific plots using its built-in commands. However, what really makes this package so powerful is that GMT is very good at processing geographical data and visualizing them in the right way. GMT includes a lot of GIS algorithms, and a user just needs to enter a few console commands for making some beautiful and high-resolution maps. These maps support multiple formats, including vectorized files such as EPS and PDF, allowing users to make further edits with ease.

1.2. And what is [PyGMT][PyGMT-link]?#

[PyGMT][PyGMT-link] is essentially a “Pythonized GMT package.” PyGMT rewraps the GMT so one can access all GMT tools as a Python module. In addition to attracting more potential users, the long-term of PyGMT is to build a Python ecosystem for scientific data analysis, together with other data science modules in Python. As of now, PyGMT already supports some data formats found in Numpy, Pandas, and Xarray, and can interactively draw your data using the Jupyter environment. [^3]

PyGMT is entirely a community-based project. Its latest version (0.7.0) was released in July 2022. If you are interested in contributing to and developing the project, I encourage you to go to the official website and forum of PyGMT and get involved.

1.3. Should I use GMT?#

If you need to make some sort of map, either a global topography or a street map around your home, GMT or PyGMT has got you covered. With that said, GMT suits better for scientific mapping because all the data and observations can be easily processed by various built-in commands. Also, you can show your results with other GIS data but with no pain. Here I highly recommend GMT for people who want to perform any tasks listed below:

  1. Show tons of data on a map, like precipitation, faults and seismicity map, bathymetry, global volcano distribution, etc.

  2. Make maps pretty often or update them frequently. You probably would feel that the fancy and clumsy graphic interface of GIS software always slows down your working efficiency. Learning how to plot using command-line tools can improve your work and save lots of your time.

  3. Need to show the results of geospatial data analysis interactively or in real time. You can get two jobs done at once – data analysis and visualization – by running a GMT or PyGMT script.

The only issue with getting a swing of GMT is that you need to write a script consisting of some code (GMT commands) to get GMT to work. For those who never used a terminal console, a steep learning curve would be expected. Fortunately, the GMT built-in commands are not that hard compared to many other standard console commands, and in most cases, we do not need the non-GMT commands for manipulating data. That means as long as we have learned the basics of the command-line interface, we will be ready to master the art of GMT. Please go to Basic Concepts and Terms for more details. Besides, if you have used or are using Python programming language, you can just start with PyGMT to speed up your learning efficiency.

1.4. About the tutorials#

I am a research scientist in geophysics and planetary sciences with more than 10 years of GMT experience. I always try hard to find well-organized and clear GMT tutorials, which sometimes makes me frustrated and spend more time learning every tool. So I decided to write down some of my scripts and thoughts and maybe write such a tutorial myself. My goal is to help beginners learn step-by-step by following the content of each chapter. If you are already a GMT veteran, I hope this tutorial can serve you as a reference book whenever you would like to look for answers to some specific questions.

Each chapter here is arranged in order by its difficulty. The first few chapters introduce basic knowledge for people who have zero experience of command lines. Later, the content shifts to some advanced script workflows. I believe the best way to learn GMT is to do it yourself rather than any online resources and these tutorials. With this in mind, you can find everything you need for making the map in each chapter, including the data and scripts. Feel free to download them and make a map that even surpasses the one I made!

1.5. How to install GMT#

There are many ways to install GMT and PyGMT. I recommend using the conda package manager to install them. For other ways of installation, please go to the GMT or PyGMT official websites.

  1. Firstly you need to install Anaconda. Anaconda is cross-platform package manager software for scientific data analysis. You can download the installation file based on your operating system and install Anaconda. The Conda package manager will be installed together with Anaconda.

  2. Open the terminal (Linux or Mac) or Anaconda command window (Windows) and use the conda-forge channel (which contains third-party packages) as the installation source. For more details and explanations, please see Basic Concepts and Terms.

    $ conda config --prepend channels conda-forge

  3. Create a GMT environment and install GMT. Note you can change the environment name mygmt to any letter combination you like.)

    $ conda create --name mygmt python=3.9 gmt

    Or you can install PyGMT directly as GMT will be installed as a dependency:

    $ conda create --name mygmt python=3.9 numpy pandas xarray netcdf4 packaging pygmt

  4. Switch to the mygmt environment to start using GMT/PyGMT. GMT is a tool running in the command-line interface (CLI), and you can use the gmt command in the terminal to access GMT’s full functionality.

    $ conda activate mygmt
$ gmt help

    To start using PyGMT, import the pygmt module in the Python interface or a Python script:

    ::

  5. If you plan to use PyGMT, I recommend installing JupyterLab as well for interactive data analysis.

    $ conda install jupyterlab

1.6. User Community#

There is a growing GMT and PyGMT community. The official GMT community forum provides a space for users to interact, ask questions, and contribute to development. The forum also serves as the announcement board when a new software version is released.

1

Wessel, P., and Smith, W. H. F. (1991). Free software helps map and display data, EOS Trans. AGU, 72(41), 445–446. https://doi.org/10.1029/90EO00319

2

Wessel, P., Luis, J., Uieda, L., Scharroo, R., Wobbe, F., Smith, W. H. F., and Tian, D. (2019). The Generic Mapping Tools Version 6. Geochemistry, Geophysics, Geosystems, 20. http://doi.org/10.1029/2019GC008515

3

Uieda, L., Tian, D., Leong, W. J., Jones, M., Schlitzer, W., Grund, M., Toney, L., Yao, J., Magen, Y., Materna, K., Fröhlich, Y., Belem, A., Newton, T., Anant, A., Ziebarth, M., Quinn, Ja., and Wessel, P. (2022). PyGMT: A Python interface for the Generic Mapping Tools (v0.7.0). Zenodo. https://doi.org/10.5281/zenodo.6702566