1. GMT / PyGMT Introduction and Installation

1.1. What is GMT?

Generic Mapping Tools, or GMT for short, is a software package for geographical mapping and other related tasks. The development of the software 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 was could be, which has motivated two authors and the whole GMT development team for continuing 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. For academic fields such as geophysics or oceanography, GMT has become the introductory toolbox for plotting scientific data.

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 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 是由科學社群發起的專案計畫，目前的最新版 (版本號 0.3.1) 已於 2021 年 3 月釋出。各位如有興趣貢獻一己之力開發軟體，非常歡迎前往 PyGMT 的官方網站一探究竟。

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 to get a swing of GMT is, however, 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 would 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 for speeding up your learning efficiency.

1.4. About the tutorials

I am a research scientist in geophysics and planetary sciences, with about 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 some of my scripts and thoughts down 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 that 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. Here lists my preferred method: installing GMT 6 using conda. 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.

  2. Open terminal (Linux or Mac) or Anaconda command window (Windows) and create a GMT environment: (For more details and explanations please see Basic Concepts and Terms. Note you can change the environment name gmt6 to any letter combination you like.)

    $ conda create --name gmt6
$ conda activate gmt6

  3. To install GMT:

    $ conda config --prepend channels conda-forge
$ conda install python=3.9 gmt

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

    $ conda config --prepend channels conda-forge
$ conda install python=3.9 pygmt pip numpy pandas xarray netcdf4 packaging gmt pytest pytest-mpl

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

    $ conda install jupyterlab

  5. To start up GMT, switch to the GMT conda environment and you are all set.

    $ conda activate gmt6
$ gmt help

    To start using PyGMT, just import the pygmt module in Python:

    import pygmt
pygmt.show_versions()

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 there is a new software version released.

1

Wessel, P., and Smith, W. H. F. (1991). Free software helps map and display data, EOS Trans. AGU, 72(41), 445–446. 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. doi.org/10.1029/2019GC008515.

3

Uieda, L., Tian, D., Leong, W. J., Toney, L., Newton, T., and Wessel, P. (2020, November 14). PyGMT: A Python interface for the Generic Mapping Tools (Version v0.2.1). Zenodo. doi.org/10.5281/zenodo.4253459.