API Reference

PyGMT is a library for processing geospatial and geophysical data and making publication-quality maps and figures. It provides a Pythonic interface for the Generic Mapping Tools (GMT), a command-line program widely used across the Earth, Ocean, and Planetary sciences and beyond. Besides making GMT more accessible to new users, PyGMT aims to provide integration with the PyData ecosystem as well as support for rich display in Jupyter notebooks.

Main Features

Here are just a few of the things that PyGMT does well:

• Easy handling of individual types of data like Cartesian, geographic, or time-series data.

• Processing of (geo)spatial data including gridding, filtering, and masking.

• Plotting of a large spectrum of objects on figures including lines, vectors, polygons, and symbols (pre-defined and customized).

• Generating publication-quality illustrations and making animations.

Plotting

Figure class overview

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

Figure()

A GMT figure to handle all plotting.

Plotting map elements

Figure.basemap(*[, region, projection, ...])	Plot base maps and frames for the figure.
Figure.coast(*[, area_thresh, frame, lakes, ...])	Plot continents, shorelines, rivers, and borders on maps.
Figure.colorbar(*[, frame, cmap, position, ...])	Plot colorbars on figures.
Figure.inset(*[, position, box, projection, ...])	Create an inset figure to be placed within a larger figure.
Figure.legend([spec, position, box, region, ...])	Plot legends on maps.
Figure.logo(*[, region, projection, ...])	Plot the GMT logo.
Figure.solar([terminator, terminator_datetime])	Plot day-light terminators or twilights.
Figure.text([textfiles, x, y, position, ...])	Plot or typeset text strings of variable size, font type, and orientation.
Figure.timestamp([text, label, justify, ...])	Plot the GMT timestamp logo.

Plotting tabular data

Figure.contour([data, x, y, z, annotation, ...])	Contour table data by direct triangulation.
Figure.histogram(data, *[, horizontal, ...])	Plot Cartesian histograms.
Figure.meca(spec, scale[, convention, ...])	Plot focal mechanisms.
Figure.plot([data, x, y, size, direction, ...])	Plot lines, polygons, and symbols in 2-D.
Figure.plot3d([data, x, y, z, size, ...])	Plot lines, polygons, and symbols in 3-D.
Figure.rose([data, length, azimuth, sector, ...])	Plot windrose diagrams or polar histograms.
Figure.ternary(data[, alabel, blabel, ...])	Plot ternary diagrams.
Figure.velo([data, vector, frame, cmap, ...])	Plot velocity vectors, crosses, anisotropy bars, and wedges.
Figure.wiggle([data, x, y, z, fillpositive, ...])	Plot z=f(x,y) anomalies along tracks.

Plotting raster data

Figure.grdcontour(grid, *[, annotation, ...])	Convert grids or images to contours and plot them on maps.
Figure.grdimage(grid, *[, frame, cmap, ...])	Project and plot grids or images.
Figure.grdview(grid, *[, region, ...])	Create 3-D perspective image or surface mesh from a grid.
Figure.image(imagefile, *[, position, box, ...])	Place images or EPS files on maps.
Figure.tilemap(region[, zoom, source, ...])	Plot an XYZ tile map.

Configuring layout

Figure.set_panel([panel, fixedlabel, ...])	Set the current subplot panel to plot on.
Figure.shift_origin([xshift, yshift])	Shift plot origin in x and/or y directions.
Figure.subplot([nrows, ncols, figsize, ...])	Create multi-panel subplot figures.

Saving and displaying the figure

Figure.savefig(fname[, transparent, crop, ...])	Save the figure to an image file.
Figure.show([dpi, width, method, waiting])	Display a preview of the figure.
Figure.psconvert(*[, crop, gs_option, dpi, ...])	Convert [E]PS file(s) to other formats.

Configuring the display settings

The following function is provided directly through the pygmt top level package.

set_display([method])

Set the display method when calling pygmt.Figure.show.

Color palette table generation

The following functions are provided directly through the pygmt top level package.

grd2cpt(grid, *[, transparency, cmap, ...])	Make GMT color palette tables from a grid file.
makecpt(*[, transparency, cmap, background, ...])	Make GMT color palette tables.

