plate_model_manager package

Subpackages

Submodules

plate_model_manager.auxiliary module

plate_model_manager.auxiliary.check_update()[source]

Check whether configured models have newer versions on Zenodo.

For each model that includes both URL and Version metadata, this function compares the stored Zenodo version identifier against the latest available record version. It logs update status for each model and logs a summary when everything is up-to-date.

This function is intended for PMM server maintenance workflows.

plate_model_manager.auxiliary.get_plate_model(model_name: str, data_dir: str | PathLike) → PlateModel | None[source]

Return a plate model instance using online lookup with local fallback.

This helper first attempts to resolve model_name through PlateModelManager. If the PMM servers are unavailable, it falls back to creating a local, read-only PlateModel from files already present in data_dir.

Parameters:

  • model_name – Name of the plate model to resolve.

  • data_dir – Directory containing downloaded plate model data.

Returns:

A PlateModel instance, or None if the model name cannot be resolved.

Example usage:

from plate_model_manager import get_plate_model

model = get_plate_model("Muller2025", data_dir="plate-models-data-dir")
if model is not None:
    print(model.get_rotation_model())
else:
    print("Model not found.")

plate_model_manager.exceptions module

exception plate_model_manager.exceptions.InvalidConfigFile[source]

Bases: Exception

exception plate_model_manager.exceptions.LayerNotFoundInModel[source]

Bases: Exception

exception plate_model_manager.exceptions.ServerUnavailable[source]

Bases: Exception

plate_model_manager.file_fetcher module

class plate_model_manager.file_fetcher.FileFetcher[source]

Bases: object

abstractmethod fetch_file(url: str, filepath: str, filename: str | None = None, etag: str | None = None, auto_unzip: bool = True)[source]

download a file from “url” and save to “filepath” You can give a new “filename” for the file. If “etag” is given, check if etag has changed. If not changed, do not download again.

Parameters:

  • url – the url to download file from

  • filepath – location to keep the file

  • filename – new file name (optional)

  • etag – old etag. if the old etag is the same with the one on server, do not download again.

  • auto_unzip – bool flag to indicate if unzip .zip file automatically

Returns:

new etag

abstractmethod fetch_files(urls, filepaths, filenames=[], etags=[], auto_unzip: bool = True)[source]

fetch multiple files concurrently

Parameters:

  • urls – the urls to download files from

  • filepaths – location(s) to keep the files. This can be one path for all files or one path for each file.

  • filenames – new file names (optional)

  • etags – old etags. if the old etag is the same with the one on server, do not download again.

  • auto_unzip – bool flag to indicate if unzip .zip file automatically

fetch_large_file(url: str, filepath: str, filename: str | None, filesize: int | None = None, etag: str | None = None, auto_unzip: bool = True, check_etag: bool = True, timeout=(None, None))[source]
use multi-thread to fetch a large file.

LOOK HERE!!! Be careful when use this function. You cannot get partial content if the content is gzip encoded. So the file might be larger than the one download directly. It is useful when downloading large .zip file. Warning: this could be slower than single thread download. Some firewall sequences these requests to shape network traffic and defeat the purpose of this function completely.

check the etag and get content-length before calling this function

Parameters:

  • url – the file url

  • filepath – location to keep the file

  • filename – the output filename specified by caller. ignored if auto unzip compressed data.

  • filesize – the size of file (in bytes)

  • etag – old etag. if the old etag is the same with the one on server, do not download again.

  • auto_unzip – bool flag to indicate if unzip .zip file automatically

Returns:

new etag

plate_model_manager.network_aiohttp module

class plate_model_manager.network_aiohttp.AiohttpFetcher[source]

Bases: FileFetcher

fetch_file(url: str, filepath: str, filename: str | None = None, etag: str | None = None, auto_unzip: bool = True)[source]

Download a single file.

Parameters:

  • url – URL to download.

  • filepath – Folder where the file should be saved.

  • filename – Optional override name for the downloaded file.

  • etag – Optional cached ETag used to skip unchanged downloads.

  • auto_unzip – If True, automatically extract downloaded .zip files when possible.

Returns:

The new ETag value returned by the server, if any.

fetch_files(urls, filepaths, filenames=[], etags=[], auto_unzip: bool = True)[source]

Download multiple files concurrently.

Parameters:

  • urls – URLs to download.

  • filepaths – Output location(s). This can be a single folder used for every URL, or a list of per-file destinations matching urls.

  • filenames – Optional override names for the downloaded files.

  • etags – Optional cached ETag values used to skip unchanged files.

  • auto_unzip – If True, automatically extract downloaded .zip files when possible.

Returns:

A list of the new ETag values returned by the server.

