API Reference#

This page exposes selected Python API docs generated from in-code docstrings.

Core Models#

class profsea.components.core.global_model.Global(components: Dict[str, Component], end_yr: int, nt: int = 100, num_members: int = 1000, tcv: float = 1.0, parallel: bool = True, output_percentiles: list | np.ndarray = None, palmer_method: bool = True, random_sample: bool = False)#

Bases: object

Global sea level rise component emulator.

Parameters:

  • components (Dict) – List of SLR components for projections

  • end_yr (int) – End year of the projections.

  • nt (int) – Number of realisations of the input timeseries

  • num_members (int) – Number of realisations of for each component. Must be a multiple of the number of glacier methods.

  • tcv (float) – Multiplier for the standard deviation in the input fields.

  • parallel (bool) – If True, project SLR components in parallel.

  • output_percentiles (list|np.ndarray) – If not None, calculate percentiles from a 1D list/array for each component

  • palmer_method (bool) – If True, allow integration to end in any year up to 2300, with the contributions to GMLSR from ice-sheet dynamics, Greenland SMB and land water storage held at the 2100 rate beyond 2100.

  • random_sample (bool) – If True, randomly sample a single ensemble member across all components

endofhistory#

First year of AR5 projections.

Type:

int

endofAR5#

Last year of AR5 projections.

Type:

int

nyr#

Length of projections.

Type:

int

run(scenario: str, T_change: numpy.ndarray, member_seed: int = 42) → Dict[str, numpy.ndarray]#

Run the emulator to project GMSLR components for a specific state. :param scenario: Name of the scenario. :type scenario: str :param T_change: Array of temperature change values. :type T_change: np.ndarray :param member_seed: Seed for numpy.random. :type member_seed: int

save_components(components: Dict[str, numpy.ndarray], output_dir: str, scenario_name: str) → None#

Save SLR components as nc files to a directory.

Parameters:

  • components (Dict[str, np.ndarray]) – Dictionary of component names and their corresponding arrays.

  • output_directory (str) – Directory to save components to.

  • scenario_name (str) – Name of the scenario you’ve run the emulator for.

Return type:

None

sum_components(components: Dict[str, numpy.ndarray]) → numpy.ndarray#

Sum the components to get total GMSLR.

class profsea.components.core.spatial_model.Spatial(components: Dict[str, Component], grid_config: dict = None, grid_interpolation: str = 'linear', end_year: int = 2301, baseline_yrs: tuple = (1995, 2014), output_percentiles: list | np.ndarray = [5, 17, 50, 83, 95])#

Bases: object

Spatial sea level rise component emulator.

__init__(components: Dict[str, Component], grid_config: dict = None, grid_interpolation: str = 'linear', end_year: int = 2301, baseline_yrs: tuple = (1995, 2014), output_percentiles: list | np.ndarray = [5, 17, 50, 83, 95]) → None#
Parameters:

  • components (dict) – Dictionary of spatial components to include in the model. Keys should be the component names and values should be instances of Component subclasses.

  • grid_config (dict, optional) – Dictionary defining the grid configuration with keys ‘start_lon’, ‘end_lon’, ‘step_lon ‘start_lat’, ‘end_lat’, ‘step_lat’. If None, defaults to a 1-degree global grid.

  • grid_interpolation (str, optional) – Interpolation method to use when interpolating patterns to the target grid. Default is ‘linear’.

  • end_year (int, optional) – The final year of the projections. Default is 2301.

  • baseline_yrs (tuple, optional) – Tuple defining the start and end years of the baseline period for calculating anomalies. Default is (1995, 2014).

  • output_percentiles (list or np.ndarray, optional) – List or array of percentiles to sample from the ensemble for output. If None, outputs all members. Default is [5, 17, 50, 83, 95].

run(member_seed: int = 42) → None#

Run the spatial model to generate regional sea level projections for each component.

Parameters:

member_seed (int, optional) – Seed for random number generation to ensure reproducibility of member sampling. Default is 42.

Returns:

Dictionary of spatial projections for each component, where keys are component names and values are Dask arrays of shape (n_members, n_years, n_lats, n_lons).

Return type:

Dict[str, da.Array]

save_components(components: Dict[str, xarray.DataArray], scenario_name: str, output_dir: str = '.', output_format: str = 'zarr') → None#

