gplately.DataServer

class gplately.DataServer(file_collection, data_dir=None, verbose=True)

Bases: object

Download the plate reconstruction models from the EarthByte server.

The DataServer object downloads the model files to the GPlately cache folder. If the same model is requested again, a new DataServer instance will retrieve the files from the cache – provided they haven’t been moved or deleted.

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__(file_collection, data_dir=None, verbose=True)

Constructor. Create a DataServer object.

Example

# create a DataServer object for the Cao2024 model (https://zenodo.org/records/11536686)
data_server = gplately.DataServer("Cao2024")

Parameters:

• file_collection (str) – The model name of interest.

• verbose (bool, default=True) – Toggle print messages regarding server/internet connection status, file availability, etc.

Methods

__init__(file_collection[, data_dir, verbose])	Constructor.
get_age_grid(times)	Download the seafloor age grids for the plate model.
get_feature_data([feature_data_id_string])	Downloads assorted geological feature data from web servers (i.e. GPlates 2.3 sample data) into the "gplately" cache.
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.
cache_path	The location of DataServer cache on your computer.
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	A pygplates.RotationModel object for the plate reconstruction model.
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.

property 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])

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

See also

DataServer.cache_path

The available seafloor age grids are listed below.

• Muller et al. 2019

  • file_collection = Muller2019

  • Time range: 0-250 Ma

  • Seafloor age grids in netCDF format.

• Muller et al. 2016

  • file_collection = Muller2016

  • Time range: 0-240 Ma

  • Seafloor age grids in netCDF format.

• Seton et al. 2012

  • file_collection = Seton2012

  • Time range: 0-200 Ma

  • Seafloor age grids in netCDF format.

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("Muller2019")
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 Müller et al. (2019) seafloor age grids for 0Ma, 1Ma and 100 Ma:

data_server = gplately.DataServer("Muller2019")
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("Muller2019")
print(model.get_rasters("AgeGrids", times=[10, 20, 30]))
print(model.get_raster("AgeGrids", time=100))

get_feature_data(feature_data_id_string=None)

Downloads assorted geological feature data from web servers (i.e. GPlates 2.3 sample data) into the “gplately” cache.

Currently, DataServer supports the following feature data:

• 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: .gpml

    • 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.

Parameters:

feature_data_id_string (str, default=None) – A string to identify which feature data to download to the cache (see list of supported feature data above).

Returns:

feature_data_filenames – If a single set of feature data is downloaded, a single pyGPlates FeatureCollection object is returned. Otherwise, a list containing multiple pyGPlates FeatureCollection objects is returned (like for SeafloorFabric). In the latter case, feature reconstruction and plotting may have to be done iteratively.

Return type:

instance of <pygplates.FeatureCollection>, or list of instance <pygplates.FeatureCollection>

Raises:

ValueError – If a feature_data_id_string is not provided.

Examples

For examples of plotting data downloaded with get_feature_data, see GPlately’s sample notebook 05 - Working With Feature Geometries here.

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 Müller et al. (2019) plate reconstruction model and create a gplately.PlateReconstruction object.

import gplately

data_server = gplately.DataServer("Muller2019")
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)

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

See also

DataServer.cache_path

The available seafloor spreading rate grids are listed below.

• Clennett et al. 2020

  • file_collection = Clennett2020

  • Time range: 0-250 Ma

  • Seafloor spreading rate grids in netCDF format.

Parameters:

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

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 Müller et al. (2019) plate reconstruction model and create a gplately.PlotTopologies object.

data_server = gplately.download.DataServer("Muller2019")
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

A pygplates.RotationModel object for the plate reconstruction model.

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.