rle-python 0.2.0__py3-none-any.whl

rle/core/aoo_grid.py

@@ -0,0 +1,54 @@
+"""Generate AOO grid cells for local (non-Earth Engine) backends."""
+
+import geopandas as gpd
+import numpy as np
+from pyproj import Transformer
+from shapely.geometry import box
+
+
+# ESRI:54034 World Cylindrical Equal Area — the IUCN-approved equal-area
+# projection for RLE AOO grids. The Earth Engine backend (rle.gee.ee_rle.
+# get_aoo_grid_projection) builds the equivalent ee.Projection from WKT.
+AOO_CRS = "ESRI:54034"
+AOO_CELL_SIZE = 10_000  # 10 km in meters
+
+
+def generate_aoo_grid(bounds_4326: tuple[float, float, float, float]) -> gpd.GeoDataFrame:
+    """Generate a GeoDataFrame of AOO grid cells covering the given bounds.
+
+    Args:
+        bounds_4326: (minx, miny, maxx, maxy) in EPSG:4326.
+
+    Returns:
+        GeoDataFrame with grid cell polygons in EPSG:4326.
+    """
+    minx, miny, maxx, maxy = bounds_4326
+
+    # Transform bounds to equal-area projection
+    transformer = Transformer.from_crs("EPSG:4326", AOO_CRS, always_xy=True)
+    ea_minx, ea_miny = transformer.transform(minx, miny)
+    ea_maxx, ea_maxy = transformer.transform(maxx, maxy)
+
+    # Snap to grid origin (0, 0) so cells are globally consistent
+    ea_minx = np.floor(ea_minx / AOO_CELL_SIZE) * AOO_CELL_SIZE
+    ea_miny = np.floor(ea_miny / AOO_CELL_SIZE) * AOO_CELL_SIZE
+    ea_maxx = np.ceil(ea_maxx / AOO_CELL_SIZE) * AOO_CELL_SIZE
+    ea_maxy = np.ceil(ea_maxy / AOO_CELL_SIZE) * AOO_CELL_SIZE
+
+    xs = np.arange(ea_minx, ea_maxx, AOO_CELL_SIZE)
+    ys = np.arange(ea_miny, ea_maxy, AOO_CELL_SIZE)
+
+    grid_cols = []
+    grid_rows = []
+    cells = []
+    for x in xs:
+        for y in ys:
+            grid_cols.append(int(x / AOO_CELL_SIZE))
+            grid_rows.append(int(y / AOO_CELL_SIZE))
+            cells.append(box(x, y, x + AOO_CELL_SIZE, y + AOO_CELL_SIZE))
+
+    grid = gpd.GeoDataFrame(
+        {"grid_col": grid_cols, "grid_row": grid_rows, "geometry": cells},
+        crs=AOO_CRS,
+    )
+    return grid.to_crs("EPSG:4326")

rle/core/cli.py

@@ -0,0 +1,49 @@
+"""Command-line interface for rle-python core."""
+
+import typer
+from typing import Annotated
+
+from rle.core import __version__
+
+app = typer.Typer(
+    name="rle",
+    help="IUCN Red List of Ecosystems tools (core)",
+    add_completion=False,
+)
+
+
+@app.command()
+def backends():
+    """List installed data-access backends (core + any plugins)."""
+    from rle.core.registry import iter_backends
+
+    infos = iter_backends()
+    if not infos:
+        print("No backends registered.")
+        return
+    width = max(len(b.name) for b in infos)
+    for b in sorted(infos, key=lambda x: (x.capability, x.name)):
+        dist = f"  [{b.distribution}]" if b.distribution else ""
+        print(f"  {b.name:<{width}}  {b.capability}{dist}")
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: Annotated[
+        bool,
+        typer.Option("--version", "-v", help="Show version and exit"),
+    ] = False,
+):
+    """Main entry point for the rle CLI."""
+    if version:
+        print(f"rle-python version {__version__}")
+        raise typer.Exit()
+
+    if ctx.invoked_subcommand is None:
+        print("Hello from rle-python!")
+        print("\nUse --help to see available commands")
+
+
+if __name__ == "__main__":
+    app()

rle/core/ecosystem_codes.py

