API documentation

API documentation#

centum

Delineation#

A class for analyzing evapotranspiration (ET) data using xarray.

This class provides methods to compute ratios of actual evapotranspiration (ETa) to potential evapotranspiration (ETp), identify thresholds for decision-making based on changes in these ratios, and calculate rolling time means.

centum.delineation.ETa_name#

Name of the variable representing actual evapotranspiration in the dataset. Default is ‘ETa’.

Type:

str

centum.delineation.ETp_name#

Name of the variable representing potential evapotranspiration in the dataset. Default is ‘ETp’.

Type:

str

centum.delineation.threshold_local#

Threshold value for identifying significant changes in local ETa/ETp ratios. Default is -0.25.

Type:

float

centum.delineation.threshold_regional#

Threshold value for identifying significant changes in regional ETa/ETp ratios. Default is -0.25.

Type:

float

centum.delineation.stat#

Statistical operation to apply to ETa/ETp ratios. Options include ‘mean’, ‘sum’, etc. Default is ‘mean’.

Type:

str

class centum.delineation.ETAnalysis(ETa_name: str = 'ETa', ETp_name: str = 'ETp', threshold_local: float = -0.25, threshold_regional: float = -0.25)#
apply_rules_irrigation(decision_ds: Dataset) → Dataset#

Applies the rules for detecting irrigation events based on the change in local and regional ETa/ETp ratios.

Parameters:

decision_ds (xr.Dataset) – An xarray Dataset containing the necessary variables to apply the rules.

Returns:

The updated xarray Dataset with new conditions (‘condIrrigation1’, ‘condIrrigation2’, ‘condIrrigation’).

Return type:

xr.Dataset

apply_rules_rain(decision_ds: Dataset) → Dataset#

Applies the rules for detecting rain events based on the change in regional and local ETa/ETp ratios.

Parameters:

decision_ds (xr.Dataset) – An xarray Dataset containing the necessary variables to apply the rules.

Returns:

The updated xarray Dataset with new conditions (‘condRain1’, ‘condRain2’, ‘condRain’).

Return type:

xr.Dataset

apply_time_window_mean(ds_analysis: Dataset, variable: str, time_window: int) → Dataset#

Applies a rolling time-window mean to a specified variable.

Parameters:

  • ds_analysis (xr.Dataset) – The dataset containing the variable to process.

  • variable (str) – The name of the variable to which the rolling mean is applied.

  • time_window (int) – The rolling time window size.

Returns:

The dataset with the time-averaged variable added.

Return type:

xr.Dataset

classify_event(decision_ds: Dataset, irrigation_condition: str = 'condIrrigation', rain_condition: str = 'condRain') → DataArray#

Classifies events into irrigation, rain, or no event based on conditions.

Parameters:

  • decision_ds (xr.Dataset) – The dataset containing the event classification conditions.

  • irrigation_condition (str, optional) – The name of the variable indicating irrigation conditions. Default is “condIrrigation”.

  • rain_condition (str, optional) – The name of the variable indicating rain conditions. Default is “condRain”.

Returns:

An array representing event types: 1 = Irrigation event 2 = Rain event 0 = No event

Return type:

xr.DataArray

compute_bool_threshold_decision_local(ds_analysis: Dataset, checkp: str = 'ratio_ETap_local_time_avg') → Dataset#

Computes a boolean threshold decision for the local ETa/ETp ratio.

Parameters:

  • ds_analysis (xr.Dataset) – The dataset containing the local ETa/ETp ratio data.

  • checkp (str, optional) – The name of the variable in the dataset to check against the threshold. Default is ‘ratio_ETap_local_time_avg’.

Returns:

The updated dataset with a new variable threshold_local indicating where the specified variable exceeds the threshold.

Return type:

xr.Dataset

compute_bool_threshold_decision_regional(ds_analysis: Dataset, checkp: str = 'ratio_ETap_regional_spatial_avg_time_avg') → Dataset#

Computes a boolean threshold decision for the regional ETa/ETp ratio.

Parameters:

  • ds_analysis (xr.Dataset) – The dataset containing the regional ETa/ETp ratio data.

  • checkp (str, optional) – The name of the variable in the dataset to check against the threshold. Default is ‘ratio_ETap_regional_spatial_avg_time_avg’.

Returns:

The updated dataset with a new variable threshold_regional indicating where the specified variable exceeds the threshold.

Return type:

xr.Dataset

compute_ratio_ETap_local(ds_analysis: Dataset, ETa_name: str = 'ETa', ETp_name: str = 'ETp', time_window: int | None = None) → Dataset#

Computes the local ETa/ETp ratio and its temporal differences.

Parameters:

  • ds_analysis (xr.Dataset) – The dataset containing ETa and ETp data.

  • ETa_name (str, optional) – The variable name for ETa. Default is ‘ETa’.

  • ETp_name (str, optional) – The variable name for ETp. Default is ‘ETp’.

  • time_window (int, optional) – The rolling time window size for temporal averaging. Default is None.

Returns:

