plate_model_manager package

Submodules

plate_model_manager.auxiliary module

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

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

Parameters:

• model_name – the plate model name of interest

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

Returns:

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

plate_model_manager.exceptions module

exception plate_model_manager.exceptions.InvalidConfigFile

Bases: Exception

exception plate_model_manager.exceptions.LayerNotFoundInModel

Bases: Exception

exception plate_model_manager.exceptions.ServerUnavailable

Bases: Exception

plate_model_manager.file_fetcher module

class plate_model_manager.file_fetcher.FileFetcher

Bases: object

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

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)

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

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

Bases: FileFetcher

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

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)

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)

plate_model_manager.network_aiohttp.fetch_files(urls, filepaths, etags=[], auto_unzip: bool = True)

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)

plate_model_manager.network_requests module

class plate_model_manager.network_requests.RequestsFetcher

Bases: FileFetcher

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

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

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

plate_model_manager.network_requests.fetch_files(urls, filepaths: list | str, etags=[], auto_unzip: bool = True, timeout=(None, None))

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

plate_model_manager.plate_model module

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

Bases: object

Download and manage files required for a plate reconstruction model.

👀👇 LOOK HERE!!! 👀👇

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

See also

Use PlateModel class in readonly mode.

create_model_dir()

Create a folder with a file .metadata.json in it to keep the model files.

download_all()

Download everything in this plate model.

download_all_layers()

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

download_time_dependent_rasters(raster_name, times=None)

Download time-dependent rasters for a given raster name.

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

Parameters:

• raster_name – the raster name of interest

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

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

Return a list of Continent-Ocean Boundaries files.

get_avail_layers()

Get all available layers in this plate model.

get_avail_time_dependent_raster_names()

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

get_big_time()

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

get_cfg()

Return the model configuration.

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

Return a list of coastlines files.

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

Return a list of continental polygons files.

get_data_dir()

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

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

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

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

Parameters:

• layer_name – The layer name of interest.

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

Returns:

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

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

get_model_dir()

Return the path to a folder containing the model files.

get_raster(raster_name: str, time: int | float) → str

Return a local path for the raster file.

Parameters:

time (int or float) – A single time of interest.

Returns:

A local path of the raster file.

Return type:

str

get_rasters(raster_name: str, times: List[int | float]) → List[str]

Return local paths for the raster files.

Parameters:

times – A list of times

Returns:

A list of local paths

get_rotation_model()

Return a list of rotation files.

get_small_time()

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

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

Return a list of static polygons files.

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

Return a list of topologies files.

static is_model_dir(folder_path: str)

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

property model: Dict

The model metadata.

purge()

Remove the model folder and everything inside the folder.

purge_layer(layer_name)

Remove the layer folder of the given layer name.

purge_time_dependent_rasters(raster_name)

Remove the raster folder of the given raster name.

set_data_dir(new_dir)

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

plate_model_manager.plate_model_manager module

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

Bases: object

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

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

Download all available models into the data_dir.

Parameters:

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

get_available_model_names()

Return the names of available models as a list.

static get_default_repo_url()

Return the URL to the configuration data of models.

static get_local_available_model_names(local_dir: str)

Return a list of model names in a local folder.

Parameters:

local_dir (str) – The local folder containing models.

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

Return a PlateModel object for a given plate model name.

Call get_available_model_names() to see a list of available plate model names.

Parameters:

• model_name – the plate model name of interest

• data_dir – The folder to save the plate model files. This data_dir can be changed with PlateModel.set_data_dir() later.

Returns:

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

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)

Bases: object

Manage the present-day rasters.

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

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

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

Parameters:

_name (str) – The raster name of interest.

Returns:

The local path to the downloaded raster file.

Return type:

str

is_wms(_name: str, check_raster_avail_flag=True)

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

Parameters:

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

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

list_present_day_rasters()

Return a list of available present-day rasters.

property rasters: Dict

The metadata of rasters.

set_data_dir(data_dir)

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

exception plate_model_manager.present_day_rasters.RasterNameNotFound

Bases: Exception

plate_model_manager.zenodo module

class plate_model_manager.zenodo.ZenodoRecord(conceptrecid)

Bases: object

get_all_version_ids() → List[str]

get_all_versions() → List[Dict]

get_file_links(id) → List[str]

get_filenames(id) → List[str]

get_latest_version() → Dict

get_latest_version_id() → str

get_version(id) → Dict

Module contents

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

Bases: object

Download and manage files required for a plate reconstruction model.

👀👇 LOOK HERE!!! 👀👇

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

See also

Use PlateModel class in readonly mode.

create_model_dir()

Create a folder with a file .metadata.json in it to keep the model files.

download_all()

Download everything in this plate model.

download_all_layers()

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

download_time_dependent_rasters(raster_name, times=None)

Download time-dependent rasters for a given raster name.

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

Parameters:

• raster_name – the raster name of interest

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

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

Return a list of Continent-Ocean Boundaries files.

get_avail_layers()

Get all available layers in this plate model.

get_avail_time_dependent_raster_names()

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

get_big_time()

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

get_cfg()

Return the model configuration.

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

Return a list of coastlines files.

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

Return a list of continental polygons files.

get_data_dir()

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

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

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

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

Parameters:

• layer_name – The layer name of interest.

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

Returns:

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

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

get_model_dir()

Return the path to a folder containing the model files.

get_raster(raster_name: str, time: int | float) → str

Return a local path for the raster file.

Parameters:

time (int or float) – A single time of interest.

Returns:

A local path of the raster file.

Return type:

str

get_rasters(raster_name: str, times: List[int | float]) → List[str]

Return local paths for the raster files.

Parameters:

times – A list of times

Returns:

A list of local paths

get_rotation_model()

Return a list of rotation files.

get_small_time()

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

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

Return a list of static polygons files.

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

Return a list of topologies files.

static is_model_dir(folder_path: str)

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

property model: Dict

The model metadata.

purge()

Remove the model folder and everything inside the folder.

purge_layer(layer_name)

Remove the layer folder of the given layer name.

purge_time_dependent_rasters(raster_name)

Remove the raster folder of the given raster name.

set_data_dir(new_dir)

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

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

Bases: object

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

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

Download all available models into the data_dir.

Parameters:

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

get_available_model_names()

Return the names of available models as a list.

static get_default_repo_url()

Return the URL to the configuration data of models.

static get_local_available_model_names(local_dir: str)

Return a list of model names in a local folder.

Parameters:

local_dir (str) – The local folder containing models.

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

Return a PlateModel object for a given plate model name.

Call get_available_model_names() to see a list of available plate model names.

Parameters:

• model_name – the plate model name of interest

• data_dir – The folder to save the plate model files. This data_dir can be changed with PlateModel.set_data_dir() later.

Returns:

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

property models: Dict

The metadata for all the models.

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

Bases: object

Manage the present-day rasters.

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

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

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

Parameters:

_name (str) – The raster name of interest.

Returns:

The local path to the downloaded raster file.

Return type:

str

is_wms(_name: str, check_raster_avail_flag=True)

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

Parameters:

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

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

list_present_day_rasters()

Return a list of available present-day rasters.

property rasters: Dict

The metadata of rasters.

set_data_dir(data_dir)

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

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.