pyreclaim 0.1.0__py3-none-any.whl

reclaim/static_features/reservoir_static.py

@@ -0,0 +1,97 @@
+import pandas as pd
+from shapely.geometry import Point, Polygon
+
+# Import utils
+from reclaim.static_features.utils.flow_length import find_actual_flow_path
+from reclaim.static_features.utils.area_perimeter import calculate_length_area_meters
+from reclaim.static_features.utils.aec_shape import concavity_index, mean_curvature, mean_slope
+
+
+def reservoir_based_static_features(
+    obc: float = None,
+    hgt: float = None,
+    mrb: str = None,
+    lat: float = None,
+    lon: float = None,
+    reservoir_polygon: Polygon = None,
+    inlet_point: Point = None,
+    resolution: float = None,
+    aec_df: pd.DataFrame = None
+) -> pd.DataFrame:
+    """
+    Compute reservoir-based features for RECLAIM input dataset.
+    
+    Parameters
+    ----------
+    obc : float, optional
+        Original Built Capacity (MCM), original design capacity of the reservoir.
+    hgt : float, optional
+        Dam height (meters).
+    mrb : str, optional
+        Major river basin name.
+    lat : float, optional
+        Latitude of dam location (degrees).
+    lon : float, optional
+        Longitude of dam location (degrees).
+    reservoir_polygon : shapely.geometry.Polygon, optional
+        Reservoir polygon geometry used to compute area and perimeter.
+    dam_point : shapely.geometry.Point, optional
+        Location of the dam.
+    inlet_point : shapely.geometry.Point, optional
+        Reservoir inlet location (if not provided, estimated internally).
+    resolution : float, optional
+        Spatial resolution used in flow length calculations.
+    aec_df : pd.DataFrame, optional
+        Area-Elevation Curve dataframe with columns ['area', 'elevation'].
+    
+    Returns
+    -------
+    pd.DataFrame
+        A single-row DataFrame with the following columns:
+        - OBC: Original Built Capacity (MCM)
+        - HGT: Dam Height (m)
+        - MRB: Major River Basin
+        - LAT: Latitude (deg)
+        - LON: Longitude (deg)
+        - RA: Reservoir Area (sq km)
+        - RP: Reservoir Perimeter (km)
+        - FL: Flow Length (km)
+        - AECS: AEC Mean Slope (km2/m)
+        - AECC: AEC Mean Curvature (km2/m2)
+        - AECI: AEC Concavity Index (DL)
+    """
+
+    features = {
+        "OBC": obc,
+        "HGT": hgt,
+        "MRB": mrb,
+        "LAT": lat,
+        "LON": lon,
+        "RA": None,
+        "RP": None,
+        "FL": None,
+        "AECS": None,
+        "AECC": None,
+        "AECI": None,
+    }
+
+    # Area and Perimeter
+    if reservoir_polygon is not None:
+        features["RP"], features["RA"] = calculate_length_area_meters(reservoir_polygon, area=True)
+        features["RA"] = features["RA"] / 1e6  # m2 → km2
+        features["RP"] = features["RP"] / 1e3  # m → km
+
+    # Flow Length
+    dam_point = Point(lon, lat)
+    if dam_point is not None and reservoir_polygon is not None:
+        _, _, features["FL"], _ = (
+            find_actual_flow_path(dam_point, reservoir_polygon, inlet_point, resolution) / 1e3
+        )  # m → km
+
+    # AEC metrics
+    if aec_df is not None:
+        features["AECS"] = mean_slope(aec_df)
+        features["AECC"] = mean_curvature(aec_df)
+        features["AECI"] = concavity_index(aec_df)
+
+    return pd.DataFrame([features])

