PlateModel

class 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 for a plate reconstruction model.

In most workflows, create instances through PlateModelManager.get_model() so model configuration and metadata are resolved automatically. Direct instantiation is primarily intended for advanced or offline use (for example, readonly=True with pre-downloaded local files).

Note

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.

See also

Use PlateModel class in readonly mode.

Methods

__init__	Create a PlateModel instance.
create_model_dir	Ensure the model folder exists and refresh local metadata files.
download_all	Download all layers and all configured time-dependent rasters.
download_all_layers	Download all configured layers for this model.
download_time_dependent_rasters	Download and cache a time series of rasters for raster_name.
get_COBs	Return local file paths for the COBs layer.
get_age_grid	Return a local path for an AgeGrids raster at time Ma.
get_age_grids	Return local paths for AgeGrids rasters at multiple times.
get_anchor_id_for_pmag_reference_frame	Return the PMAG anchor plate ID when this model supports PMAG.
get_avail_layers	Return all available geometry layer names in this model.
get_avail_time_dependent_raster_names	Return configured names of time-dependent rasters.
get_big_time	Return the maximum reconstruction time in Ma.
get_cfg	Return the model configuration dictionary.
get_coastlines	Return local file paths for the Coastlines layer.
get_continental_polygons	Return local file paths for the ContinentalPolygons layer.
get_data_dir	Return the parent directory containing downloaded models.
get_layer	Return local file paths for a geometry layer in this model.
get_layer_metadata	Return metadata for a layer as a dictionary.
get_model_dir	Return the local directory path for this model.
get_raster	Return a local path for a single time-dependent raster.
get_rasters	Return local paths for a sequence of time-dependent rasters.
get_rotation_model	Return rotation files, and optionally a PMAG anchor plate ID.
get_small_time	Return the minimum reconstruction time in Ma.
get_spreading_rate_grid	Return a local path for a SpreadingRate raster at time Ma.
get_spreading_rate_grids	Return local paths for SpreadingRate rasters at multiple times.
get_static_polygons	Return local file paths for the StaticPolygons layer.
get_supported_reference_frames	Return the reference frames which this model supports.
get_topologies	Return local file paths for the Topologies layer.
get_vector_data	Return local file paths for the vector data in this model.
is_model_dir	Return whether folder_path looks like a local model directory.
purge	Delete the model directory and all files under it, if present.
purge_layer	Delete a local layer directory for layer_name, if present.
purge_time_dependent_rasters	Delete local cached rasters for raster_name, if present.
set_data_dir	Set a new parent directory for this model.

Attributes

model	Return model metadata for this instance.
model_dir	Return the model folder path under data_dir.

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

Create a PlateModel instance.

Parameters:

• model_name (str) – Model name to load.

• model_cfg – Model configuration dictionary. This is typically provided by PlateModelManager.get_model(), or loaded from local metadata in readonly mode.

• data_dir (str, default=".") – Parent directory used to store model files.

• reference_frame (ReferenceFrame or None) – Default reference frame associated with this instance.

• readonly (bool, default=False) – If True, use only local files and do not perform downloads or updates.

• timeout – Network timeout tuple passed to file downloads.

Raises:

Exception – If readonly=True and the local model directory is invalid.

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 all layers and all configured time-dependent rasters.

download_all_layers()

Download all configured layers for this model.

This includes Rotations when available, plus every entry under model["Layers"].

download_time_dependent_rasters(raster_name, times=None)

Download and cache a time series of rasters for raster_name.

Parameters:

• raster_name – Raster key in model["TimeDepRasters"].

• times – Iterable of reconstruction times (Ma). If omitted, download every integer time from SmallTime to BigTime inclusive.

Raises:

Exception – If called in readonly mode or raster configuration is missing.

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

Return local file paths for the COBs layer.

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

Return a local path for an AgeGrids raster at time Ma.

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

Return local paths for AgeGrids rasters at multiple times.

get_anchor_id_for_pmag_reference_frame() → int | None

Return the PMAG anchor plate ID when this model supports PMAG.

Models that expose PMAG through Attributes.PmagReferenceFrameAnchorPID return that configured anchor plate ID. Dedicated _pmag_ref models use 0 as the implicit PMAG anchor plate ID. Mantle-only models return None.

Returns:

PMAG anchor plate ID, or None when PMAG is unsupported.

Return type:

int or None

get_avail_layers()

Return all available geometry layer names in this model.

Returns:

Layer names.

Return type:

list[str]

Raises:

Exception – If model configuration is missing.

get_avail_time_dependent_raster_names()

Return configured names of time-dependent rasters.

Returns:

Raster names from TimeDepRasters, or an empty list when the model defines none.

Return type:

list[str]

get_big_time()

Return the maximum reconstruction time in Ma.

get_cfg()

Return the model configuration dictionary.

Returns:

Model metadata dictionary.

Return type:

Dict

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

Return local file paths for the Coastlines layer.

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

Return local file paths for the ContinentalPolygons layer.

get_data_dir()

Return the parent directory containing downloaded models.

Returns:

Data directory path.

Return type:

str

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

Return local file paths for a geometry layer in this model.

In writable mode, this function will check if the layer files exist on the local computer. If the files don’t exist or need to be updated, they are downloaded or updated before paths are returned.

In readonly mode, paths are resolved from the local model folder without checking for updates.

Note

This function is for accessing geometry layers(vector data), such as Coastlines, Topologies, StaticPolygons, etc. Call get_avail_layers() to get a list of available layer names. For accessing time-dependent rasters, use get_raster() or get_rasters().

Parameters:

• layer_name – Layer name. Call get_avail_layers() to get a list of available layer names.

• return_none_if_not_exist – If True, return None instead of raising exception when the layer does not exist.

Returns:

List of matching layer file paths, or None when return_none_if_not_exist=True and the layer does not exist.

Raises:

LayerNotFoundInModel – If the layer does not exist and return_none_if_not_exist is False.

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.

• Exception – If the layer metadata file is missing.

get_model_dir()

Return the local directory path for this model.

In writable mode, the model directory is created when missing.

Returns:

Absolute or relative path to this model folder.

Return type:

str

Raises:

Exception – If the folder is missing in readonly mode.

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()

Return the minimum reconstruction time in Ma.

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

Return a local path for a SpreadingRate raster at time Ma.

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

Return local paths for SpreadingRate rasters at multiple times.

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

Return local file paths for the StaticPolygons layer.

get_supported_reference_frames() → List[ReferenceFrame]

Return the reference frames which this model supports.

If the model name ends with “pmag_ref”, we will consider it as a PMAG reference frame model. Otherwise, it is a mantle reference frame model by default.

If the model configuration has a PmagReferenceFrameAnchorPID attribute, we will consider this model supports both PMAG and mantle reference frame, such as Zahirovic2022 model. The same rotation files can be used for both reference frames, but with different default anchor plate ID. For mantle reference frame, the anchor plate ID is usually 0. For PMAG reference frame, the anchor plate ID is usually a non-zero integer defined in the model configuration as PmagReferenceFrameAnchorPID attribute.

Returns:

A list of supported reference frames.

Return type:

list[ReferenceFrame]

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

Return local file paths for the Topologies layer.

get_vector_data(name: str, return_none_if_not_exist: bool = False) → List[str] | None

Return local file paths for the vector data in this model.

This is an alias for get_layer() to access vector data layers such as Coastlines, Topologies, StaticPolygons, etc. The purpose of this function is to provide a more intuitive API for users who may wonder whether the term “layer” means vector layer or raster layer. You can use this function to get file paths for vector data available in this model by specifying its name.

Call get_avail_layers() to get a list of available names for vector data.

Parameters:

• name – The vector data name which is the same with the layer_name in get_layer(). Call get_avail_layers() to get a list of available vector layer names.

• return_none_if_not_exist – If True, return None instead of raising exception when the vector data doesn’t exist.

Returns:

List of vector data file paths, or None when return_none_if_not_exist=True and the vector data doesn’t exist.

static is_model_dir(folder_path: str)

Return whether folder_path looks like a local model directory.

property model_dir

Return the model folder path under data_dir.

purge()

Delete the model directory and all files under it, if present.

purge_layer(layer_name)

Delete a local layer directory for layer_name, if present.

purge_time_dependent_rasters(raster_name)

Delete local cached rasters for raster_name, if present.

set_data_dir(new_dir)

Set a new parent directory for this model.

Parameters:

new_dir – New data directory path.