Data Processing

Operations on tabular data

binstats(data[, outgrid])	Bin spatial data and determine statistics per bin.
blockmean([data, x, y, z, output_type, outfile])	Block average (x, y, z) data tables by mean estimation.
blockmedian([data, x, y, z, output_type, ...])	Block average (x, y, z) data tables by median estimation.
blockmode([data, x, y, z, output_type, outfile])	Block average (x, y, z) data tables by mode estimation.
filter1d(data[, output_type, outfile])	Time domain filtering of 1-D data tables.
nearneighbor([data, x, y, z, outgrid])	Grid table data using a "Nearest neighbor" algorithm.
project([data, x, y, z, output_type, outfile])	Project data onto lines or great circles, or generate tracks.
select([data, output_type, outfile])	Select data table subsets based on multiple spatial criteria.
sph2grd(data[, outgrid])	Create spherical grid files in tension of data.
sphdistance([data, x, y, outgrid])	Create Voronoi distance, node, or natural nearest-neighbor grid on a sphere.
sphinterpolate(data[, outgrid])	Create spherical grid files in tension of data.
surface([data, x, y, z, outgrid])	Grid table data using adjustable tension continuous curvature splines.
triangulate()	Delaunay triangulation or Voronoi partitioning and gridding of Cartesian data.
triangulate.regular_grid([data, x, y, z, ...])	Delaunay triangle based gridding of Cartesian data.
triangulate.delaunay_triples([data, x, y, ...])	Delaunay triangle based gridding of Cartesian data.
xyz2grd([data, x, y, z, outgrid])	Create a grid file from table data.

Operations on raster data

dimfilter(grid[, outgrid])	Filter a grid by dividing the filter circle.
grd2xyz(grid[, output_type, outfile])	Convert grid to data table.
grdclip(grid[, outgrid])	Set values in a grid that meet certain criteria to a new value.
grdcut(grid, *[, outgrid, region, ...])	Extract subregion from a grid.
grdfill(grid[, outgrid])	Fill blank areas from a grid file.
grdfilter(grid[, outgrid])	Filter a grid in the space (or time) domain.
grdgradient(grid[, outgrid])	Compute the directional derivative of the vector gradient of the data.
grdhisteq()	Perform histogram equalization for a grid.
grdhisteq.equalize_grid(grid[, outgrid])	Perform histogram equalization for a grid.
grdhisteq.compute_bins(grid[, output_type, ...])	Perform histogram equalization for a grid.
grdlandmask([outgrid])	Create a grid file with set values for land and water.
grdproject(grid[, outgrid])	Change projection of gridded data between geographical and rectangular.
grdsample(grid[, outgrid])	Change the registration, spacing, or nodes in a grid file.
grdtrack(grid[, points, output_type, ...])	Sample grids at specified (x,y) locations.
grdvolume(grid[, output_type, outfile])	Determine the volume between the surface of a grid and a plane.

Crossover analysis with x2sys

x2sys_init(tag, *[, fmtfile, suffix, force, ...])	Initialize a new x2sys track database.
x2sys_cross([tracks, outfile, combitable, ...])	Calculate crossovers between track data files.

Input/output

load_dataarray(filename_or_obj, **kwargs)

Open, load into memory, and close a DataArray from a file or file-like object containing a single data variable.

GMT Defaults

Operations on GMT defaults:

config(*[, COLOR_BACKGROUND, ...])

Set GMT defaults globally or locally.

Metadata

Getting metadata from tabular or grid data:

GMTDataArrayAccessor(xarray_obj)	GMT accessor for xarray.DataArray.
info(data, *[, per_column, spacing, ...])	Get information about data tables.
grdinfo(grid, *[, per_column, tiles, ...])	Get information about a grid.

Miscellaneous

which(fname, **kwargs)	Find the full path to specified files.
print_clib_info([file])	Print information about the GMT shared library that we can find.
show_versions([file])	Print various dependency versions which are useful when submitting bug reports.

Datasets

PyGMT provides access to GMT’s datasets through the pygmt.datasets module. These functions will download the datasets automatically the first time they are used and store them in GMT’s user data directory.

