First Steps with GMT/Python

This tutorial will get you started with the basic usage of GMT/Python. Some of the examples shown here are from the GMT Tutorial.

Loading the library

The GMT modules are available as functions and classes in the gmt Python package. So we’ll start by importing it:

import gmt

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
<ipython-input-1-f88e611ef6c5> in <module>
----> 1 import gmt

ModuleNotFoundError: No module named 'gmt'

Our first map

All figure generation in GMT/Python is handled by the gmt.Figure class. It has methods to add layers to your figure, like a basemap, coastlines, and data.

We start a new figure by creating an instance of gmt.Figure:

fig = gmt.Figure()

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-2-17bdc6832b74> in <module>
----> 1 fig = gmt.Figure()

NameError: name 'gmt' is not defined

We add elements to the figure using its methods. For example, lets add the coastlines of Central America to a 6 inch wide map using the Mercator projection (M). Our figure will also have a nice frame with automatic ticks.

fig.coast(region=[-90, -70, 0, 20], projection='M6i', land='chocolate',
          frame=True)

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-3-cecfe0a22e49> in <module>
----> 1 fig.coast(region=[-90, -70, 0, 20], projection='M6i', land='chocolate',
      2           frame=True)

NameError: name 'fig' is not defined

You can see a preview of the figure directly in the Jupyter notebook using fig.show().

fig.show()

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-4-6ebedab27258> in <module>
----> 1 fig.show()

NameError: name 'fig' is not defined

To open a PDF preview of the figure using your default PDF viewer use:

fig.show(method='external')

This is useful when using the Python shell or IPython terminal app. However, this command will not interrupt your Python process. So using it in a Python script will not work because the script will finish and delete the generated previews. Use fig.savefig to save the figure to a file instead (see below).

There is also the option of inserting the figure in an interactive globe using NASA’s WorldWind Web. See option external='globe' in the examples below.

A note for experienced GMT users

You’ll probably have noticed several things that are different from classic command-line GMT. Many of these changes reflect the new GMT modern execution mode that will be part of the future 6.0 release. A few are GMT/Python exclusive (like the long argument names).

1. The name of method is coast instead of pscoast. As a general rule, all ps* modules had their ps removed. The exceptions are: psxy == plot, psxyz == plot3d, and psscale == colorbar.
2. The arguments don’t use the GMT 1-letter syntax (R, J, B, etc). Those are still available as aliases and the methods will accept them (see below).
3. Arguments like region can take lists instead of strings like 1/2/3/4. You can still use the string form but the list form is easier in Python.
4. If a GMT argument has no options (like -B instead of -Baf), use a True value instead. An empty string would also be acceptable.
5. There is no output redirecting to a PostScript file. The figure is generated in the background and will only be shown or saved when you ask for it.

We could have generated the figure above using the classic GMT argument names (but not the module names):

fig_alias = gmt.Figure()
fig_alias.coast(R='-90/-70/0/20', J='M6i', G='gray', S="blue", B=True)
fig_alias.show()

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-5-f7265ca23a19> in <module>
----> 1 fig_alias = gmt.Figure()
      2 fig_alias.coast(R='-90/-70/0/20', J='M6i', G='gray', S="blue", B=True)
      3 fig_alias.show()

NameError: name 'gmt' is not defined

Saving the figure

Unlike the GMT command-line interface, no figure file was generated until you ask for one.

That means that fig.show won’t produce a figure file.

Use method fig.savefig (based on the matplotlib function) to save your figure:

fig.savefig('first-steps-central-america.png')

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-6-5b6cf59b6d73> in <module>
----> 1 fig.savefig('first-steps-central-america.png')

NameError: name 'fig' is not defined

If you’re running a Python script, you can tell fig.savefig to open the figure in an external viewer:

fig.savefig('first-steps-central-america.png', show=True)