@@ -0,0 +1,108 @@
+"""Assign hierarchical ecosystem codes to a vector dataset.
+
+For each functional group code, the distinct ecosystem names are sorted
+alphabetically and assigned a counter starting at 1. The counter is
+appended to the functional group code to form the ecosystem code. For
+example, two ecosystems in functional group ``T1.1`` become ``T1.1.1``
+and ``T1.1.2``.
+"""
+
+import warnings
+
+import geopandas as gpd
+import pandas as pd
+
+# Shapefile DBF character fields are limited to 10 characters; longer
+# values are silently truncated by downstream tools that export to .shp,
+# which can collapse distinct ecosystems into the same reported code.
+SHAPEFILE_VALUE_LIMIT = 10
+
+
+def assign_ecosystem_codes(
+    gdf: gpd.GeoDataFrame,
+    *,
+    fg_code_col: str,
+    eco_name_col: str,
+    eco_code_col: str,
+) -> gpd.GeoDataFrame:
+    """Return a copy of ``gdf`` with a new column of hierarchical ecosystem codes.
+
+    Within each functional group, distinct ecosystem names are sorted
+    alphabetically before numbering, so the result is deterministic
+    regardless of input row order.
+
+    Args:
+        gdf: Input GeoDataFrame.
+        fg_code_col: Existing column holding the functional group code
+            (e.g. values like ``"T1.1"``).
+        eco_name_col: Existing column holding the ecosystem name.
+        eco_code_col: Name of the new column to create and populate.
+
+    Returns:
+        A copy of ``gdf`` with ``eco_code_col`` added. Rows whose
+        functional group code or ecosystem name is null receive a null
+        ecosystem code.
+
+    Raises:
+        ValueError: If ``fg_code_col`` or ``eco_name_col`` is missing
+            from ``gdf``, or if ``eco_code_col`` already exists.
+
+    Warns:
+        UserWarning: If any generated ecosystem code exceeds
+            :data:`SHAPEFILE_VALUE_LIMIT` characters. Such codes will be
+            silently truncated if later written to a shapefile field,
+            which can collapse distinct ecosystems when reporting
+            statistics per ecosystem.
+    """
+    # --- Validate columns ---
+    for col in (fg_code_col, eco_name_col):
+        if col not in gdf.columns:
+            raise ValueError(
+                f"column {col!r} not found in input. "
+                f"Available columns: {list(gdf.columns)}"
+            )
+    if eco_code_col in gdf.columns:
+        raise ValueError(
+            f"column {eco_code_col!r} already exists in input. "
+            f"Refusing to overwrite."
+        )
+
+    # --- Build (fg, eco_name) -> code mapping ---
+    # Distinct (fg, eco_name) pairs, skipping any with nulls, sorted so
+    # that within each functional group, ecosystem names are alphabetical.
+    pairs = (
+        gdf[[fg_code_col, eco_name_col]]
+        .dropna()
+        .drop_duplicates()
+        .sort_values([fg_code_col, eco_name_col])
+    )
+
+    code_map: dict[tuple, str] = {}
+    for fg, group in pairs.groupby(fg_code_col, sort=True):
+        for counter, eco_name in enumerate(group[eco_name_col].tolist(), start=1):
+            code_map[(fg, eco_name)] = f"{fg}.{counter}"
+
+    # --- Apply mapping to every row ---
+    def lookup(row):
+        fg = row[fg_code_col]
+        eco = row[eco_name_col]
+        if pd.isna(fg) or pd.isna(eco):
+            return None
+        return code_map.get((fg, eco))
+
+    result = gdf.copy()
+    result[eco_code_col] = result.apply(lookup, axis=1)
+
+    # --- Warn about values that exceed the shapefile character limit ---
+    long_codes = sorted(
+        {c for c in code_map.values() if len(c) > SHAPEFILE_VALUE_LIMIT}
+    )
+    if long_codes:
+        warnings.warn(
+            f"{len(long_codes)} ecosystem code(s) exceed "
+            f"{SHAPEFILE_VALUE_LIMIT} characters and will be truncated if "
+            f"later written to a shapefile field: {long_codes}",
+            stacklevel=2,
+        )
+
+    return result