gplately.DataServer

class gplately.DataServer(model_name, data_dir=None)

Bases: object

Access, download, and cache plate-model data and related geospatial datasets.

DataServer is a convenience interface over plate_model_manager. It downloads requested assets into the local GPlately cache directory and reuses cached files when available.

Main capabilities include:

• Loading rotation/topology/static-polygon inputs for plate reconstruction.

• Loading optional topology geometries (coastlines, continents, COBs).

• Fetching time-dependent rasters (for example age and spreading-rate grids).

• Fetching supported present-day rasters and curated feature datasets.

Notes

Cache reuse is automatic. Repeated calls generally avoid re-downloading unchanged files.

Example

import gplately

data_server = gplately.DataServer("Muller2025")
rotation_model, topology_features, static_polygons = (
    data_server.get_plate_reconstruction_files()
)

See also

• This table provides a list of available plate reconstruction models.

• Visit this EarthByte web page for more information about these plate models.

• Call gplately.auxiliary.get_data_server_cache_path() to see the path to the GPlately cache folder.

__init__(model_name, data_dir=None)

Initialize a data server for a plate model .

Parameters:

• model_name (str) – Plate model name (for example "Muller2025").

• data_dir (str or os.PathLike, optional) – Local directory used by plate_model_manager to store or read model data. If not provided, the default GPlately cache path is used.

Raises:

Exception – If the requested model collection cannot be resolved.

Example

import gplately

data_server = gplately.DataServer("Muller2025")

Methods

__init__(model_name[, data_dir])	Initialize a data server for a plate model .
cache_path()	The location of DataServer cache on your computer.
get_age_grid(times[, reference_frame, ...])	Download the seafloor age grids for the plate model.
get_feature_data(feature_data_id_string)	Download and load supported geological feature datasets.
get_plate_reconstruction_files()	Download and return a tuple of rotation_model, topology_features and static_polygons.
get_raster(raster_name)	Download rasters that are not associated with any plate reconstruction models.
get_spreading_rate_grid(times[, ...])	Download seafloor spreading rate grids from the plate reconstruction model and save the grids in the GPlately cache folder.
get_topology_geometries()	Download and return coastlines, continental polygons and COBs (continent-ocean boundary).
get_valid_times()	Deprecated!!! Use DataServer.valid_times instead.

Attributes

COBs	A pygplates.FeatureCollection object containing continent-ocean boundaries.
coastlines	A pygplates.FeatureCollection object containing coastlines.
continents	A pygplates.FeatureCollection object containing continental polygons.
from_age	The max age/time of the plate model.
rotation_model	Return the model rotation tree as a pygplates.RotationModel.
static_polygons	A pygplates.FeatureCollection object containing static polygons.
time_range	Deprecated!!! Use DataServer.valid_time instead.
to_age	The min age/time of the plate model.
topology_features	A pygplates.FeatureCollection object containing topology features.
valid_time	The period of time the plate model are valid.
valid_times	Deprecated!!! Use DataServer.valid_time instead.

property COBs

A pygplates.FeatureCollection object containing continent-ocean boundaries.

static cache_path()

The location of DataServer cache on your computer.

property coastlines

A pygplates.FeatureCollection object containing coastlines.

property continents

A pygplates.FeatureCollection object containing continental polygons.

property from_age: float

The max age/time of the plate model.

get_age_grid(times: int | list[int], reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None)

Download the seafloor age grids for the plate model. Save the grids in the GPlately cache folder.

See also

DataServer.cache_path()

Parameters:

times (int, or a list of int) – A reconstruction time or a list of reconstruction times.

Return type:

gplately.Raster or a list of gplately.Raster

Note

The age grid data can be accessed as a numpy ndarray or MaskedArray via the gplately.Raster.data attribute.

For example:

data_server = gplately.DataServer("zahirovic2022")
graster = data_server.get_age_grid(100)
graster_data = graster.data

where graster_data is a numpy ndarray.

Raises:

ValueError – If the times parameter contains invalid reconstruction time.

Example

To download Zahirovic et al. (2022) seafloor age grids for 0Ma, 1Ma and 100 Ma:

data_server = gplately.DataServer("zahirovic2022")
age_grids = data_server.get_age_grid([0, 1, 100])

See also

• PlateModel.get_raster()

• PlateModel.get_rasters()

from gplately import PlateModelManager

model = PlateModelManager().get_model("zahirovic2022")
print(model.get_rasters("AgeGrids", times=[10, 20, 30]))
print(model.get_raster("AgeGrids", time=100))

