plate_model_manager package

Submodules

plate_model_manager.auxiliary module

plate_model_manager.auxiliary.check_update()[source]: Check if new versions of plate models are available on Zenodo. Mainly used by Michael Chin to update the PMM server.

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

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.

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 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, 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.
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_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)[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 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.

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

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

Download all available models into the data_dir.

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

get_available_model_names()[source]: Return the names of available models as a list.

static get_default_repo_url()[source]: Return the URL to the configuration data of models.

static get_local_available_model_names(local_dir: str)[source]

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

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

property models: Dict: The metadata for all the models.

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 the present-day rasters.

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

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

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()[source]: Return a list of available present-day rasters.

property rasters: Dict: The metadata of rasters.

set_data_dir(data_dir)[source]: Set a new data folder to save the present-day rasters.

exception plate_model_manager.present_day_rasters.RasterNameNotFound[source]: Bases: Exception

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_file_links(id: int) → List[str][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.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 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.

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 everything in this plate model.

download_all_layers()[source]: Download all layers. This function calls download_layer_files() on every available layer.

download_time_dependent_rasters(raster_name, times=None)[source]

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[source]: 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[source]: 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][source]: Return local paths for the age grid raster files at given times.

get_avail_layers()[source]: Get all available layers in this plate model.

get_avail_time_dependent_raster_names()[source]: Return all time-dependent raster names in this plate model.

get_big_time()[source]: The max (big number in Ma) reconstruction time in the model.

get_cfg()[source]: Return the model configuration.

get_coastlines(return_none_if_not_exist: bool = False) → List[str] | None[source]: Return a list of coastlines files.

get_continental_polygons(return_none_if_not_exist: bool = False) → List[str] | None[source]: Return a list of continental polygons files.

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

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

Raises:: Exception – If the layer metadata file is missing.

get_model_dir()[source]: 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[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]: 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[source]: 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][source]: 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[source]: Return a list of static polygons files.

get_topologies(return_none_if_not_exist: bool = False) → List[str] | None[source]: Return a list of topologies files.

static is_model_dir(folder_path: str)[source]: Return True if the folder contains files of a plate model, otherwise False.

property model: Dict: The model metadata.

property model_dir: Return the folder path for this model under data_dir.

purge()[source]: Remove the model folder and everything inside the folder.

purge_layer(layer_name)[source]: Remove the layer folder of the given layer name.

purge_time_dependent_rasters(raster_name)[source]: Remove the raster folder of the given raster name.

set_data_dir(new_dir)[source]: Change the folder (parent folder of the model dir) in which you would like to save your model.

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

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.

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

Download all available models into the data_dir.

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

get_available_model_names()[source]: Return the names of available models as a list.

static get_default_repo_url()[source]: Return the URL to the configuration data of models.

static get_local_available_model_names(local_dir: str)[source]

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

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

property models: Dict: The metadata for all the models.

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

Bases: object

Manage the present-day rasters.

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

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

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()[source]: Return a list of available present-day rasters.

property rasters: Dict: The metadata of rasters.

set_data_dir(data_dir)[source]: Set a new data folder to save the present-day rasters.

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

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.