The dataset with added local ETa/ETp ratio and temporal differences.

Return type:

xr.Dataset

compute_ratio_ETap_regional(ds_analysis: Dataset, ETa_name: str = 'ETa', ETp_name: str = 'ETp', stat: str = 'mean', window_size_x: int = 10, time_window: int | None = None) → Dataset#

Computes the regional ETa/ETp ratio and its temporal differences.

Parameters:

  • ds_analysis (xr.Dataset) – The dataset containing ETa and ETp data.

  • ETa_name (str, optional) – The variable name for ETa. Default is ‘ETa’.

  • ETp_name (str, optional) – The variable name for ETp. Default is ‘ETp’.

  • stat (str, optional) – The statistic to compute for regional aggregation (e.g., ‘mean’). Default is ‘mean’.

  • window_size_x (int, optional) – The spatial window size in kilometers for regional averaging. Default is 10.

  • time_window (int, optional) – The rolling time window size for temporal averaging. Default is None.

Returns:

The dataset with added regional ETa/ETp ratio and temporal differences.

Return type:

xr.Dataset

compute_regional_ETap(ds_analysis: Dataset, window_size_x: int = 1000, window_size_y: int = 1000) → Dataset#

Computes the regional mean of ETa and ETp using a moving window.

Parameters:

  • ds_analysis (xr.Dataset) – The dataset containing ETa and ETp data in a projected CRS with units in meters.

  • window_size_x (int, optional) – The width of the moving window in meters. Default is 1000 (1 km).

  • window_size_y (int, optional) – The height of the moving window in meters. Default is 1000 (1 km).

Returns:

A dataset with spatially averaged ETa and ETp for each pixel.

Return type:

xr.Dataset

Irrigation district#

Handling irrigation districts using georeferenced shapefiles

class centum.irrigation_district.IrrigationDistrict(shapefile_path: str, crs: str | None = None)#

Class for handling irrigation districts using georeferenced shapefiles.

shapefile_path#

The path to the irrigation district shapefile.

Type:

str

crs#

The coordinate reference system (CRS) to convert the shapefile to, if needed.

Type:

str, optional

convert_to_rioxarray_withrasterize(gdf: GeoDataFrame, variable: str, resolution: float, bounds: tuple) → DataArray#

Converts a GeoDataFrame to a rioxarray DataArray, enabling spatial operations on it.

Parameters:

  • gdf (gpd.GeoDataFrame) – The GeoDataFrame representing the irrigation districts.

  • variable (str) – The name of the variable to associate with the irrigation districts.

  • resolution (float) – The spatial resolution of the output raster.

  • bounds (tuple) – The bounding box of the raster in the format (minx, miny, maxx, maxy).

Returns:

A rioxarray DataArray with the variable values overlaid on the irrigation districts’ geospatial extent.

Return type:

xr.DataArray

convert_to_xarray(gdf: GeoDataFrame, resolution: tuple = (-300, 300), categorical_enums: dict | None = None, crs: str | None = None, engine: str = 'geocube') → DataArray#

Convert a GeoDataFrame to a raster using the specified engine.

Parameters:

  • gdf (gpd.GeoDataFrame) – The GeoDataFrame representing the spatial data to rasterize.

  • resolution (tuple, optional) – The resolution of the output raster grid, default is (-300, 300).

  • categorical_enums (dict, optional) – Mapping for categorical variables, required when using the ‘geocube’ engine.

  • crs (str, optional) – The CRS for the output raster. If None, uses the CRS of the input GeoDataFrame.

  • engine (str, optional) – The engine to use for conversion, either ‘geocube’ or ‘rasterize’. Default is ‘geocube’.

Returns:

Rasterized data in the form of an xarray.DataArray.

Return type:

xr.DataArray

convert_to_xarray_withgeocube(gdf: GeoDataFrame, resolution: tuple = (-300, 300), categorical_enums: dict | None = None, crs: str | None = None) → DataArray#

Convert a GeoDataFrame to a raster using the ‘geocube’ engine.

Parameters:

  • gdf (gpd.GeoDataFrame) – The GeoDataFrame representing the spatial data to rasterize.

  • resolution (tuple, optional) – The resolution of the output raster grid, default is (-300, 300).

  • categorical_enums (dict) – Mapping for categorical variables.

  • crs (str, optional) – The CRS for the output raster. If None, uses the CRS of the input GeoDataFrame.

Returns:

Rasterized data in the form of an xarray.DataArray.

Return type:

xr.DataArray

get_irrigation_area(gdf: GeoDataFrame) → float#

Computes the total irrigation area (in square kilometers).

Parameters:

gdf (gpd.GeoDataFrame) – The GeoDataFrame representing the irrigation districts.

Returns:

The total area of the irrigation districts in square kilometers.

Return type:

float

load_shapefile() → GeoDataFrame#

Loads the irrigation district shapefile into a GeoDataFrame.

Returns:

A GeoDataFrame representing the irrigation districts.

Return type:

gpd.GeoDataFrame

Plotting#

Functions to plot

Contents