static get_feature_data(feature_data_id_string: str)

Download and load supported geological feature datasets.

This method fetches a dataset from the EarthByte GPlates sample-data server, caches it under the GPlately cache directory, and returns one or more pygplates.FeatureCollection objects from matching files.

Supported dataset identifiers:

• SeafloorFabric: Seafloor tectonic fabric data (Matthews et al., 2011).

• Johansson2018: Large igneous provinces (Johansson et al., 2018).

• Whittaker2015: Igneous province products interpreted as plume products (Whittaker et al., 2015).

• Hotspots: Present-day hotspot/plume locations (Whittaker et al., 2013).

Detailed descriptions can be found below:

• Large igneous provinces from Johansson et al. (2018)

  Information:

  • Formats: .gpmlz

  • feature_data_id_string = Johansson2018

  Citations:

  Johansson, L., Zahirovic, S., and Müller, R. D., In Prep, The interplay between the eruption and weathering of Large Igneous Provinces and the deep-time carbon cycle: Geophysical Research Letters.

• Large igneous province products interpreted as plume products from Whittaker et al. (2015)

  Information:

  • Formats: .gpmlz, .shp

  • feature_data_id_string = Whittaker2015

  Citations:

  Whittaker, J. M., Afonso, J. C., Masterton, S., Müller, R. D., Wessel, P., Williams, S. E., & Seton, M. (2015). Long-term interaction between mid-ocean ridges and mantle plumes. Nature Geoscience, 8(6), 479-483. doi:10.1038/ngeo2437.

• Seafloor tectonic fabric (fracture zones, discordant zones, V-shaped structures, unclassified V-anomalies, propagating ridge lineations and extinct ridges) from Matthews et al. (2011)

  Information:

  • Formats: .gpmlz

  • feature_data_id_string = SeafloorFabric

  Citations:

  Matthews, K.J., Müller, R.D., Wessel, P. and Whittaker, J.M., 2011. The tectonic fabric of the ocean basins. Journal of Geophysical Research, 116(B12): B12109, DOI: 10.1029/2011JB008413.

• Present day surface hotspot/plume locations from Whittaker et al. (2013)

  Information:

  • Formats: .gpmlz

  • feature_data_id_string = Hotspots

  Citation:

  Whittaker, J., Afonso, J., Masterton, S., Müller, R., Wessel, P., Williams, S., and Seton, M., 2015, Long-term interaction between mid-ocean ridges and mantle plumes: Nature Geoscience, v. 8, no. 6, p. 479-483, doi:10.1038/ngeo2437.

For examples of plotting downloaded feature data, see notebook 05.

Parameters:

feature_data_id_string (str) – Dataset identifier to download and load.

Returns:

A single feature collection if exactly one matching file is found, otherwise a list of feature collections (one per matching file).

Return type:

pygplates.FeatureCollection or list[pygplates.FeatureCollection]

Raises:

• ValueError – If feature_data_id_string is empty or not supported.

• Exception – If no files matching the dataset pattern are found after download.

Note

Files are only downloaded when local cached data are missing or stale.

get_plate_reconstruction_files()

Download and return a tuple of rotation_model, topology_features and static_polygons. These objects can then be used to create gplately.PlateReconstruction object.

Returns:

• rotation_model (pygplates.RotationModel) – A rotation model to query equivalent and/or relative topological plate rotations from a time in the past relative to another time in the past or to present day.

• topology_features (pygplates.FeatureCollection) – Topological features including ridges, transforms, subduction zones, etc. These features can be used to build topological plate boundaries and networks.

• static_polygons (pygplates.FeatureCollection) – Static polygons which can be used to assign plate IDs for other geometries. The plate IDs are essential to tectonic plate reconstruction.

Note

The example code below downloads rotation model, topology features and static polygons files from the Muller et al. (2019) plate reconstruction model and create a gplately.PlateReconstruction object.

import gplately

data_server = gplately.DataServer("Muller2025")
rotation_model, topology_features, static_polygons = (
    data_server.get_plate_reconstruction_files()
)

# create a PlateReconstruction object using the returned objects
model = gplately.PlateReconstruction(
    rotation_model, topology_features, static_polygons
)

If the requested plate model does not have certain file(s), warning messages will alert user of the missing file(s).

static get_raster(raster_name: str)

Download rasters that are not associated with any plate reconstruction models. Store the rasters in the GPlately cache.

The available present-day rasters are listed below.

