API Reference

PlateModelManager

The plate_model_manager.PlateModelManager class manages the plate reconstruction models. You can use this class to do the things listed below.

• Get a list of available model names.

• Get a plate_model_manager.PlateModel object for a specific model name.

• Download all models into a folder.

class plate_model_manager.PlateModelManager(model_manifest: str = '', timeout=(None, None))

Bases: object

Manage a set of publicly available plate reconstruction models. The model files are hosted on EarthByte servers. You need Internet connection to use this class and download the files.

__init__(model_manifest: str = '', timeout=(None, None))

Constructor. Create a PlateModelManager instance. You need Internet connection to create an instance of this class. If you don’t have Internet connection, use PlateModel class directly in readonly mode. Visit this page to see an example.

Parameters:

model_manifest – The URL to a models.json metadata file. Normally you don’t need to provide this parameter unless you would like to setup your own plate model server.

download_all_models(data_dir: str = './') → None

Download all available models into the data_dir.

Parameters:

data_dir (str) – The folder to save the model files.

get_available_model_names()

Return the names of available models as a list.

static get_default_repo_url()

Return the URL to the configuration data of models.

static get_local_available_model_names(local_dir: str)

Return a list of model names in a local folder.

Parameters:

local_dir (str) – The local folder containing models.

get_model(model_name: str = 'default', data_dir: str = '.', reference_frame: ReferenceFrame | None = None) → PlateModel | None

Retrieve a PlateModel object for a given plate model name.

This method resolves model aliases and creates a PlateModel instance configured with the model’s metadata. Alias resolution follows chains and detects circular references to prevent infinite loops.

Call get_available_model_names() to see a list of available model names and valid aliases.

Parameters:

• model_name – The name of the plate model to retrieve. Case-insensitive. Can be a direct model name, an alias, or a variant with reference frame suffix (e.g., “model_pmag_ref”). Defaults to “default”.

• data_dir – The folder path to save downloaded plate model files. Defaults to the current directory (“.”); This path can be changed later with PlateModel.set_data_dir().

• reference_frame – Optional reference frame for the plate model. If set to ReferenceFrame.PmagReferenceFrame and a “_pmag_ref” variant exists, that variant will be loaded automatically.

Returns:

A PlateModel object if the model is found and successfully created, None if the model name is not found in the manifest.

Raises:

InvalidConfigFile – If a circular alias chain is detected or if the maximum alias resolution depth is exceeded, indicating an error in the model manifest.

Example:

>>> pmm = PlateModelManager()
>>> model = pmm.get_model("muller2016", data_dir="./models")
>>> if model:
...     model.download_all_layers()

PlateModel

The plate_model_manager.PlateModel class manages the files in a plate reconstruction model. You can use this class to do the things listed below.

• Get a list of available layers in a plate model.

• Download the rotation file(s).

• Download the layer file(s) for a specific layer.

• Download time-dependent raster files.

• Download all files in a plate model.

class plate_model_manager.PlateModel(model_name: str, model_cfg=None, data_dir: str = '.', reference_frame: ReferenceFrame | None = None, readonly=False, timeout=(None, None))

Bases: object

Download and manage files required for a plate reconstruction model.

👀👇 LOOK HERE!!! 👀👇

Normally you should always use PlateModelManager.get_model() to get a PlateModel object. Create a PlateModel object directly only when you don’t have Internet connection and would like to use the local model files in readonly mode. Do not create a PlateModel object directly if you have no idea what’s going on.

See also

Use PlateModel class in readonly mode.

__init__(model_name: str, model_cfg=None, data_dir: str = '.', reference_frame: ReferenceFrame | None = None, readonly=False, timeout=(None, None))

Constructor. Create a PlateModel instance.

Parameters:

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

• model_cfg – The model configuration in JSON format. The configuration is either downloaded from the server or loaded from a local file .metadata.json. If you are confused by this parameter, use PlateModelManager.get_model() to get a PlateModel object instead.

• data_dir (str, default=".") – The folder path to save the model data.

• readonly (bool, default=False) – If this flag is set to True, The PlateModel object will use the files in the local folder and will not attempt to download/update the files from the server.

• timeout – Network connection timeout parameter.

create_model_dir()

Ensure the model folder exists and refresh local metadata files.