plate_model_manager.network_aiohttp.fetch_file(url: str, filepath: str, filename: str | None = None, etag: str | None = None, auto_unzip: bool = True)[source]
plate_model_manager.network_aiohttp.fetch_files(urls, filepaths, etags=[], auto_unzip: bool = True, filenames=[])[source]
plate_model_manager.network_aiohttp.fetch_large_file(url: str, filepath: str, filename: str | None = None, filesize: int | None = None, etag: str | None = None, auto_unzip: bool = True, check_etag: bool = True)[source]

plate_model_manager.network_requests module

class plate_model_manager.network_requests.RequestsFetcher[source]

Bases: FileFetcher

fetch_file(url: str, filepath: str, filename: str | None = None, etag: str | None = None, auto_unzip: bool = True, timeout=(None, None))[source]
download a file from “url” and save to “filepath”

You can give a new “filename” for the file. If “etag” is given, check if etag has changed. If not changed, do not download again.

Parameters:

  • url – the url to download file from

  • filepath – location to keep the file

  • etag – old etag. if the old etag is the same with the one on server, do not download again.

  • auto_unzip – bool flag to indicate if unzip .zip file automatically

fetch_files(urls, filepaths: list | str, filenames=[], etags=[], auto_unzip: bool = True, timeout=(None, None))[source]

fetch multiple files concurrently

Parameters:

  • urls – the urls to download files from

  • filepaths – location(s) to keep the files. This can be one path for all files or one path for each file.

  • etags – old etags. if the old etag is the same with the one on server, do not download again.

  • auto_unzip – bool flag to indicate if unzip .zip file automatically

plate_model_manager.network_requests.fetch_file(url: str, filepath: str, filename: str | None = None, etag: str | None = None, auto_unzip: bool = True, timeout=(None, None))[source]
plate_model_manager.network_requests.fetch_files(urls, filepaths: list | str, etags=[], auto_unzip: bool = True, timeout=(None, None))[source]
plate_model_manager.network_requests.fetch_large_file(url: str, filepath: str, filename: str | None = None, filesize: int | None = None, etag: str | None = None, auto_unzip: bool = True, check_etag: bool = True, timeout=(None, None))[source]

plate_model_manager.plate_model module

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

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.

create_model_dir()[source]

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()[source]

Download all layers and all configured time-dependent rasters.

download_all_layers()[source]

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)[source]

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[source]

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[source]

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][source]

Return local paths for AgeGrids rasters at multiple times.

get_anchor_id_for_pmag_reference_frame() → int | None[source]

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()[source]

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()[source]

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()[source]

Return the maximum reconstruction time in Ma.

get_cfg()[source]

Return the model configuration dictionary.

Returns:

Model metadata dictionary.

Return type:

Dict

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

Return local file paths for the Coastlines layer.

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

Return local file paths for the ContinentalPolygons layer.

get_data_dir()[source]

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[source]

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[source]

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()[source]

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[source]

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][source]

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)[source]

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()[source]

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[source]

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][source]

Return local paths for SpreadingRate rasters at multiple times.

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

Return local file paths for the StaticPolygons layer.

get_supported_reference_frames() → List[ReferenceFrame][source]

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[source]

Return local file paths for the Topologies layer.

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

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)[source]

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()[source]

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

purge_layer(layer_name)[source]

Delete a local layer directory for layer_name, if present.

purge_time_dependent_rasters(raster_name)[source]

Delete local cached rasters for raster_name, if present.

set_data_dir(new_dir)[source]

Set a new parent directory for this model.

Parameters:

new_dir – New data directory path.

plate_model_manager.plate_model_manager module

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

Bases: object

Manage discovery and loading of plate reconstruction model metadata.

Model manifests can be loaded from a local file or an HTTP(S) endpoint. Retrieved model configurations are used to construct PlateModel instances.

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

Download layer data for all available models into data_dir.

Parameters:

data_dir (str) – Destination directory for downloaded model data.

get_available_model_names()[source]

Return all model keys from the loaded manifest.

Returns:

Available model names and aliases.

Return type:

list[str]

static get_default_repo_url()[source]

Return the first reachable default model-manifest URL.

Endpoints are probed in order using HTTP HEAD requests.

Returns:

Reachable manifest URL.

Return type:

str

Raises:

ServerUnavailable – If none of the default endpoints are reachable.

static get_local_available_model_names(local_dir: str)[source]

Return locally available model names from local_dir.

Parameters:

local_dir (str) – The local folder containing models.

Returns:

Names of subdirectories that look like valid local PMM models (contain .metadata.json).

Return type:

list[str]

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

Return a PlateModel for model_name.

The method resolves aliases, applies optional reference-frame handling, and instantiates PlateModel with the resolved configuration.

