gplately.PlateModel

class gplately.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).

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

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.

Methods

__init__(model_name[, model_cfg, data_dir, ...])	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(raster_name)	Download and cache a time series of rasters for raster_name.
get_COBs([return_none_if_not_exist])	Return local file paths for the COBs layer.
get_age_grid(time[, reference_frame, ...])	Return a local path for an AgeGrids raster at time Ma.
get_age_grids(times[, reference_frame, ...])	Return local paths for AgeGrids rasters at multiple times.
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_none_if_not_exist])	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(layer_name[, return_none_if_not_exist])	Return local file paths for a geometry layer.
get_layer_metadata(layer_name[, ...])	Return metadata for a layer as a dictionary.
get_model_dir()	Return the local directory path for this model.
get_raster(raster_name, time[, ...])	Return a local path for a single time-dependent raster.
get_rasters(raster_name, times[, ...])	Return local paths for a sequence of time-dependent rasters.
get_rotation_model([reference_frame])	Return rotation files, and optionally a PMAG anchor plate ID.
get_small_time()	Return the minimum reconstruction time in Ma.
get_spreading_rate_grid(time[, ...])	Return a local path for a SpreadingRate raster at time Ma.
get_spreading_rate_grids(times[, ...])	Return local paths for SpreadingRate rasters at multiple times.
get_static_polygons([return_none_if_not_exist])	Return local file paths for the StaticPolygons layer.
get_topologies([return_none_if_not_exist])	Return local file paths for the Topologies layer.
is_model_dir(folder_path)	Return whether folder_path looks like a local model directory.
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.

Attributes

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

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_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 writable mode, layer data are downloaded or updated before paths are returned. In readonly mode, paths are resolved from the local model folder.

Parameters:

• layer_name – Layer name. Call get_avail_layers() to list valid names.

• return_none_if_not_exist – If True, return None instead of raising when the layer is missing.

Returns:

List of matching layer file paths, or None when return_none_if_not_exist=True and the layer is missing.

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_topologies(return_none_if_not_exist: bool = False) → List[str] | None

Return local file paths for the Topologies layer.

static is_model_dir(folder_path: str)

Return whether folder_path looks like a local model directory.

property model: Dict

Return model metadata for this instance.

Returns:

Model configuration dictionary.

Return type:

Dict

Raises:

Exception – If model configuration is unexpectedly unavailable.

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.