Actions

Land cover change

class hydrobricks.actions.action_land_cover_change.ActionLandCoverChange[source]

Bases: Action

Class for managing land cover changes over time.

This action tracks changes in land cover areas (e.g., glacier retreat) across hydro units at specified dates.

classmethod create_action_for_glaciers(catchment: Catchment, times: list[str], full_glaciers: list[str] | Path, debris_glaciers: list[str] | Path | None = None, with_debris: bool = False, method: str = 'vector', interpolate_yearly: bool = True) → tuple[ActionLandCoverChange, list[pandas.DataFrame]][source]

Extract glacier cover changes from shapefiles and create an ActionLandCoverChange object.

This method processes glacier shapefiles at multiple time points, computes area changes for each hydro unit, and returns a configured action object.

Parameters:

catchment – The catchment to extract glacier cover changes for.
times – List of dates in format ‘YYYY-MM-DD’ corresponding to glacier extent data.
full_glaciers – Path(s) to shapefile(s) containing the extent of all glaciers (debris-covered and clean ice together). Can be a list of paths (one per time) or a single path with placeholders.
debris_glaciers – Path(s) to shapefile(s) containing the extent of debris-covered glaciers. Required if with_debris is True. Default: None
with_debris – If True, distinguishes between debris-covered and clean-ice areas. If False, treats all glacier area uniformly. Default: False
method –
Method to extract glacier cover changes:
- ’vector’: Vectorial extraction (more precise but slower)
- ’raster’: Raster extraction (faster but less precise)
Default: ‘vector’
interpolate_yearly – If True, interpolate changes to yearly time steps between provided dates. If False, use only the provided time points. Default: True

Returns:

A tuple containing:

ActionLandCoverChange object configured with extracted cover areas
List of DataFrames with cover areas. If with_debris is True: [glacier_ice, glacier_debris, ground]. If False: [glacier, ground].

Return type:

tuple[ActionLandCoverChange, list[pd.DataFrame]]

Raises:

ImportError – If geopandas is not installed.
ValueError – If catchment.map_unit_ids is None or if data is inconsistent.
FileNotFoundError – If shapefile paths do not exist.

Examples

>>> action, dataframes = ActionLandCoverChange.create_action_for_glaciers(
...     catchment=my_catchment,
...     times=['2020-08-01', '2030-08-01', '2040-08-01'],
...     full_glaciers='glacier_{year}.shp',
...     method='vector',
...     interpolate_yearly=True
... )

get_change_count() → int[source]

Get the number of changes registered.

Returns:: Total number of land cover changes across all times and hydro units.
Return type:: int

get_land_cover_count() → int[source]

Get the number of land covers registered.

Returns:: Total number of distinct land cover types with registered changes.
Return type:: int

load_from_csv(path: str | Path, hydro_units: HydroUnits, land_cover: str, area_unit: str, match_with: str = 'elevation') → None[source]

Read land cover changes from a CSV file.

The file should contain changes for a single land cover. Multiple files can be loaded consecutively. The first column must contain information to identify the hydro unit ID, such as the ID or elevation. Subsequent columns contain the changes at different dates. The first line must contain dates in YYYY-MM-DD format.

Parameters:

path – Path to the CSV file containing land cover change data.
hydro_units – The HydroUnits instance to match land cover changes against.
land_cover – Name of the land cover to change (e.g., ‘glacier’, ‘forest’).
area_unit – Unit for the area values: ‘m2’ or ‘km2’.
match_with – Information used to identify hydro units. Options: ‘elevation’, ‘id’. Default: ‘elevation’

Raises:

FileNotFoundError – If the CSV file does not exist.
ValueError – If the first column values don’t match hydro unit IDs or match criteria.
KeyError – If required columns are missing from the CSV file.

Examples

>>> action = ActionLandCoverChange()
>>> action.load_from_csv(
...     'glacier_changes.csv',
...     hydro_units,
...     land_cover='glacier',
...     area_unit='km2',
...     match_with='elevation'
... )

Example CSV file format (with areas in km²)

elevation 2020-08-01 2025-08-01 2030-08-01 2035-08-01 2040-08-01 4274 0.013 0.003 0 0 0 4310 0.019 0.009 0 0 0 4346 0.052 0.042 0.032 0.022 0.012 4382 0.072 0.062 0.052 0.042 0.032 4418 0.129 0.119 0.109 0.099 0.089 4454 0.252 0.242 0.232 0.222 0.212 4490 0.288 0.278 0.268 0.258 0.248 4526 0.341 0.331 0.321 0.311 0.301 4562 0.613 0.603 0.593 0.583 0.573