• ETOPO1

  • Filetypes available : TIF, netCDF (GRD)

  • raster_name = ETOPO1_grd, ETOPO1_tif (depending on the requested format)

  • A 1-arc minute global relief model combining lang topography and ocean bathymetry.

  • Citation: doi:10.7289/V5C8276M

Parameters:

raster_name (str) – The raster name of interest.

Returns:

A gplately.Raster object containing the raster data which can be accessed as a numpy ndarray or MaskedArray via gplately.Raster.data attribute.

For example:

graster = gplately.DataServer.get_raster("ETOPO1_tif")
graster_data = graster.data

where graster_data is a numpy ndarray. This array can be visualised using matplotlib.pyplot.imshow (see example below).

Return type:

gplately.Raster

Raises:

Exception – Raise Exception when raster_name is invalid.

Example

Download ETOPO1 and plot it on a map with Mollweide projection.

import cartopy.crs as ccrs
import matplotlib.pyplot as plt

import gplately

etopo1 = gplately.DataServer.get_raster("ETOPO1_tif")
fig = plt.figure(figsize=(18, 14), dpi=300)
ax = fig.add_subplot(111, projection=ccrs.Mollweide(central_longitude=-150))
ax.imshow(etopo1.data, extent=(-180, 180, -90, 90), transform=ccrs.PlateCarree())

get_spreading_rate_grid(times, reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None)

Download seafloor spreading rate grids from the plate reconstruction model and save the grids in the GPlately cache folder.

See also

DataServer.cache_path()

Parameters:

• time (int, or list of int) – Request spreading grid(s) for one (an integer) or multiple reconstruction times (a list of integers).

• reference_frame (ReferenceFrame, optional) – The reference frame used to build the returned rotation model.

• generated_from (GenerationMethod, optional) – The generation method used to generate the spreading rate grid.

Return type:

gplately.Raster or a list of gplately.Raster

get_topology_geometries()

Download and return coastlines, continental polygons and COBs (continent-ocean boundary). These feature collections can be used to create gplately.PlotTopologies object and plot paleomaps.

Returns:

• coastlines (pygplates.FeatureCollection) – Global coastlines. These coastlines have been assigned plate IDs using static polygons and are ready to be reconstructed to a particular geological time.

• continents (pygplates.FeatureCollection) – Continental polygons containing continental crust and volcanically-modified oceanic crust (including island arcs).

• COBs (pygplates.FeatureCollection) – Continent-ocean boundary. The COBs are represented as lines along passive margins and does not include data from active margins.

Note

The example code below will attempt to download coastlines, continents and COBs from the Muller et al. (2025) plate reconstruction model and create a gplately.PlotTopologies object.

data_server = gplately.download.DataServer("Muller2025")
rotation_model, topology_features, static_polygons = (
    data_server.get_plate_reconstruction_files()
)
model = gplately.PlateReconstruction(
    rotation_model, topology_features, static_polygons
)

coastlines, continents, COBs = data_server.get_topology_geometries()

# create a gplately.PlotTopologies object at 100Ma
gPlot = gplately.PlotTopologies(model, 100, continents, coastlines, COBs)

If the requested plate model does not have certain geometries, warning messages will be printed to alert the user.

get_valid_times()

Deprecated!!! Use DataServer.valid_times instead. Return a tuple (max_time, min_time) representing the valid time range of the plate model.

property rotation_model

Return the model rotation tree as a pygplates.RotationModel.

The rotation model is created lazily and cached on first access. By default, rotations are loaded in the mantle reference frame. If reference_frame is ReferenceFrame.PmagReferenceFrame, the model is loaded with the paleomagnetic reference frame and its corresponding anchor plate ID from plate_model_manager.

Parameters:

reference_frame (ReferenceFrame, default=ReferenceFrame.MantleReferenceFrame) – Reference frame used to build the returned rotation model.

Returns:

Rotation model for the selected plate model collection.

Return type:

pygplates.RotationModel

Raises:

Exception – If the underlying plate model manager object is not initialized.

property static_polygons

A pygplates.FeatureCollection object containing static polygons.

property time_range

Deprecated!!! Use DataServer.valid_time instead. Keep consistent with GML naming.

property to_age: float

The min age/time of the plate model.

property topology_features

A pygplates.FeatureCollection object containing topology features.

property valid_time

The period of time the plate model are valid. Return a tuple of (max time, min time).

property valid_times

Deprecated!!! Use DataServer.valid_time instead. Keep consistent with GML naming.