API Reference

Plotting

All plotting is handled through the pygmt.Figure class and its methods.

Figure() A GMT figure to handle all plotting.

Plotting data and laying out the map:

Figure.basemap(self, \*\*kwargs) Produce a basemap for the figure.
Figure.coast(self, \*\*kwargs) Plot continents, shorelines, rivers, and borders on maps
Figure.colorbar(self, \*\*kwargs) Plot a gray or color scale-bar on maps.
Figure.plot(self[, x, y, data, sizes, direction]) Plot lines, polygons, and symbols on maps.
Figure.contour(self[, x, y, z, data]) Contour table data by direct triangulation.
Figure.grdcontour(self, grid, \*\*kwargs) Convert grids or images to contours and plot them on maps
Figure.grdimage(self, grid, \*\*kwargs) Project grids or images and plot them on maps.
Figure.legend(self[, spec]) Plot legends on maps.
Figure.logo(self, \*\*kwargs) Place the GMT graphics logo on a map.
Figure.image(self, imagefile, \*\*kwargs) Place images or EPS files on maps.
Figure.shift_origin(self[, xshift, yshift]) Shift plot origin in x and/or y directions.
Figure.text(self[, textfiles, x, y, text, …]) Plot or typeset text on maps

Color palette table generation:

makecpt(\*\*kwargs) Creates a static color palette table (CPT).

Saving and displaying the figure:

Figure.savefig(self, fname[, transparent, …]) Save the figure to a file.
Figure.show(self[, dpi, width, method]) Display a preview of the figure.
Figure.psconvert(self, \*\*kwargs) Convert [E]PS file(s) to other formats.

Data Processing

Operations on tabular data:

info(fname, \*\*kwargs) Get information about data tables.
surface([x, y, z, data]) Grids table data using adjustable tension continuous curvature splines.

Operations on grids:

grdinfo(grid, \*\*kwargs) Get information about a grid.

Miscellaneous

which(fname, \*\*kwargs) Find the full path to specified files.
test([doctest, verbose, coverage, figures]) Run the test suite.
print_clib_info() Print information about the GMT shared library that we can find.

Datasets

PyGMT provides access to GMT’s datasets through the pygmt.datasets package. These functions will download the datasets automatically the first time they are used and store them in the GMT cache folder.

datasets.load_earth_relief([resolution]) Load Earth relief grids (topography and bathymetry) in various resolutions.
datasets.load_usgs_quakes() Load a table of global earthquakes form the USGS as a pandas.Dataframe.
datasets.load_sample_bathymetry() Load a table of ship observations of bathymetry off Baja California as a pandas.DataFrame.
datasets.load_japan_quakes() Load a table of earthquakes around Japan as a pandas.Dataframe.

Exceptions

All custom exceptions are derived from pygmt.exceptions.GMTError.

exceptions.GMTError Base class for all GMT related errors.
exceptions.GMTInvalidInput Raised when the input of a function/method is invalid.
exceptions.GMTVersionError Raised when an incompatible version of GMT is being used.
exceptions.GMTOSError Unsupported operating system.
exceptions.GMTCLibError Error encountered when running a function from the GMT shared library.
exceptions.GMTCLibNoSessionError Tried to access GMT API without a currently open GMT session.
exceptions.GMTCLibNotFoundError Could not find the GMT shared library.

GMT C API

The pygmt.clib package is a wrapper for the GMT C API built using ctypes. Most calls to the C API happen through the pygmt.clib.Session class.

clib.Session A GMT API session where most operations involving the C API happen.

GMT modules are executed through the call_module method:

clib.Session.call_module(self, module, args) Call a GMT module with the given arguments.

Passing memory blocks between Python variables (numpy.ndarray, pandas.Series, and xarray.DataArray) and GMT happens through virtual files. These methods are context managers that automate the conversion of Python variables to GMT virtual files:

clib.Session.virtualfile_from_matrix(self, …) Store a 2d array as a table inside a virtual file.
clib.Session.virtualfile_from_vectors(self, …) Store 1d arrays as columns of a table inside a virtual file.
clib.Session.virtualfile_from_grid(self, grid) Store a grid in a virtual file.

Low level access (these are mostly used by the pygmt.clib package):

clib.Session.create(self, name) Create a new GMT C API session.
clib.Session.destroy(self) Destroy the currently open GMT API session.
clib.Session.__getitem__(self, name) Get the value of a GMT constant (C enum) from gmt_resources.h
clib.Session.__enter__(self) Create a GMT API session and check the libgmt version.
clib.Session.__exit__(self, exc_type, …) Destroy the currently open GMT API session.
clib.Session.get_default(self, name) Get the value of a GMT default parameter (library version, paths, etc).
clib.Session.create_data(self, family, …) Create an empty GMT data container.
clib.Session.put_matrix(self, dataset, matrix) Attach a numpy 2D array to a GMT dataset.
clib.Session.put_vector(self, dataset, …) Attach a numpy 1D array as a column on a GMT dataset.
clib.Session.write_data(self, family, …) Write a GMT data container to a file.
clib.Session.open_virtual_file(self, family, …) Open a GMT Virtual File to pass data to and from a module.
clib.Session.extract_region(self) Extract the WESN bounding box of the currently active figure.
clib.Session.get_libgmt_func(self, name[, …]) Get a ctypes function from the libgmt shared library.