Parameters:

  • model_name – Model name or alias (case-insensitive). Defaults to "default".

  • data_dir – Parent directory for model downloads and cache files.

  • reference_frame – Optional reference frame. When PMAG is requested and a _pmag_ref variant exists, that variant is selected automatically.

Returns:

A configured PlateModel, or None if the model is unavailable or incompatible with the requested reference frame.

Raises:

InvalidConfigFile – If alias resolution detects an invalid alias chain.

property models: Dict

Return metadata for all configured models.

Returns:

Mapping from model names to model entries.

Return type:

Dict

Raises:

Exception – If model metadata is unavailable.

plate_model_manager.present_day_rasters module

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

Bases: object

Manage present-day raster metadata retrieval and local raster access.

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

Download or fetch a raster and return its local file path.

For file-based rasters, this method downloads and caches files under self.data_dir. For WMS rasters, it requests a GeoTIFF with the given output dimensions and bounding box, and caches the result using a hash of the WMS request URL.

Call list_present_day_rasters() to inspect available raster names.

Parameters:

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

  • width (int) – Output raster width in pixels for WMS requests.

  • height (int) – Output raster height in pixels for WMS requests.

  • bbox (list[float]) – Geographic bounding box [min_lon, min_lat, max_lon, max_lat] used for WMS requests.

  • large_file_hint (bool) – Passed to file downloader to optimize large-file handling for non-WMS rasters.

Returns:

Local path to the downloaded or cached raster file.

Return type:

str

Raises:
is_wms(_name: str, check_raster_avail_flag=True)[source]

Return whether a raster is served through WMS metadata.

Parameters:

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

  • check_raster_avail_flag (bool) – If True, validate the raster name against the loaded manifest before checking service type.

Returns:

True when the raster metadata marks the service as WMS; otherwise False.

Return type:

bool

list_present_day_rasters()[source]

Return the list of available present-day raster names.

Returns:

Available raster names from the manifest.

Return type:

list[str]

property rasters: Dict

Return raster metadata loaded from the configured manifest.

Returns:

Mapping of raster names to raster metadata.

Return type:

Dict

Raises:

Exception – If raster metadata is unexpectedly unavailable.

set_data_dir(data_dir)[source]

Set the directory used to store downloaded raster files.

Parameters:

data_dir – Directory path for local raster data.

exception plate_model_manager.present_day_rasters.RasterNameNotFound[source]

Bases: Exception

Raised when a requested raster name is not present in the manifest.

plate_model_manager.zenodo module

class plate_model_manager.zenodo.ZenodoRecord(conceptrecid)[source]

Bases: object

get_all_version_ids() → List[str][source]
get_all_versions() → List[Dict][source]
get_filenames(id: int) → List[str][source]
get_latest_version() → Dict[source]
get_latest_version_id() → int[source]
get_version(id: int) → Dict[source]

Module contents

class plate_model_manager.FileDownloader(file_url: str, meta_filepath: str, dst_dir: str, filename: str | None = None, auto_unzip: bool = True, expire_hours=12, expiry_time_format='%Y/%m/%d, %H:%M:%S', large_file_hint=False, timeout=(None, None), http_client: HttpClient = HttpClient.REQUESTS)[source]

Bases: object

class for managing single file download

check_if_expire_date_need_update()[source]
check_if_file_need_update()[source]

Decide whether the target file should be downloaded again.

Returns:

True when the file should be downloaded/re-downloaded, False when the existing local file can be reused.

Return type:

bool

Decision flow:

  1. If the metadata file is missing, return True.

  2. If the stored url differs from self.file_url (or is missing), return True.

  3. If the metadata expiry is still valid, return False.

  4. If expired (or expiry is invalid/missing), compare remote content state: - Prefer SHA-256 comparison when available. - Fall back to ETag comparison if SHA-256 cannot be obtained. - If neither reliable value is available, return True.

download_file_and_update_metadata()[source]

download a file from “file_url”, save the file in “dst_dir” and update the metadata file

Parameters:

  • file_url – the url to the file

  • metadata_file – the path to the metadata file

  • dst_dir – the destination to save the file

update_metadata()[source]

update metadata file

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

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.

create_model_dir()[source]

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()[source]

Download all layers and all configured time-dependent rasters.

download_all_layers()[source]

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)[source]

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[source]

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[source]

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][source]

Return local paths for AgeGrids rasters at multiple times.

get_anchor_id_for_pmag_reference_frame() → int | None[source]

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()[source]

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()[source]

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()[source]

Return the maximum reconstruction time in Ma.

get_cfg()[source]

Return the model configuration dictionary.

Returns:

Model metadata dictionary.

Return type:

Dict

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

Return local file paths for the Coastlines layer.

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

Return local file paths for the ContinentalPolygons layer.

