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], start_yr: int, end_yr: int, baseline_start: int, baseline_end: int, initialise_from_observations: bool = True, 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, dtype: np.dtype | str = numpy.float32)#

Bases: object

Global sea level rise component emulator.

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

  • start_yr (int) – Start year of the projections. Must be later than 1980 and earlier than end_yr.

  • end_yr (int) – End year of the projections. Must be later than start_yr.

  • baseline_start (int) – First year of the period used to define the sea-level baseline. Must be 1980 or later and earlier than baseline_end.

  • baseline_end (int) – Last year of the period used to define the sea-level baseline. Must be later than baseline_start.

  • initialise_from_observations (bool, default=True) – If True, observations to initialise component projections. If False, components are projected without observational initialisation and are re-baselined after projection.

  • 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

Raises:

ValueError – if start_yr is later than end_yr; if baseline_start is later than baseline_end; if start_yr or baseline_start is earlier than 1980.

endofhistory#

First year of AR5 projections.

Type:

int

endofAR5#

Last year of AR5 projections.

Type:

int

n_years#

Length of projections.

Type:

int

observations#

Manages observational data used to initialise the sea-level components. Uses baseline_start and baseline_end as its default baseline

Type:

Observations

run(scenario: str, T_change: np.ndarray | xr.DataArray, member_seed: int = 42) → dict[str, np.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/DataArray of temperature change values. :type T_change: np.ndarray | xr.DataArray :param member_seed: Seed for numpy.random. :type member_seed: int

save_components(components: dict[str, xarray.DataArray], scenario_name: str, output_prefix: str = 'projection', output_dir: str = '.', output_format: str = 'zarr', output_dtype: str | None = None, description: str = 'Spatial sea level rise projections') → None#

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

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

  • output_prefix (str) – Prefix for the output file name (e.g., ‘projection’ or ‘global’).

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

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

  • output_dtype (str | None) – Data type to force the output to (e.g., ‘float32’). If None, the dtype is dynamically inferred from each individual component.

  • description (str) – Metadata description attached to the dataset attributes.

Return type:

None

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

Sum the components in-place to get total GMSLR.

Parameters:

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

Returns:

DataArray of the summed global projections.

Return type:

xr.DataArray

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], dtype: np.dtype = numpy.float32)#

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], dtype: np.dtype = numpy.float32) → 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].

  • dtype (np.dtype, optional) – Data type for the output arrays. Default is np.float32.

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 (num_members, n_years, n_lats, n_lons).

Return type:

Dict[str, da.Array]

save_components(components: dict[str, xarray.DataArray], scenario_name: str, output_prefix: str = 'projection', output_dir: str = '.', output_format: str = 'zarr', output_dtype: str | None = None, description: str = 'Spatial sea level rise projections') → None#

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

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

  • output_prefix (str) – Prefix for the output file name (e.g., ‘projection’ or ‘global’).

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

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

  • output_dtype (str | None) – Data type to force the output to (e.g., ‘float32’). If None, the dtype is dynamically inferred from each individual component.

  • description (str) – Metadata description attached to the dataset attributes.

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, start_yr: int, end_yr: int, baseline_start: int, baseline_end: int, n_years: int, nt: int, num_members: int, dtype: numpy.dtype = numpy.float32)#

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, nt: int, num_members: int, num_output_members: int, grid_interpolation: str, endofhistory: int, output_percentiles: list[int] | np.ndarray, baseline_yrs: tuple[int, int], dtype: np.dtype = numpy.float32)#

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(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, observations: Observations | None) → numpy.ndarray#

Project Antarctic rapid ice-sheet dynamics contribution to GMSLR.

Parameters:
  • state (ClimateState) – Climate state containing scenario, ensemble, and projection settings.

  • rng (np.random.Generator) – Random number generator used for uncertainty sampling.

  • observations (Observations or None) – Observational data used to initialise the projection. This component requires observational initialisation and raises an error if None.