Glacier evolution — delta-h

class hydrobricks.actions.action_glacier_evolution_delta_h.ActionGlacierEvolutionDeltaH[source]

Bases: Action

Class for glacier evolution based on the delta-h method.

The glacier evolution is based on the delta-h method, which spatializes the glacier melt using a lookup table. The lookup table is computed by the routine preprocessing/glacier_evolution_delta_h.py.

get_hydro_unit_ids() → numpy.ndarray[source]

Get the lookup table hydro unit IDs.

Returns:: Array of hydro unit IDs (integers) for which glacier evolution is tracked.
Return type:: np.ndarray

get_land_cover_name() → str[source]

Get the land cover name (glacier name) to apply the changes.

Returns:: The land cover name (glacier name) to apply the changes.
Return type:: str

get_lookup_table_area() → numpy.ndarray[source]

Get the lookup table areas.

Returns:: 2D array of glacier areas (in m²) for each hydro unit and time increment. Shape: (n_increments, n_hydro_units)
Return type:: np.ndarray

get_lookup_table_volume() → numpy.ndarray[source]

Get the lookup table volumes.

Returns:: 2D array of glacier volumes (in m³) for each hydro unit and time increment. Shape: (n_increments, n_hydro_units)
Return type:: np.ndarray

get_month() → int[source]

Get the month to apply the changes.

Returns:: The month number (1-12) when changes are applied.
Return type:: int

load_from(obj: GlacierEvolutionDeltaH, land_cover: str = 'glacier', update_month: str | int = 'October') → None[source]

Get the glacier evolution lookup table from a GlacierEvolutionDeltaH instance.

Parameters:

obj – The GlacierEvolutionDeltaH instance containing lookup tables.
land_cover – The land cover name to apply the changes. Default: ‘glacier’
update_month – The month to apply the changes. Full English name or number (1-12). The update will be applied at the beginning of the month, every year. Default: ‘October’

Raises:

ConfigurationError – If the object is not a GlacierEvolutionDeltaH instance.

load_from_csv(dir_path: str | Path, land_cover: str = 'glacier', filename_area: str = 'glacier_evolution_lookup_table_area.csv', filename_volume: str = 'glacier_evolution_lookup_table_volume.csv', update_month: str | int = 'October') → None[source]

Read the glacier evolution lookup table from CSV files.

The files should contain the glacier area and volume evolution (in m²) for each hydro unit and increment (typically 100). The first row should contain the hydro unit IDs for the units containing glaciers. There should be no index column in the file; the first column should contain data.

Parameters:

dir_path – Path to the directory containing the lookup table files.
land_cover – The land cover name to apply the changes. Default: ‘glacier’
filename_area – Name of the lookup table file for the glacier area. Default: ‘glacier_evolution_lookup_table_area.csv’
filename_volume – Name of the lookup table file for the glacier volume. Default: ‘glacier_evolution_lookup_table_volume.csv’
update_month – The month to apply the changes. Full English name or number (1-12). The update will be applied at the beginning of the month, every year. Default: ‘October’

Raises:

FileNotFoundError – If the specified CSV files do not exist.
ValueError – If the CSV format is incorrect or data is inconsistent.
AssertionError – If hydro unit IDs or table shapes don’t match between area and volume files.

Examples

>>> action = ActionGlacierEvolutionDeltaH()
>>> action.load_from_csv('./data', land_cover='glacier', update_month='October')

Example of a file (with areas in m²)

2 3 4 5 6 2500.0 48125.0 34375.0 54375.0 65000.0 2125.2 44069.6 31544.8 51044.3 61726.6 1668.2 39600.1 28428.8 47478.1 58268.9 1024.3 34555.2 24914.0 43617.1 54591.8 0 28628.9 20776.8 39371.4 50646.9 0 21024.9 15298.5 34564.7 46342.8 0 7906.0 7475.2 28921.9 41597.3 0 0 1231.4 21121.3 36034.0 0 0 0 10242.1 28498.8

Glacier evolution — area scaling

class hydrobricks.actions.action_glacier_evolution_area_scaling.ActionGlacierEvolutionAreaScaling[source]

Bases: Action

Class for the glacier evolution based on a simple area-volume scaling.

The glacier evolution is based on a simple area-volume scaling, which computes the glacier area evolution based on the glacier volume evolution for each hydro unit. The lookup table is computed by the routine preprocessing/glacier_evolution_area_scaling.py