get_data_dir()[source]

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[source]

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[source]

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()[source]

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[source]

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][source]

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)[source]

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()[source]

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[source]

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][source]

Return local paths for SpreadingRate rasters at multiple times.

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

Return local file paths for the StaticPolygons layer.

get_supported_reference_frames() → List[ReferenceFrame][source]

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[source]

Return local file paths for the Topologies layer.

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

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)[source]

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()[source]

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

purge_layer(layer_name)[source]

Delete a local layer directory for layer_name, if present.

purge_time_dependent_rasters(raster_name)[source]

Delete local cached rasters for raster_name, if present.

set_data_dir(new_dir)[source]

Set a new parent directory for this model.

Parameters:

new_dir – New data directory path.

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

Bases: object

Manage discovery and loading of plate reconstruction model metadata.

Model manifests can be loaded from a local file or an HTTP(S) endpoint. Retrieved model configurations are used to construct PlateModel instances.

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

Download layer data for all available models into data_dir.

Parameters:

data_dir (str) – Destination directory for downloaded model data.

get_available_model_names()[source]

Return all model keys from the loaded manifest.

Returns:

Available model names and aliases.

Return type:

list[str]

static get_default_repo_url()[source]

Return the first reachable default model-manifest URL.

Endpoints are probed in order using HTTP HEAD requests.

Returns:

Reachable manifest URL.

Return type:

str

Raises:

ServerUnavailable – If none of the default endpoints are reachable.

static get_local_available_model_names(local_dir: str)[source]

Return locally available model names from local_dir.

Parameters:

local_dir (str) – The local folder containing models.

Returns:

Names of subdirectories that look like valid local PMM models (contain .metadata.json).

Return type:

list[str]

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

Return a PlateModel for model_name.

The method resolves aliases, applies optional reference-frame handling, and instantiates PlateModel with the resolved configuration.

Parameters:

  • model_name – Model name or alias (case-insensitive). Defaults to "default".

  • data_dir – Parent directory for model downloads and cache files.

  • reference_frame – Optional reference frame. When PMAG is requested and a _pmag_ref variant exists, that variant is selected automatically.

Returns:

A configured PlateModel, or None if the model is unavailable or incompatible with the requested reference frame.

Raises:

InvalidConfigFile – If alias resolution detects an invalid alias chain.

property models: Dict

Return metadata for all configured models.

Returns:

Mapping from model names to model entries.

Return type:

Dict

Raises:

Exception – If model metadata is unavailable.

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

Bases: object

Manage present-day raster metadata retrieval and local raster access.

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

Download or fetch a raster and return its local file path.

For file-based rasters, this method downloads and caches files under self.data_dir. For WMS rasters, it requests a GeoTIFF with the given output dimensions and bounding box, and caches the result using a hash of the WMS request URL.

Call list_present_day_rasters() to inspect available raster names.

Parameters:

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

  • width (int) – Output raster width in pixels for WMS requests.

  • height (int) – Output raster height in pixels for WMS requests.

  • bbox (list[float]) – Geographic bounding box [min_lon, min_lat, max_lon, max_lat] used for WMS requests.

  • large_file_hint (bool) – Passed to file downloader to optimize large-file handling for non-WMS rasters.

Returns:

Local path to the downloaded or cached raster file.

Return type:

str

Raises:
is_wms(_name: str, check_raster_avail_flag=True)[source]

Return whether a raster is served through WMS metadata.

Parameters:

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

  • check_raster_avail_flag (bool) – If True, validate the raster name against the loaded manifest before checking service type.

Returns:

True when the raster metadata marks the service as WMS; otherwise False.

Return type:

bool

list_present_day_rasters()[source]

Return the list of available present-day raster names.

Returns:

Available raster names from the manifest.

Return type:

list[str]

property rasters: Dict

Return raster metadata loaded from the configured manifest.

Returns:

Mapping of raster names to raster metadata.

Return type:

Dict

Raises:

Exception – If raster metadata is unexpectedly unavailable.

set_data_dir(data_dir)[source]

Set the directory used to store downloaded raster files.

Parameters:

data_dir – Directory path for local raster data.

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

Return a plate model instance using online lookup with local fallback.

This helper first attempts to resolve model_name through PlateModelManager. If the PMM servers are unavailable, it falls back to creating a local, read-only PlateModel from files already present in data_dir.

Parameters:

  • model_name – Name of the plate model to resolve.

  • data_dir – Directory containing downloaded plate model data.

Returns:

A PlateModel instance, or None if the model name cannot be resolved.

Example usage:

from plate_model_manager import get_plate_model

model = get_plate_model("Muller2025", data_dir="plate-models-data-dir")
if model is not None:
    print(model.get_rotation_model())
else:
    print("Model not found.")