Returns:

Antarctic rapid ice-sheet dynamics contribution to GMSLR.

Return type:

np.ndarray

class profsea.components.global_.antarctica.AntarcticaISMIP6(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__(region: str)#
Parameters:

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

project(state: ClimateState, rng: numpy.random.Generator, observations: Observations | None) → 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, observations: Observations | None) → numpy.ndarray#

Project Antarctic SMB contribution to GMSLR.

Parameters:
  • state (ClimateState) – Climate state containing scenario, ensemble, and projection settings.

  • rng (np.random.Generator) – Random number generator used for uncertainty sampling.

  • observations (Observations or None) – Observational data used to initialise the projection. This component requires observational initialisation and raises an error if None.

Returns:

antsmb – Antarctic SMB contribution to GMSLR.

Return type:

np.ndarray

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

Project Greenland ice-sheet contribution to GMSLR.

This follows the IPCC AR6 methodology as closely as possible, relative to the specified start date and baseline period. For years after 2100, the 2100 rate of sea-level change is persisted linearly.

Parameters:
  • state (ClimateState) – Climate state containing the projection start year and baseline period.

  • rng (np.random.Generator) – Random number generator used to sample calibrated model parameters and the Greenland trend contribution.

  • observations (Observations or None) – Observational data used to initialise the projection. This component requires observational initialisation and raises an error if None.

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, observations: Observations) → 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.

  • observations (Observations or None) – Observational data used to initialise the projection. This component requires observational initialisation and raises an error if None.

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, observations: Observations | None) → numpy.ndarray#

Project Greenland SMB contribution to GMSLR.

The projection is initialised from the observed IMBIE3 Greenland SMB contribution at the projection start year, relative to the specified baseline.

Parameters:
  • state (ClimateState) – Climate state containing the projection start year and baseline period.

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

  • observations (Observations or None) – Observational data used to initialise the projection. This component requires observational initialisation and raises an error if None..

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, observations: Observations) → numpy.ndarray#

Project glacier contribution to GMSLR.

The projection is initialised from the observed glacier contribution at the projection start year.

Parameters:
  • state (ClimateState) – Climate state containing the projection configuration.

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

  • observations (Observations) – Observational data used to initialise the projection.

Returns:

glacier – Glacier contribution to GMSLR.

Return type:

np.ndarray

class profsea.components.global_.expansion.ThermalExpansion(data_input: np.ndarray | xr.DataArray, distribution_scaler: float = 1.0, OHC_change: bool = True)#

Parameters and Attributes#

data_input: np.ndarray | xr.DataArray

Array of ocean heat content (or thermosteric sea level) change values.

distribution_scaler: float

Controls distribution of sensitivity of thermosteric SLR to ocean heat content change.

OHC_change: bool

If True, assumes input is ocean heat content change. If False, assumes input is thermosteric sea level change (e.g., zostoga) and skips OHC→SLR conversion.

project(state: ClimateState, rng: numpy.random.Generator, observations: Observations | None) → numpy.ndarray#

Calculate and return the SLR projection for this component

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

Project land water storage contribution to GMSLR.

The AR5 end-of-century very-likely range is reported for 2081-2100 relative to the 1986-2005 baseline (Table 13.5 AR5). The projected contribution is expressed relative to the baseline specified in the ClimateState.

Parameters:
  • state (ClimateState) – Climate state containing projection years, and baseline period,

  • rng (np.random.Generator) – Random number generator used for uncertainty sampling.

  • observations (Observations or None) – Observational data used to initialise the projection. This component requires observational initialisation and raises an error if None.

Returns:

Land water storage contribution to GMSLR.

Return type:

np.ndarray

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

Project land water storage contribution to GMSLR. This follows the IPCC AR6 methodology as closely as possible. The observed contribution, from Zheng et al., (2026), is added at the start_yr relative to the specified baseline.