get_hydro_unit_ids() → numpy.ndarray[source]

Get the lookup table hydro unit IDs.

Returns:: Array of hydro unit IDs (integers) for which glacier evolution is tracked.
Return type:: np.ndarray

get_land_cover_name() → str[source]

Get the land cover name (glacier name) to apply the changes.

Returns:: The land cover name (glacier name) to apply the changes.
Return type:: str

get_lookup_table_area() → numpy.ndarray[source]

Get the lookup table areas.

Returns:: 2D array of glacier areas (in m²) for each hydro unit and time increment. Shape: (n_increments, n_hydro_units)
Return type:: np.ndarray

get_lookup_table_volume() → numpy.ndarray[source]

Get the lookup table volumes.

Returns:: 2D array of glacier volumes (in m³) for each hydro unit and time increment. Shape: (n_increments, n_hydro_units)
Return type:: np.ndarray

get_month() → int[source]

Get the month to apply the changes.

Returns:: The month number (1-12) when changes are applied.
Return type:: int

load_from(obj: GlacierEvolutionAreaScaling, land_cover: str = 'glacier', update_month: str | int = 'October') → None[source]

Get the evolution lookup table from a GlacierEvolutionAreaScaling instance.

Parameters:

obj – The GlacierEvolutionAreaScaling instance containing lookup tables.
land_cover – The land cover name to apply the changes. Default: ‘glacier’
update_month – The month to apply the changes. Full English name or number (1-12). The update will be applied at the beginning of the month, every year. Default: ‘October’

Raises:

ConfigurationError – If the object is not a GlacierEvolutionAreaScaling instance.

load_from_csv(dir_path: str | Path, land_cover: str = 'glacier', filename_area: str = 'glacier_evolution_lookup_table_area.csv', filename_volume: str = 'glacier_evolution_lookup_table_volume.csv', update_month: str | int = 'October') → None[source]

Read the glacier evolution lookup table from CSV files.

The files should contain the glacier area and volume evolution (in m²) for each hydro unit and increment (typically 100). The first row should contain the hydro unit IDs for the units containing glaciers. There should be no index column in the file; the first column should contain data.

Parameters:

dir_path – Path to the directory containing the lookup table files.
land_cover – The land cover name to apply the changes. Default: ‘glacier’
filename_area – Name of the lookup table file for the glacier area. Default: ‘glacier_evolution_lookup_table_area.csv’
filename_volume – Name of the lookup table file for the glacier volume. Default: ‘glacier_evolution_lookup_table_volume.csv’
update_month – The month to apply the changes. Full English name or number (1-12). The update will be applied at the beginning of the month, every year. Default: ‘October’

Raises:

FileNotFoundError – If the specified CSV files do not exist.
ValueError – If the CSV format is incorrect or data is inconsistent.
AssertionError – If hydro unit IDs or table shapes don’t match between area and volume files.

Examples

>>> action = ActionGlacierEvolutionAreaScaling()
>>> action.load_from_csv('./data', land_cover='glacier', update_month='October')

Example of a file (with areas in m²)

2 3 4 5 6 2500.0 48125.0 34375.0 54375.0 65000.0 2125.2 44069.6 31544.8 51044.3 61726.6 1668.2 39600.1 28428.8 47478.1 58268.9 1024.3 34555.2 24914.0 43617.1 54591.8 0 28628.9 20776.8 39371.4 50646.9 0 21024.9 15298.5 34564.7 46342.8 0 7906.0 7475.2 28921.9 41597.3 0 0 1231.4 21121.3 36034.0 0 0 0 10242.1 28498.8

Snow-to-ice transformation

class hydrobricks.actions.action_glacier_snow_to_ice_transformation.ActionGlacierSnowToIceTransformation(update_month: str | int = 'September', update_day: int = 30, land_cover: str = 'glacier')[source]

Bases: Action

Class for the glacier snow to ice transformation action.

This action transforms all remaining snow on glaciers into ice at a given date, typically at the end of the accumulation season.

get_day() → int[source]

Get the day of the month to apply the changes.

Returns:: The day of the month (1-31) when changes are applied.
Return type:: int

get_land_cover_name() → str[source]

Get the land cover name (glacier name) to apply the changes.

Returns:: The land cover name (glacier name) where changes are applied.
Return type:: str

get_month() → int[source]

Get the month to apply the changes.

Returns:: The month number (1-12) when changes are applied.
Return type:: int