This method creates self.model_dir when missing, then always rewrites .metadata.json and readme.txt from the current in-memory model configuration, even if the folder already exists.

Returns:

The model folder path.

Return type:

str

Raises:

Exception – If running in readonly mode, if self.model_dir is invalid/empty, or if the model path exists as a file.

download_all()

Download everything in this plate model.

download_all_layers()

Download all layers. This function calls download_layer_files() on every available layer.

download_time_dependent_rasters(raster_name, times=None)

Download time-dependent rasters for a given raster name.

Call get_avail_time_dependent_raster_names() to see all the available raster names in this model.

Parameters:

• raster_name – the raster name of interest

• times – if not given, download from begin to end with 1My interval

get_COBs(return_none_if_not_exist: bool = False) → List[str] | None

Return a list of Continent-Ocean Boundaries files.

get_age_grid(time: int | float, reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → str

Return a local path for the age grid raster file at a given time.

get_age_grids(times: List[int | float], reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → List[str]

Return local paths for the age grid raster files at given times.

get_avail_layers()

Get all available layers in this plate model.

get_avail_time_dependent_raster_names()

Return all time-dependent raster names in this plate model.

get_big_time()

The max (big number in Ma) reconstruction time in the model.

get_cfg()

Return the model configuration.

get_coastlines(return_none_if_not_exist: bool = False) → List[str] | None

Return a list of coastlines files.

get_continental_polygons(return_none_if_not_exist: bool = False) → List[str] | None

Return a list of continental polygons files.

get_data_dir()

Return the path to a folder (parent folder of the model dir) containing a set of downloaded models.

get_layer(layer_name: str, return_none_if_not_exist: bool = False) → List[str] | None

Get a list of layer files by a layer name. Call get_avail_layers() to get all the available layer names.

Raise LayerNotFoundInModel exception to get user’s attention by default. Set return_none_if_not_exist to True if you don’t want to see the LayerNotFoundInModel exception.

Parameters:

• layer_name – The layer name of interest.

• return_none_if_not_exist – If set to True, return None when the layer does not exist in the model.

Returns:

A list of file names or None if return_none_if_not_exist is set to True.

:raises LayerNotFoundInModel: Raise this exception if the layer name does not exist in this model.

get_layer_metadata(layer_name: str, return_none_if_not_exist: bool = False) → Dict | None

Return metadata for a layer as a dictionary.

In writable mode, this method ensures the layer is downloaded/updated before reading metadata. In readonly mode, it reads from the local layer folder directly.

Parameters:

• layer_name – The layer name of interest.

• return_none_if_not_exist – If set to True, return None when the layer does not exist in the model.

Returns:

Layer metadata dictionary, or None if return_none_if_not_exist is set to True and the layer is not found.

:raises LayerNotFoundInModel: Raise this exception if the

layer name does not exist in this model.

Raises:

Exception – If the layer metadata file is missing.

get_model_dir()

Return the path to a folder containing the model files.

get_raster(raster_name: str, time: int | float, reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → str

Return a local path for a single time-dependent raster.

The final raster key is built from raster_name and optional suffixes from generated_from and reference_frame (in that order), matching the naming convention used in model["TimeDepRasters"].

Parameters:

• raster_name – Base raster name in TimeDepRasters (for example, "AgeGrids").

• time – Reconstruction time (Ma) to fetch.

• reference_frame – Optional reference-frame suffix to append to the raster name.

• generated_from – Optional generation-method suffix to append to the raster name.

Returns:

Local file path for the requested raster at time.

Raises:

Exception – If this model has no TimeDepRasters entry, if the constructed raster name is not configured, if the file is missing in readonly mode, or if a download fails in writable mode.

get_rasters(raster_name: str, times: List[int | float], reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → List[str]

Return local paths for a sequence of time-dependent rasters.

The final raster key is built from raster_name and optional suffixes from generated_from and reference_frame (in that order), matching the naming convention used in model["TimeDepRasters"].

Parameters:

• raster_name – Base raster name in TimeDepRasters (for example, "AgeGrids").

• times – Reconstruction times (Ma) to fetch.

• reference_frame – Optional reference-frame suffix to append to the raster name.

• generated_from – Optional generation-method suffix to append to the raster name.

Returns:

Local file paths for the requested times, in the same order as times.

Raises:

Exception – If this model has no TimeDepRasters entry, if the constructed raster name is not configured, if a requested file is missing in readonly mode, or if a download fails in writable mode.

get_rotation_model(reference_frame: ReferenceFrame | None = None)

Return rotation files, and optionally a PMAG anchor plate ID.

Rotation files are read from the local model directory in readonly mode, or downloaded/updated first in writable mode.

When reference_frame is ReferenceFrame.PmagReferenceFrame, this method also returns the anchor plate ID required by consumers that need PMAG reference frame rotations. The anchor ID is read from model["Attributes"]["PmagReferenceFrameAnchorPID"] when present. If that value is missing but this model is already under PMAG reference frame, set the anchor ID to 0, such as matthews2016_pmag_ref model.

Parameters:

reference_frame – Optional reference frame for the returned rotation model. (since version 1.4.0)

Returns:

If reference_frame is PMAG, returns (rotation_files, anchor_pid) where rotation_files is a list of .rot/.grot file paths and anchor_pid is an integer. Otherwise returns only rotation_files.

Raises:

Exception – If PMAG is requested but the model is not PMAG and Attributes.PmagReferenceFrameAnchorPID is not defined.

get_small_time()

The min (small number in Ma) reconstruction time in the model.

get_spreading_rate_grid(time: int | float, reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → str

Return a local path for the spreading rate grid raster file at a given time.

get_spreading_rate_grids(times: List[int | float], reference_frame: ReferenceFrame | None = None, generated_from: GenerationMethod | None = None) → List[str]

Return local paths for the spreading rate grid raster files at given times.

get_static_polygons(return_none_if_not_exist: bool = False) → List[str] | None

Return a list of static polygons files.

get_topologies(return_none_if_not_exist: bool = False) → List[str] | None

Return a list of topologies files.

static is_model_dir(folder_path: str)

Return True if the folder contains files of a plate model, otherwise False.

property model_dir

Return the folder path for this model under data_dir.

purge()

Remove the model folder and everything inside the folder.

purge_layer(layer_name)

Remove the layer folder of the given layer name.

purge_time_dependent_rasters(raster_name)

Remove the raster folder of the given raster name.

set_data_dir(new_dir)

Change the folder (parent folder of the model dir) in which you would like to save your model.

PresentDayRasterManager

The plate_model_manager.PresentDayRasterManager class manages the present-day rasters. You can use this class to do the things listed below.

• Get a list of available present-day raster names.

• Download a specific present-day raster.

class plate_model_manager.PresentDayRasterManager(data_dir='present-day-rasters', raster_manifest=None)

Bases: object

Manage the present-day rasters.

__init__(data_dir='present-day-rasters', raster_manifest=None)

Constructor. Create a PresentDayRasterManager instance.

Parameters:

• raster_manifest – The URL to a present_day_rasters.json metadata file. Normally you don’t need to provide this parameter unless you would like to setup your own present-day raster server.

• data_dir – The path to a folder to save the present-day raster files.

get_raster(_name: str, width=1800, height=800, bbox=[-180, -80, 180, 80], large_file_hint=True)

Download a raster file by name, save the raster file in self.data_dir and return the local path to the raster file.

Call list_present_day_rasters() to see a list of available present-day raster names.

Parameters:

_name (str) – The raster name of interest.

Returns:

The local path to the downloaded raster file.

Return type:

str

is_wms(_name: str, check_raster_avail_flag=True)

Return True if the raster is served by Web Map Service, otherwise False

Parameters:

• _name (str) – The raster name of interest.

• check_raster_avail_flag (bool) – If the flag is True, validate the raster name against the raster configuration.

list_present_day_rasters()

Return a list of available present-day rasters.

set_data_dir(data_dir)

Set a new data folder to save the present-day rasters.

Auxiliary Function

Auxiliary functon for users’ convenience.

plate_model_manager.get_plate_model(model_name: str, data_dir: str | PathLike) → PlateModel | None

Convenient function to create a PlateModel instance using best effort. First, try to get the plate model with PlateModelManager. If the servers cannot be reached, try to use the local plate model files which were previously downloaded.

Parameters:

• model_name – the plate model name of interest

• data_dir – The folder to save the plate model files.

Returns:

a PlateModel object or None if the plate model name is no good.