Parameters:
  • state (ClimateState) – Climate state containing projection years and baseline period.

  • rng (np.random.Generator) – Random number generator used for uncertainty sampling.

  • observations (Observations or None) – Observational data used to initialise the projection. This component requires observational initialisation and raises an error if None.

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: xarray.DataArray, 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: xarray.DataArray, fingerprint_component: str, fingerprint_paths: str | Path | list[str | Path] = None, scaling_factor: float = 1.0, sample_spatial: bool = False) → None#
Parameters:
  • global_projection (xr.DataArray) – 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(*args, **kwargs)#

Placeholder for a sterodynamic SLR component based on CMIP5 patterns.

Not implemented yet: constructing it raises NotImplementedError so that it cannot silently contribute zeros to a projection. Use SterodynamicCMIP6 instead.

property global_projection#

Spatial component must define a global_projection attribute or property

project(state, rng) → dask.array.Array#

Calculate and return the SLR projection for this component

class profsea.components.spatial.sterodynamic.SterodynamicCMIP6(global_projection: xarray.DataArray, patterns_dir: str = None, cmip_era: str = 'CMIP6', 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: xarray.DataArray, patterns_dir: str = None, cmip_era: str = 'CMIP6', sample_spatial: bool = False) → None#
Parameters:
  • global_projection (xr.DataArray) – A 2D array (members x years) of global projections to apply the fingerprints to.

  • patterns_dir (str, optional) – Path to directory containing {cmip_era} sterodynamic patterns.

  • cmip_era (str, optional) – The CMIP era to use for the sterodynamic patterns. Default is “CMIP6”, other option is “CMIP5”.

  • 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_paths: 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_paths: str | Path = None, sample_spatial: bool = False) → None#
gia_paths: str, Path, list of str/Path, or None

Path(s) to a directory containing GIA files or direct paths to specific GIA NetCDF files. Defaults to the main GIA_DIR if None.

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

class profsea.components.core.local_model.Local(components: dict[str, SpatialComponent], locations: dict[str, tuple[float, float]], interpolation_method: str = 'nearest', end_year: int = 2301, baseline_yrs: tuple = (1995, 2014), output_percentiles: list | np.ndarray = [5, 17, 50, 83, 95])#

Site-specific (Local) sea level rise component emulator.

__init__(components: dict[str, SpatialComponent], locations: dict[str, tuple[float, float]], interpolation_method: str = 'nearest', 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.

  • locations (dict) – Dictionary mapping site names to (latitude, longitude) tuples. Example: {“Aberdeen”: (57.144, -2.080)}

  • interpolation_method (str, optional) – Interpolation method to use when interpolating patterns to the target sites. Default is ‘nearest’.

  • 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. Default is (1995, 2014).

  • output_percentiles (list or np.ndarray, optional) – List or array of percentiles to sample from the ensemble for output.

run(member_seed: int = 42) → dict[str, xarray.DataArray]#

Run the local model to generate site-specific projections.

Parameters:

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

Returns:

Dictionary of local projections for each component, where keys are component names and values are xarray DataArrays of shape (num_members, n_years, n_sites).

Return type:

dict

save_components(components: dict[str, xarray.DataArray], scenario_name: str, output_prefix: str = 'projection', output_dir: str = '.', output_format: str = 'zarr', output_dtype: str | None = None, description: str = 'Spatial sea level rise projections') → None#

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

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

  • output_prefix (str) – Prefix for the output file name (e.g., ‘projection’ or ‘global’).

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

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

  • output_dtype (str | None) – Data type to force the output to (e.g., ‘float32’). If None, the dtype is dynamically inferred from each individual component.

  • description (str) – Metadata description attached to the dataset attributes.

Return type:

None

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

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

Parameters:

components (dict) – Dictionary of xarray DataArrays representing individual components.

Returns:

A single xarray DataArray representing the total sea-level projections, with appropriate attributes.

Return type:

xr.DataArray