CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-pygmt

A Python interface for the Generic Mapping Tools

—

Pending
Overview
Eval results
Files

datasets.mddocs/

Dataset Loading

Built-in access to GMT's extensive collection of global datasets including Earth relief, planetary data, geophysical grids, and sample datasets. All datasets are downloaded from GMT's data server and returned as xarray DataArrays with proper GMT metadata.

Capabilities

Earth Relief and Topography

Global digital elevation models at various resolutions.

def load_earth_relief(resolution: str = "01d", region: Region | None = None, 
                      registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load global relief grid from ETOPO1, SRTM, or GMT global relief.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m", "30s", "15s", "03s", "01s")
    - region: Geographic extent [west, east, south, north] 
    - registration: Grid registration ("gridline" or "pixel")
    - use_srtm: Use SRTM data for high-resolution land areas
    
    Returns:
    xarray.DataArray: Global relief grid in meters
    """

def load_earth_age(resolution: str = "01d", region: Region | None = None, 
                   registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load a grid of seafloor crustal ages.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Seafloor age grid in millions of years
    """

def load_earth_mask(resolution: str = "01d", region: Region | None = None,
                    registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load global mask grid distinguishing land and water areas.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m", "15s")
    - region: Geographic extent  
    - registration: Grid registration
    
    Returns:  
    xarray.DataArray: Mask grid (0=ocean, 1=land, 2=lake, 3=island_in_lake, 4=pond_in_island)
    """

Earth Geophysical Data

Global grids of geophysical quantities.

def load_earth_free_air_anomaly(resolution: str = "01d", region: Region | None = None,
                                registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load global free-air gravity anomaly grid.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Free-air gravity anomaly in mGal
    """

def load_earth_magnetic_anomaly(resolution: str = "01d", region: Region | None = None,
                                registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load global magnetic anomaly grid.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Magnetic anomaly in nT
    """

def load_earth_geoid(resolution: str = "01d", region: Region | None = None,
                     registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load global geoid grids.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Geoid height in meters
    """

def load_earth_vertical_gravity_gradient(resolution: str = "01d", region: Region | None = None,
                                         registration: GridRegistration | None = None, 
                                         **kwargs) -> xr.DataArray:
    """
    Load global vertical gravity gradient grid.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent  
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Vertical gravity gradient in Eotvos units
    """

def load_earth_deflection(resolution: str = "01d", region: Region | None = None,
                          registration: GridRegistration | None = None, 
                          component: Literal["east", "north"] = "east", **kwargs) -> xr.DataArray:
    """
    Load vertical deflection grids.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration  
    - component: Deflection component ("east" or "north")
    
    Returns:
    xarray.DataArray: Vertical deflection in arc-seconds
    """

def load_earth_dist(resolution: str = "01d", region: Region | None = None,
                    registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load distance to nearest point on land.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Distance to land in kilometers
    """

Earth Ocean Data

Ocean-specific global datasets.

def load_earth_mean_sea_surface(resolution: str = "01d", region: Region | None = None,
                                registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load global mean sea surface grid.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Mean sea surface height in meters
    """

def load_earth_mean_dynamic_topography(resolution: str = "01d", region: Region | None = None,
                                       registration: GridRegistration | None = None, 
                                       **kwargs) -> xr.DataArray:
    """
    Load global mean dynamic topography grid.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Mean dynamic topography in meters
    """

Earth Satellite Imagery

Global satellite imagery datasets.

def load_blue_marble(resolution: str = "01d", region: Region | None = None,
                     registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load a blue marble Earth day image.
    
    Parameters:
    - resolution: Image resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: RGB satellite image
    """

def load_black_marble(resolution: str = "01d", region: Region | None = None,
                      registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load a black marble Earth night image.
    
    Parameters:
    - resolution: Image resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: RGB nighttime satellite image
    """

Planetary Relief Data

Digital elevation models for other planets and moons.

def load_mars_relief(resolution: str = "01d", region: Region | None = None,
                     registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load global relief grid for Mars.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent  
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Mars elevation grid in meters
    """

def load_moon_relief(resolution: str = "01d", region: Region | None = None,
                     registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load global relief grid for the Moon.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Lunar elevation grid in meters
    """

def load_mercury_relief(resolution: str = "01d", region: Region | None = None,
                        registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load global relief grid for Mercury.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Mercury elevation grid in meters
    """

def load_venus_relief(resolution: str = "01d", region: Region | None = None,
                      registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load global relief grid for Venus.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Venus elevation grid in meters
    """

def load_pluto_relief(resolution: str = "01d", region: Region | None = None,
                      registration: GridRegistration | None = None, **kwargs) -> xr.DataArray:
    """
    Load global relief grid for Pluto.
    
    Parameters:
    - resolution: Grid resolution ("01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m")
    - region: Geographic extent
    - registration: Grid registration
    
    Returns:
    xarray.DataArray: Pluto elevation grid in meters
    """

Sample and Test Data

Built-in sample datasets for testing and examples.

def list_sample_data() -> list:
    """
    Get list of names of all available sample datasets.
    
    Returns:
    list: Names of available sample datasets
    """

def load_sample_data(name: str) -> xr.DataArray | pd.DataFrame:
    """
    Load sample data included with GMT.
    
    Parameters:
    - name: Name of sample dataset
    
    Returns:
    xarray.DataArray or pandas.DataFrame: Sample data
    
    Available datasets include:
    - "@earth_relief_01d_g": 1 degree global relief
    - "@earth_age_01m_g": 1 arc-minute seafloor age
    - "@hotspots.txt": Global hotspot locations
    - "@ridge.txt": Mid-ocean ridge locations
    - "@fractures.txt": Fracture zone locations
    - "@seamounts.txt": Seamount locations
    """

Web Map Tiles

Access to web-based map tile services.

def load_tile_map(region: Region, zoom: int = "auto", source: str = "OpenStreetMap",
                  lonlat: bool = True, wait: int = 0, max_retries: int = 2, **kwargs) -> xr.DataArray:
    """
    Load tile maps from various web map servers.
    
    Parameters:
    - region: Geographic extent [west, east, south, north]
    - zoom: Zoom level (1-19, or "auto" for automatic selection)
    - source: Tile source ("OpenStreetMap", "OpenTopoMap", "ESRI_World_Imagery", etc.)
    - lonlat: Input region in longitude/latitude (True) or tile coordinates (False)
    - wait: Wait time between tile requests in seconds
    - max_retries: Maximum number of retry attempts
    
    Returns:
    xarray.DataArray: RGB tile map image
    
    Available sources:
    - "OpenStreetMap": Standard OpenStreetMap tiles
    - "OpenTopoMap": Topographic map tiles  
    - "ESRI_World_Imagery": ESRI satellite imagery
    - "ESRI_World_Terrain_Base": ESRI terrain base map
    - "Google_Satellite": Google satellite imagery (requires API key)
    - "Google_Terrain": Google terrain maps (requires API key)
    """

Usage Examples

Basic Dataset Loading

import pygmt

# Load global relief at 1 degree resolution
relief = pygmt.datasets.load_earth_relief(resolution="01d")
print(f"Grid shape: {relief.shape}")
print(f"Data range: {relief.min().values:.1f} to {relief.max().values:.1f} meters")

# Load regional high-resolution relief
regional_relief = pygmt.datasets.load_earth_relief(
    resolution="03s",
    region=[120, 125, 20, 25]  # Taiwan region
)
print(f"Regional grid shape: {regional_relief.shape}")

Geophysical Data Analysis

import pygmt
import matplotlib.pyplot as plt

# Load magnetic anomaly data
mag_data = pygmt.datasets.load_earth_magnetic_anomaly(
    resolution="02m", 
    region=[-20, 20, -20, 20]  # Atlantic mid-ocean ridge region
)

# Load gravity data for comparison
gravity_data = pygmt.datasets.load_earth_free_air_anomaly(
    resolution="02m",
    region=[-20, 20, -20, 20]
)

# Plot both datasets
fig = pygmt.Figure()

# Plot magnetic anomalies
fig.subplot(nrows=1, ncols=2, figsize="20c", frame="WSen")
fig.set_panel(panel=0)
fig.grdimage(grid=mag_data, cmap="polar", projection="M8c")
fig.coast(shorelines=True)
fig.colorbar(frame='a500+l"Magnetic anomaly (nT)"')

# Plot gravity anomalies  
fig.set_panel(panel=1)
fig.grdimage(grid=gravity_data, cmap="polar", projection="M8c")
fig.coast(shorelines=True)
fig.colorbar(frame='a50+l"Gravity anomaly (mGal)"')

fig.show()

Planetary Data Visualization

import pygmt

# Load Mars elevation data
mars_relief = pygmt.datasets.load_mars_relief(resolution="06m")

# Create a global Mars map
fig = pygmt.Figure()
fig.grdimage(
    grid=mars_relief,
    projection="W15c",
    cmap="geo",
    frame="a60f30"
)
fig.colorbar(frame='a5000+l"Elevation (m)"')
fig.show()

# Compare with Earth
earth_relief = pygmt.datasets.load_earth_relief(resolution="06m")

fig = pygmt.Figure()
fig.subplot(nrows=2, ncols=1, figsize="15c/20c")

# Earth
fig.set_panel(panel=0)
fig.grdimage(grid=earth_relief, projection="W?", cmap="geo")
fig.colorbar(frame='a5000+l"Earth elevation (m)"')

# Mars  
fig.set_panel(panel=1)
fig.grdimage(grid=mars_relief, projection="W?", cmap="geo")
fig.colorbar(frame='a5000+l"Mars elevation (m)"')

fig.show()

Sample Data Exploration

import pygmt

# List available sample datasets
datasets = pygmt.datasets.list_sample_data()
print("Available sample datasets:")
for dataset in datasets[:10]:  # Show first 10
    print(f"  {dataset}")

# Load hotspot locations
hotspots = pygmt.datasets.load_sample_data("@hotspots.txt")
print(f"\nHotspots data shape: {hotspots.shape}")
print(f"Columns: {hotspots.columns.tolist()}")

# Plot hotspots on a global map
fig = pygmt.Figure()
fig.basemap(region="global", projection="W15c", frame="a60f30")
fig.coast(land="lightgray", water="lightblue")
fig.plot(
    data=hotspots,
    style="c0.2c",
    fill="red",
    pen="0.5p,black"
)
fig.show()

Web Tile Integration

import pygmt

# Load OpenStreetMap tiles for a city
osm_tiles = pygmt.datasets.load_tile_map(
    region=[-74.02, -73.97, 40.75, 40.78],  # Manhattan, NYC
    zoom=12,
    source="OpenStreetMap"
)

# Create map with tiles as background
fig = pygmt.Figure()
fig.grdimage(
    grid=osm_tiles,
    projection="M15c",
    frame="a0.01f0.005"
)

# Add some sample points
sample_points = [
    [-73.985, 40.758],  # Times Square
    [-73.971, 40.764],  # Central Park
    [-73.997, 40.731]   # World Trade Center
]

for point in sample_points:
    fig.plot(x=point[0], y=point[1], style="c0.3c", fill="yellow", pen="1p,black")

fig.show()

Multi-Resolution Analysis

import pygmt

# Load same region at different resolutions
region = [120, 140, 20, 40]  # East Asia

resolutions = ["01d", "30m", "15m", "05m"]
grids = {}

for res in resolutions:
    print(f"Loading {res} resolution data...")
    grids[res] = pygmt.datasets.load_earth_relief(
        resolution=res,
        region=region
    )
    print(f"  Grid shape: {grids[res].shape}")
    print(f"  Grid spacing: {grids[res].gmt.spacing}")

# Plot comparison
fig = pygmt.Figure()
fig.subplot(nrows=2, ncols=2, figsize="20c", frame="WSen")

for i, res in enumerate(resolutions):
    fig.set_panel(panel=i)
    fig.grdimage(grid=grids[res], projection="M?", cmap="geo")
    fig.coast(shorelines=True)
    fig.text(text=f"Resolution: {res}", position="TL", font="12p,Helvetica-Bold")

fig.show()

Dataset Resolution Guide

Available Resolutions

All Earth datasets support these resolutions:

  • 01d: 1 degree (~111 km at equator)
  • 30m: 30 arc-minutes (~55 km)
  • 20m: 20 arc-minutes (~37 km)
  • 15m: 15 arc-minutes (~28 km)
  • 10m: 10 arc-minutes (~18 km)
  • 06m: 6 arc-minutes (~11 km)
  • 05m: 5 arc-minutes (~9 km)
  • 04m: 4 arc-minutes (~7 km)
  • 03m: 3 arc-minutes (~5.5 km)
  • 02m: 2 arc-minutes (~3.7 km)
  • 01m: 1 arc-minute (~1.8 km)
  • 30s: 30 arc-seconds (~900 m)
  • 15s: 15 arc-seconds (~450 m)
  • 03s: 3 arc-seconds (~90 m)
  • 01s: 1 arc-second (~30 m)

Memory and Performance Considerations

Higher resolution datasets require more memory and processing time:

  • Global 01d: ~0.5 MB, instant download
  • Global 15m: ~25 MB, fast download
  • Global 01m: ~1.5 GB, slower download
  • Regional 15s: Can be very large for big regions

Use appropriate resolution for your analysis needs and computational resources.

Install with Tessl CLI

npx tessl i tessl/pypi-pygmt

docs

config-utilities.md

data-processing.md

datasets.md

figure-plotting.md

index.md

tile.json