datasets.list_sample_data()	Report datasets available for tests and documentation examples.
datasets.load_earth_age([resolution, ...])	Load the Earth seafloor crustal age dataset in various resolutions.
datasets.load_earth_free_air_anomaly([...])	Load the IGPP Earth free-air anomaly dataset in various resolutions.
datasets.load_earth_geoid([resolution, ...])	Load the EGM2008 Earth geoid dataset in various resolutions.
datasets.load_earth_magnetic_anomaly([...])	Load the Earth magnetic anomaly datasets in various resolutions.
datasets.load_earth_mask([resolution, ...])	Load the GSHHG Earth mask dataset in various resolutions.
datasets.load_earth_relief([resolution, ...])	Load the Earth relief datasets (topography and bathymetry) in various resolutions.
datasets.load_earth_vertical_gravity_gradient([...])	Load the IGPP Earth vertical gravity gradient dataset in various resolutions.
datasets.load_mars_relief([resolution, ...])	Load the Mars relief dataset in various resolutions.
datasets.load_mercury_relief([resolution, ...])	Load the Mercury relief dataset in various resolutions.
datasets.load_moon_relief([resolution, ...])	Load the Moon relief dataset in various resolutions.
datasets.load_pluto_relief([resolution, ...])	Load the Pluto relief dataset in various resolutions.
datasets.load_venus_relief([resolution, ...])	Load the Venus relief dataset in various resolutions.
datasets.load_sample_data(name)	Load an example dataset from the GMT server.

In addition, there is also a special function to load XYZ tile maps via contextily to be used as base maps.

datasets.load_tile_map(region[, zoom, ...])

Load a georeferenced raster tile map from XYZ tile providers.

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(module, args)

Call a GMT module with the given arguments.

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

clib.Session.virtualfile_in([check_kind, ...])	Store any data inside a virtual file.
clib.Session.virtualfile_out([kind, fname])	Create a virtual file or an actual file for storing output data.
clib.Session.virtualfile_to_dataset(vfname)	Output a tabular dataset stored in a virtual file to a different format.
clib.Session.virtualfile_to_raster(vfname[, ...])	Output raster data stored in a virtual file to an xarray.DataArray object.

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

clib.Session.create(name)	Create a new GMT C API session.
clib.Session.destroy()	Destroy the currently open GMT API session.
clib.Session.__getitem__(name)	Get the value of a GMT constant (C enum) from gmt_resources.h.
clib.Session.__enter__()	Create a GMT API session and check the libgmt version.
clib.Session.__exit__(exc_type, exc_value, ...)	Destroy the currently open GMT API session.
clib.Session.get_default(name)	Get the value of a GMT default parameter (library version, paths, etc).
clib.Session.get_common(option)	Inquire if a GMT common option has been set and return its current value if possible.
clib.Session.create_data(family, geometry, mode)	Create an empty GMT data container.
clib.Session.put_matrix(dataset, matrix[, pad])	Attach a numpy 2-D array to a GMT dataset.
clib.Session.put_strings(dataset, family, ...)	Attach a numpy 1-D array of dtype str as a column on a GMT dataset.
clib.Session.put_vector(dataset, column, vector)	Attach a numpy 1-D array as a column on a GMT dataset.
clib.Session.write_data(family, geometry, ...)	Write a GMT data container to a file.
clib.Session.open_virtualfile(family, ...)	Open a GMT virtual file to pass data to and from a module.
clib.Session.read_virtualfile(vfname[, kind])	Read data from a virtual file and optionally cast into a GMT data container.
clib.Session.extract_region()	Extract the WESN bounding box of the currently active figure.
clib.Session.get_libgmt_func(name[, ...])	Get a ctypes function from the libgmt shared library.
clib.Session.virtualfile_from_data([...])	Store any data inside a virtual file.
clib.Session.virtualfile_from_grid(grid)	Store a grid in a virtual file.
clib.Session.virtualfile_from_matrix(matrix)	Store a 2-D array as a table inside a virtual file.
clib.Session.virtualfile_from_vectors(*vectors)	Store 1-D arrays as columns of a table inside a virtual file.