Stream all regional sea level projections to disk in a single file/store.

Parameters:

  • components (Dict[str, xr.DataArray]) – Dictionary of component names and their corresponding Xarray DataArrays.

  • output_format (str) – Format to save the output in. Must be either ‘netcdf’ or ‘zarr’.

  • output_dir (str) – Directory to save components to.

  • scenario_name (str) – Name of the scenario you’ve run the emulator for.

Return type:

None

sum_components(components: Dict[str, xarray.DataArray]) → xarray.DataArray#

Sum the spatial components to get total sea-level change.

Parameters:

components (Dict[str, xr.DataArray]) – Dictionary of spatial component DataArrays.

Returns:

DataArray of the summed spatial projections.

Return type:

xr.DataArray

profsea.components.core.spatial_model.fetch_zenodo_fingerprints(zenodo_url: str, data_dir: Path, expected_folder_name: str) → None#

Downloads and extracts the ProFSea fingerprint dataset from Zenodo if it doesn’t already exist locally.

Parameters:

  • zenodo_url (str) – The direct download URL for the fingerprint dataset on Zenodo.

  • data_dir (Path) – The base directory where the dataset should be stored.

  • expected_folder_name (str) – The name of the folder that should be created when the dataset is extracted. Used to check if the data already exists.

class profsea.components.core.state.ClimateState(scenario: str, T_ens: numpy.ndarray, T_int_ens: numpy.ndarray, T_int_med: numpy.ndarray, fraction: numpy.ndarray, palmer_method: bool, endofAR5: int, endofhistory: int, end_yr: int, nyr: int, nt: int, num_members: int)#

ClimateState context object to hold relevant state information for SLR projections.

class profsea.components.core.state.SpatialState(grid_lats: np.ndarray, grid_lons: np.ndarray, n_years: int, n_members: int, grid_interpolation: str, output_percentiles: list[int] | np.ndarray, baseline_yrs: tuple[int, int])#

SpatialState context object to hold relevant state information for spatial SLR projections.

profsea.components.core.time_projection.time_projection(state: ClimateState, startratemean: float, startratepm: float, final, rng: numpy.random.Generator, nfinal: int = 1, fraction: numpy.ndarray = None) → numpy.ndarray#

Project a quantity which is a quadratic function of time.

Parameters:

  • startratemean (float) – Rate of GMSLR at the start in mm yr-1.

  • startratepm (float) – Start rate error in mm yr-1.

  • final (list | np.ndarray) – Likely range in m for GMSLR at the end of AR5.

  • nfinal (int) – Number of years at the end over which final is a time-mean.

  • fraction (np.ndarray) – Random numbers in the range 0 to 1.

Returns:

Projection of the quantity.

Return type:

np.ndarray

Global Components#

class profsea.components.global_.antarctica.AntarcticaDynAR5(d_ant: float = 0.0025, cum_emissions_total: float = None)#

AR5 Antarctic ice-dynamics response to warming, as a function of cumulative emissions or scenario. Following the implementation as given by Jonathan Gregory’s ar5gmslr (JonathanGregory/ar5gmslr).

Requires cumulative emissions total to be specified for a given scenario, or will default to scenario-based regression, based on rcp scenarios.

project(state: ClimateState, rng: numpy.random.Generator) → numpy.ndarray#

Project Antarctic rapid ice-sheet dynamics contribution to GMSLR.

Parameters:

fraction (np.ndarray) – Random numbers for the dynamic contribution.

Returns:

Antarctic rapid ice-sheet dynamics contribution to GMSLR.

Return type:

np.ndarray

class profsea.components.global_.antarctica.AntarcticaISMIP6(ais_region: str)#

ISMIP6 2300 Antarctic ice-sheet emulator with two-timescale response.

This emulation of the ISMIP6 ice-sheet model ensemble aims to capture slow, fast and drift responses of the Antarctic ice sheet to GMST. The slow response is modelled as the impulse response to temperature forcing, convolved with two exponential decay kernels representing different ice-sheet response timescales, depending on the region being modelled. The fast response is modelled as a direct proportionality to the integrated temperature anomaly, while the drift term captures any linear time-dependent trends not explained by the temperature forcing.

Parameters provided are for the WAIS, EAIS and AIS Peninsula regions, since each has different response characteristics to warming.

__init__(ais_region: str)#
Parameters:

ais_region (str) – The Antarctic region to model. Must be one of “wais”, “eais”, or “peninsula”.

project(state: ClimateState, rng: numpy.random.Generator) → numpy.ndarray#

Projects AIS response using empirical additive bootstrapping aligned to the ClimateState ensemble size.

class profsea.components.global_.antarctica.AntarcticaSMBAR5#

AR5 Antarctic SMB contribution to GMSLR, as a function of global mean surface temperature change.

Following the implementation as given by Jonathan Gregory’s ar5gmslr (JonathanGregory/ar5gmslr).

project(state: ClimateState, rng: numpy.random.Generator) → numpy.ndarray#

Project Antarctic SMB contribution to GMSLR.

Parameters:

  • T_int_ens (np.ndarray) – Ensemble of time-integral temperature anomaly timeseries.

  • fraction (np.ndarray) – Random numbers for the SMB-dynamic feedback.

Returns:

antsmb – Antarctic SMB contribution to GMSLR.

Return type:

np.ndarray

class profsea.components.global_.greenland.GreenlandAR6#
project(state: ClimateState, rng: numpy.random.Generator) → numpy.ndarray#

Project Greenland ice-sheet contribution to GMSLR. This follows the IPCC AR6 methodology as closely as possible. Projections are relative to 1996-2014 baseline.

Returns:

Total GIS contribution to GMSLR.

Return type:

np.ndarray

class profsea.components.global_.greenland.GreenlandDynAR5#

AR5 Greenland ice-sheet dynamics contribution to GMSLR.

NOTE: This is not scenario independent. It will run with either rcp85/ssp585 related projections, or will default to a temperature independent projection based on AR5.

This is based on Jonathan Gregory’s AR5 implmentation, which can be found at JonathanGregory/ar5gmslr

project(state: ClimateState, rng: numpy.random.Generator) → numpy.ndarray#

Project Greenland rapid ice-sheet dynamics contribution to GMSLR.

Parameters:

  • state (ClimateState) – State object containing relevant information for the projection.

  • rng (np.random.Generator) – Random number generator.

Returns:

Greenland rapid ice-sheet dynamics contribution to GMSLR.

Return type:

np.ndarray

class profsea.components.global_.greenland.GreenlandSMBAR5#

AR5 Greenland SMB contribution to GMSLR.

project(state: ClimateState, rng: numpy.random.Generator) → numpy.ndarray#

Project Greenland SMB contribution to GMSLR.

Parameters:

  • state (ClimateState) – State object containing relevant information for the projection.

  • rng (np.random.Generator) – Random number generator.

Returns:

greensmb – Greenland SMB contribution to GMSLR.

Return type:

np.ndarray

profsea.components.global_.greenland.load_greenland_calibration()#

Loads the CSV once and keeps it in memory.

class profsea.components.global_.glacier.Glacier(glaciermip: int = 2)#
project(state: ClimateState, rng: numpy.random.Generator) → numpy.ndarray#

Project glacier contribution to GMSLR.

Returns:

glacier – Glacier contribution to GMSLR.

Return type:

np.ndarray

class profsea.components.global_.expansion.ThermalExpansion(OHC_change: numpy.ndarray, distribution_scaler: float = 1.0)#

Parameters and Attributes#

OHC_change: np.ndarray

Array of ocean heat content change values.

exp_efficiency: float

Sensitivity of thermosteric SLR to ocean heat content change.

project(state: ClimateState, rng: numpy.random.Generator) → numpy.ndarray#

Calculate and return the SLR projection for this component

class profsea.components.global_.landwater.LandwaterAR5#
project(state: ClimateState, rng: numpy.random.Generator) → numpy.ndarray#

Old projection function. Project land water storage contribution to GMSLR.

Returns:

Land water storage contribution to GMSLR.

Return type:

np.ndarray

class profsea.components.global_.landwater.LandwaterAR6#
project(state: ClimateState, rng: numpy.random.Generator) → numpy.ndarray#

Project land water storage contribution to GMSLR. This follows the IPCC AR6 methodology as closely as possible. Projections are relative to 1996-2014 baseline.

Returns:

Land water storage contribution to GMSLR.

Return type:

np.ndarray

profsea.components.global_.landwater.load_landwater_projection()#

Loads the NetCDF once and keeps the VALUES in memory.

Spatial Components#