reclaim/static_features/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility functions to generate static features for RECLAIM input dataset :no-index:"""

reclaim/static_features/utils/aec_shape.py

@@ -0,0 +1,101 @@
+import numpy as np
+import pandas as pd
+
+def mean_slope(df: pd.DataFrame) -> float:
+    """
+    Computes the mean slope (dA/dz) of reservoir bathymetry
+    from area–elevation data.
+    """
+    if not {'elevation', 'area'}.issubset(df.columns):
+        raise ValueError("DataFrame must have columns: 'elevation', 'area'")
+    if df.empty:
+        return float('nan')
+
+    # Sort and drop duplicate elevations (keep mean area if duplicates exist)
+    df = df.groupby("elevation", as_index=False)["area"].mean()
+    df = df.sort_values("elevation").reset_index(drop=True)
+
+    # Compute slope (Δarea/Δelevation)
+    dz = np.diff(df['elevation'])
+    da = np.diff(df['area'])
+
+    # Avoid division by zero
+    with np.errstate(divide='ignore', invalid='ignore'):
+        slopes = np.where(dz != 0, da / dz, np.nan)
+
+    return float(np.nanmean(slopes))
+
+
+def mean_curvature(df: pd.DataFrame) -> float:
+    """
+    Computes the mean curvature (d²A/dz²) of reservoir bathymetry
+    from area–elevation data.
+    """
+    if not {'elevation', 'area'}.issubset(df.columns):
+        raise ValueError("DataFrame must have columns: 'elevation', 'area'")
+    if df.empty:
+        return float('nan')
+
+    # Sort and drop duplicate elevations (keep mean area if duplicates exist)
+    df = df.groupby("elevation", as_index=False)["area"].mean()
+    df = df.sort_values("elevation").reset_index(drop=True)
+
+    dz = np.diff(df['elevation'])
+    da = np.diff(df['area'])
+
+    # First derivative
+    with np.errstate(divide='ignore', invalid='ignore'):
+        slopes = np.where(dz != 0, da / dz, np.nan)
+
+    # Second derivative (curvature)
+    dz2 = np.diff(df['elevation'][:-1])
+    dslopes = np.diff(slopes)
+    with np.errstate(divide='ignore', invalid='ignore'):
+        curvature = np.where(dz2 != 0, dslopes / dz2, np.nan)
+
+    return float(np.nanmean(curvature))
+
+def concavity_index(df: pd.DataFrame) -> float:
+    """
+    Computes the concavity index from a reservoir's area-elevation curve.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Must contain columns 'area' (km²) and 'elevation' (m).
+
+    Returns
+    -------
+    float
+        Concavity index (ratio of actual curve to straight line). 
+        Returns np.nan if invalid.
+    """
+    if not {'area', 'elevation'}.issubset(df.columns):
+        raise ValueError("DataFrame must have columns: 'area' and 'elevation'")
+    if df.empty:
+        return np.nan
+
+    # Convert to numpy and filter invalid values
+    area = df['area'].to_numpy(dtype=float)
+    elevation = df['elevation'].to_numpy(dtype=float)
+    
+    mask = (~np.isnan(area)) & (~np.isnan(elevation)) & (~np.isinf(area)) & (~np.isinf(elevation))
+    area = area[mask]
+    elevation = elevation[mask]
+
+    if len(area) < 2:
+        return np.nan
+
+    # Normalize to 0–1
+    area_norm = (area - area.min()) / (area.max() - area.min())
+    elev_norm = (elevation - elevation.min()) / (elevation.max() - elevation.min())
+
+    # Straight line between first and last point
+    line = np.linspace(0, 1, len(area_norm))
+
+    # Area under actual curve vs line
+    auc_curve = np.trapz(elev_norm, area_norm)
+    auc_line = np.trapz(line, area_norm)
+
+    concavity = auc_curve / auc_line if auc_line > 0 else np.nan
+    return concavity

reclaim/static_features/utils/area_perimeter.py

@@ -0,0 +1,36 @@
+import numpy as np
+from shapely.ops import transform
+
+def calculate_length_area_meters(geometry, area= True):
+    """
+    Calculate the length and area of a geometry in meters and square meters using
+    approximate conversion factors based on the geometry's centroid latitude.
+
+    Parameters:
+    geometry (shapely.geometry): Geometry in WGS84 (EPSG:4326) to calculate length and area.
+
+    Returns:
+    tuple: (length in meters, area in square meters)
+    """
+    # Get centroid for latitude reference
+    centroid = geometry.centroid
+    reference_latitude = centroid.y  # latitude of the centroid
+
+    # Conversion factors
+    lat_factor = 111_000  # meters per degree latitude
+    lon_factor = 111_320 * np.cos(np.radians(reference_latitude))  # meters per degree longitude at given latitude
+
+    # Transform function to scale degrees to meters
+    def scale_degrees_to_meters(x, y):
+        return (x * lon_factor, y * lat_factor)
+
+    # Scale geometry from degrees to meters using the conversion factors
+    scaled_geometry = transform(scale_degrees_to_meters, geometry)
+    
+    # Calculate length and area in meters and square meters
+    length_meters = scaled_geometry.length
+    if area: 
+        area_square_meters = scaled_geometry.area
+        return length_meters, area_square_meters
+    else:
+        return length_meters[0]

reclaim/static_features/utils/catchment_agreggate.py

@@ -0,0 +1,147 @@
+import pandas as pd
+import numpy as np
+import xarray as xr
+import geopandas as gpd
+import regionmask
+from collections import Counter
+from shapely.geometry import Polygon
+
+
+def compute_catchment_aggregate(
+    netcdf_path,
+    catchment_geometry,
+    function_type="mean"  # Can be 'mean', 'mode', 'std', 'percent' or dict
+) -> pd.DataFrame:
+    """
+    Compute catchment-based features by aggregating raster variables in a NetCDF file
+    for a single catchment geometry.
+
+    Parameters
+    ----------
+    netcdf_path : str or Path
+        Path to the NetCDF file containing raster variables.
+
+    catchment_geometry : shapely.geometry.Polygon or GeoSeries
+        Catchment geometry (single polygon).
+
+    function_type : str or dict, default="mean"
+        Either a string ('mean', 'mode', 'std', 'percent') to apply to all variables,
+        or a dictionary specifying function(s) per variable. Example::
+
+            {
+                "precip": "mean",
+                "slope": ["mean", "std"],
+                "landcover": {"type": "percent"}
+            }
+
+    Returns
+    -------
+    pd.DataFrame
+        A single-row DataFrame with catchment-level features.
+    """
+
+    # Open dataset
+    ds = xr.open_dataset(netcdf_path, chunks={'x': 200, 'y': 200})
+    ds = ds.rio.write_crs("EPSG:4326")
+
+    # Rename coords if needed
+    if 'lon' in ds.dims and 'lat' in ds.dims:
+        ds = ds.rename({'lon': 'x', 'lat': 'y'})
+
+    variables = list(ds.data_vars)
+
+    # Build function dict
+    if isinstance(function_type, str):
+        apply_func = {var: function_type for var in variables}
+    elif isinstance(function_type, dict):
+        apply_func = function_type
+    else:
+        raise ValueError("function_type must be a string or a dictionary.")
+
+    # Order check
+    y_order = "descending" if ds.y[0] > ds.y[-1] else "ascending"
+    x_order = "descending" if ds.x[0] > ds.x[-1] else "ascending"
+
+    # Get catchment bounds
+    minx, miny, maxx, maxy = catchment_geometry.bounds
+    if y_order == "descending":
+        y_slice = slice(maxy, miny)
+    else:
+        y_slice = slice(miny, maxy)
+    if x_order == "descending":
+        x_slice = slice(maxx, minx)
+    else:
+        x_slice = slice(minx, maxx)
+
+    # Subset dataset
+    subset_ds = ds.sel(x=x_slice, y=y_slice)
+
+    # Create mask
+    catchment_gdf = gpd.GeoDataFrame({"geometry": [catchment_geometry]}, crs="EPSG:4326")
+    mask_from_geopandas = regionmask.mask_geopandas(catchment_gdf, subset_ds.x, subset_ds.y)
+    catchment_mask = mask_from_geopandas == 0
+
+    if mask_from_geopandas.notnull().sum().sum().item() == 0:
+        raise ValueError("Catchment mask is empty — geometry may not overlap the raster.")
+
+    results = {}
+
+    # Loop over variables
+    for var in apply_func.keys():
+        data = subset_ds[var]
+        masked = data.where(catchment_mask).compute()
+        arr = masked.where(~masked.isnull(), drop=True)
+
+        # Skip if empty
+        if arr.size == 0:
+            continue
+
+        func_list = apply_func[var]
+        if not isinstance(func_list, list):
+            func_list = [func_list]  # wrap into list
+
+        for func_info in func_list:
+            if isinstance(func_info, str):
+                func = func_info
+                threshold = None
+                threshold_direction = None
+            elif isinstance(func_info, dict):
+                func = func_info.get("type")
+                threshold = func_info.get("threshold", None)
+                threshold_direction = func_info.get("direction", "greater")
+            else:
+                raise ValueError(f"Invalid function format for variable {var}")
+
+            if func == "mean":
+                results[f"{var}_mean"] = float(arr.mean().item())
+
+            elif func == "mode":
+                vals = arr.values.flatten()
+                results[f"{var}_mode"] = Counter(vals).most_common(1)[0][0]
+
+            elif func == "std":
+                results[f"{var}_std"] = float(arr.std().item())
+
+            elif func == "percent":
+                vals = arr.values.flatten()
+                total = len(vals)
+                class_counts = Counter(vals)
+                for cls, count in class_counts.items():
+                    results[f"{var}_percent_{int(cls)}"] = (count / total) * 100
+
+            elif func == "threshold_percent":
+                if threshold is None:
+                    raise ValueError(f"Threshold not provided for variable '{var}'")
+                vals = arr.values.flatten()
+                valid = vals[~np.isnan(vals)]
+                if threshold_direction == "greater":
+                    percent = (valid > threshold).sum() / len(valid) * 100
+                    results[f"{var}_percent_above_{threshold}"] = percent
+                else:
+                    percent = (valid < threshold).sum() / len(valid) * 100
+                    results[f"{var}_percent_below_{threshold}"] = percent
+
+            else:
+                raise ValueError(f"Unknown function type '{func}' for variable '{var}'")
+
+    return pd.DataFrame([results])