API Reference

PlateModelManager

The plate_model_manager.PlateModelManager class manages the plate reconstruction models. You can use this class to do the things listed below.

• Get a list of available model names.

• Get a plate_model_manager.PlateModel object for a specific model name.

• Download all models into a folder.

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.

__init__(model_manifest: str = '', timeout=(None, None))

Constructor. Create a PlateModelManager instance. You need Internet connection to create an instance of this class. If you don’t have Internet connection, use PlateModel class directly in readonly mode. Visit this page to see an example.

Parameters:

model_manifest – The URL to a models.json metadata file. Normally you don’t need to provide this parameter unless you would like to setup your own plate model server.

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.

PlateModel

The plate_model_manager.PlateModel class manages the files in a plate reconstruction model. You can use this class to do the things listed below.

• Get a list of available layers in a plate model.

• Download the rotation file(s).

• Download the layer file(s) for a specific layer.

• Download time-dependent raster files.

• Download all files in a plate model.

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.

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

Constructor. Create a PlateModel instance.

Parameters:

• model_name (str) – The model name of interest.

• model_cfg – The model configuration in JSON format. The configuration is either downloaded from the server or loaded from a local file .metadata.json. If you are confused by this parameter, use PlateModelManager.get_model() to get a PlateModel object instead.

• data_dir (str, default=".") – The folder path to save the model data.

• readonly (bool, default=False) – If this flag is set to True, The PlateModel object will use the files in the local folder and will not attempt to download/update the files from the server.

• timeout – Network connection timeout parameter.

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.

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.

PresentDayRasterManager

The plate_model_manager.PresentDayRasterManager class manages the present-day rasters. You can use this class to do the things listed below.

• Get a list of available present-day raster names.

• Download a specific present-day raster.

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

Bases: object

Manage the present-day rasters.

__init__(data_dir='present-day-rasters', raster_manifest=None)

Constructor. Create a PresentDayRasterManager instance.

Parameters:

• raster_manifest – The URL to a present_day_rasters.json metadata file. Normally you don’t need to provide this parameter unless you would like to setup your own present-day raster server.

• data_dir – The path to a folder to save the present-day raster files.

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.

set_data_dir(data_dir)

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

Auxiliary Function

Auxiliary functon for users’ convenience.

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.