class profsea.components.spatial.fingerprint.Fingerprint(global_projection: numpy.ndarray, fingerprint_component: str, fingerprint_paths: str | Path | list[str | Path] = None, scaling_factor: float = 1.0, sample_spatial: bool = False)#

Spatial fingerprint component that applies spatial patterns to global projections.

__init__(global_projection: numpy.ndarray, fingerprint_component: str, fingerprint_paths: str | Path | list[str | Path] = None, scaling_factor: float = 1.0, sample_spatial: bool = False) → None#
Parameters:

  • global_projection (np.ndarray) – A 2D array (members x years) of global projections to apply the fingerprints to.

  • fingerprint_paths (str, Path, or list of str/Path) – Path(s) to NetCDF files containing the spatial fingerprint patterns. Each file should contain a DataArray with dimensions (lat, lon).

  • scaling_factor (float, optional) – Optional multiplier to apply to the fingerprint patterns (e.g., to convert from m to mm). Default is 1.0 (no scaling).

  • sample_spatial (bool, optional) – If True, randomly sample a different fingerprint pattern for each member. If False, use the mean of all provided fingerprints for all members (storyline mode). Default is False.

property global_projection#

Spatial component must define a global_projection attribute or property

project(state: SpatialState, rng: numpy.random.Generator) → dask.array.Array#

Calculate the spatial projection by applying the fingerprints to the global projection.

Parameters:

  • state (SpatialState) – The state object containing the target grid information and number of members.

  • rng (np.random.Generator) – Random number generator for sampling fingerprints if sample_spatial is True.

Returns:

A 4D array of shape (members, years, lat, lon) containing the spatial projections for each member and year.

Return type:

da.Array

class profsea.components.spatial.sterodynamic.SterodynamicCMIP5#

Placeholder for a sterodynamic SLR component based on CMIP5 projections.

project(state: ClimateState, rng) → numpy.ndarray#

Calculate and return the SLR projection for this component

class profsea.components.spatial.sterodynamic.SterodynamicCMIP6(global_projection: numpy.ndarray, patterns_dir: str = None, sample_spatial: bool = False)#

Parameters and Attributes#

global_projection: np.ndarray

Array of global sea level rise projections to use as input for sterodynamic projection.

__init__(global_projection: numpy.ndarray, patterns_dir: str = None, sample_spatial: bool = False) → None#
Parameters:

  • global_projection (np.ndarray) – A 2D array (members x years) of global projections to apply the fingerprints to.

  • patterns_dir (str, optional) – Path to directory containing CMIP6 sterodynamic patterns.

  • sample_spatial (bool, optional) – If True, randomly sample a different fingerprint pattern for each member. If False, use the mean of all provided fingerprints for all members (storyline mode). Default is False.

property global_projection#

Spatial component must define a global_projection attribute or property

project(state: ClimateState, rng) → numpy.ndarray#

Project the sterodynamic component by applying the CMIP6 patterns to the global expansion projection.

Parameters:

  • state (ClimateState) – The state object containing the target grid information and number of members.

  • rng (np.random.Generator) – Random number generator for sampling spatial patterns if needed.

Returns:

A numpy array of shape (members, years, lat, lon) containing the sterodynamic component for each member and year.

Return type:

np.ndarray

class profsea.components.spatial.gia.GIA(gia_dir: str | Path = None, sample_spatial: bool = False)#

Handles Glacial Isostatic Adjustment. GIA accumulates linearly over time and has no global warming driver input. Supports loading single files, lists of files, or directories of files.

__init__(gia_dir: str | Path = None, sample_spatial: bool = False) → None#
Parameters:

  • gia_dir (str, Path, or list of str/Path) – Path to a directory containing GIA files.

  • sample_spatial (bool, optional) – Whether to sample spatial patterns probabilistically. Default is False.

property global_projection#

Spatial component must define a global_projection attribute or property

project(state: SpatialState, rng: numpy.random.Generator) → dask.array.Array#

Project the GIA component by multiplying the accumulation time vector with the spatial rates.

Parameters:

  • state (SpatialState) – The spatial state containing the target grid information.

  • rng (np.random.Generator) – Random number generator for sampling GIA models if sample_spatial is True.

Returns:

A 4D array of shape (members, years, lat, lon) containing the spatial projections for each member and year.

Return type:

da.Array