core-lens 0.1.dev175__tar.gz → 0.1.dev178__tar.gz

{core_lens-0.1.dev175 → core_lens-0.1.dev178}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev175
+Version: 0.1.dev178
 Summary: Query, analyse, and visualise CoreStack's microwatershed and Earth science data through a clean, composable Python API.
 Project-URL: Homepage, https://github.com/ApoorvaKashyap/core-lens
 Project-URL: Issues, https://github.com/ApoorvaKashyap/core-lens/issues

{core_lens-0.1.dev175 → core_lens-0.1.dev178}/src/core_lens/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.dev175'
-__version_tuple__ = version_tuple = (0, 1, 'dev175')
+__version__ = version = '0.1.dev178'
+__version_tuple__ = version_tuple = (0, 1, 'dev178')
 
 __commit_id__ = commit_id = None

{core_lens-0.1.dev175 → core_lens-0.1.dev178}/src/core_lens/aoi.py

@@ -284,7 +284,8 @@ class AoI:
 
     **Registration** must happen before any ``AoI`` is constructed::
 
-        from core_lens import AoI, MWSEntity, TehsilEntity
+        from core_lens import AoI
+        from core_lens.entities import MWSEntity, TehsilEntity
 
         AoI.register(MWSEntity)
         AoI.register(TehsilEntity)

{core_lens-0.1.dev175 → core_lens-0.1.dev178}/src/core_lens/utils/spatial.py

@@ -607,3 +607,109 @@ def execute_spatial_join(
         on=primary_key_cols,
         how="left",
     )
+
+
+def point_in_entities(
+    latlon: dict[str, float],
+    entities: list[Any],
+) -> dict[str, Any | None]:
+    """Return the entity-id in which a lat/lon point falls, per entity.
+
+    For each entity, performs a two-phase lookup:
+
+    1. **Bbox pre-filter** — eliminates entities whose bounding box doesn't
+       contain the point using the in-memory ``_index`` (no I/O).
+    2. **Exact containment** — loads geometry only for bbox candidates and
+       runs a vectorised Shapely ``contains`` test.
+
+    The function is designed for repeated hot-path calls; it relies on
+    ``entity._index`` and ``entity.geometry_lazy`` which are both
+    process-level cached after first access.
+
+    Args:
+        latlon (dict[str, float]): Point coordinates with keys ``"lat"`` and
+            ``"lon"`` (or ``"lng"`` as an alias for longitude).
+        entities (list[BaseEntity]): List of entity instances to test against.
+            Each must expose ``_index``, ``key_cols``, ``schema_profile``,
+            ``_resolve``, and ``static_path``.
+
+    Returns:
+        dict[str, Any | None]: Mapping of ``entity_class_name → entity_id``
+        (the value of the first ``key_col``). ``None`` if the point doesn't
+        fall inside any geometry of that entity.
+
+    Raises:
+        KeyError: If neither ``"lon"`` nor ``"lng"`` key exists in ``latlon``.
+
+    Example::
+
+        result = point_in_entities(
+            {"lat": 28.6139, "lon": 77.2090},
+            [district_entity, block_entity],
+        )
+        # {"DistrictEntity": "DEL_001", "BlockEntity": None}
+
+    """
+    lat: float = latlon["lat"]
+    lon: float = latlon.get("lon", latlon.get("lng"))  # type: ignore[assignment]
+
+    # Shapely Point — created once, reused across all entities.
+    pt = shapely.Point(lon, lat)
+
+    result: dict[str, Any | None] = {}
+
+    for entity in entities:
+        entity_name = type(entity).__name__
+
+        # Phase 1: bbox pre-filter (pure in-memory, no I/O) ---------------
+        index_df = (
+            entity._index
+        )  # pl.DataFrame with (key_cols…, minx, miny, maxx, maxy)
+        candidates = index_df.filter(
+            (pl.col("minx") <= lon)
+            & (pl.col("maxx") >= lon)
+            & (pl.col("miny") <= lat)
+            & (pl.col("maxy") >= lat)
+        )
+
+        if candidates.is_empty():
+            result[entity_name] = None
+            continue
+
+        # Phase 2: exact containment (load only candidate geometries) ------
+        profile = entity.schema_profile
+        geom_col = profile.geometry_col
+        geom_type = profile.geometry_type
+        key_cols: list[str] = entity.key_cols
+        static_path: str = entity._resolve(entity.static_path)
+
+        geom_df = (
+            pl.scan_parquet(static_path)
+            .select(key_cols + [geom_col])
+            .join(candidates.select(key_cols).lazy(), on=key_cols, how="semi")
+            .collect()
+        )
+
+        if geom_df.is_empty():
+            result[entity_name] = None
+            continue
+
+        raw = geom_df[geom_col].to_numpy()
+        if geom_type == "wkb":
+            geoms = shapely.from_wkb(raw)
+        else:
+            geoms = shapely.from_wkt(raw)
+
+        # Vectorised contains — after bbox pre-filter candidates are O(1~10),
+        # so tree construction would cost more than the query itself.
+        mask = shapely.contains(geoms, pt)  # C-level, no Python loop
+        hit_indices = np.where(mask)[0]
+
+        if len(hit_indices) == 0:
+            result[entity_name] = None
+        else:
+            # Return first key_col value of the first match.
+            primary_key = key_cols[0]
+            result[entity_name] = geom_df[primary_key][int(hit_indices[0])]
+
+    return result

{core_lens-0.1.dev175 → core_lens-0.1.dev178}/tests/unit/test_spatial.py

@@ -239,3 +239,180 @@ def test_execute_spatial_join_no_match_and_agg(tmp_path: Any) -> None:
     assert res["other_val"][1] == 10.0  # Match
     assert res["other_val2"][1] == 10.0
     assert res["other_val3"][1] == 10.0
+
+
+def _make_pie_entity(tmp_path: Any, name: str, polygons: list[tuple[str, str]]) -> Any:
+    """Build a minimal entity stub for point_in_entities tests.
+
+    Args:
+        tmp_path: pytest tmp_path fixture.
+        name: Class name (used as entity key in result dict).
+        polygons: List of (id, wkt_polygon_string) tuples.
+
+    Returns:
+        Entity-like object with _index, key_cols, schema_profile, _resolve, static_path.
+
+    """
+    from core_lens.schema.profile import SchemaProfile
+
+    ids = [p[0] for p in polygons]
+    wkts = [p[1] for p in polygons]
+
+    p = tmp_path / f"{name}.parquet"
+    pl.DataFrame({"entity_id": ids, "geom": wkts}).write_parquet(p)
+
+    # Build bbox index manually from WKT bounds.
+    import shapely
+
+    geoms = shapely.from_wkt(wkts)
+    bnds = shapely.bounds(geoms) if len(geoms) else None
+    if bnds is not None and len(bnds):
+        index = pl.DataFrame(
+            {
+                "entity_id": ids,
+                "minx": bnds[:, 0].tolist(),
+                "miny": bnds[:, 1].tolist(),
+                "maxx": bnds[:, 2].tolist(),
+                "maxy": bnds[:, 3].tolist(),
+            }
+        )
+    else:
+        index = pl.DataFrame(
+            schema={
+                "entity_id": pl.Utf8,
+                "minx": pl.Float64,
+                "miny": pl.Float64,
+                "maxx": pl.Float64,
+                "maxy": pl.Float64,
+            }
+        )
+
+    profile = SchemaProfile(
+        key_cols=["entity_id"],
+        geometry_col="geom",
+        geometry_type="wkt",
+        annual_time_col=None,
+        sub_annual_time_col=None,
+        bbox_cols=None,
+    )
+
+    static_str = str(p)
+
+    class _Entity:
+        key_cols = ["entity_id"]
+        static_path = static_str
+        schema_profile = profile
+        _index = index
+
+        def _resolve(self, path: str) -> str:
+            return path
+
+    _Entity.__name__ = name
+    return _Entity()
+
+
+def test_point_in_entities_hit(tmp_path: Any) -> None:
+    """Point inside a polygon returns its id."""
+    from core_lens.utils.spatial import point_in_entities
+
+    entity = _make_pie_entity(
+        tmp_path,
+        "Zone",
+        [("Z1", "POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))")],
+    )
+    result = point_in_entities({"lat": 0.5, "lon": 0.5}, [entity])
+    assert result == {"Zone": "Z1"}
+
+
+def test_point_in_entities_miss(tmp_path: Any) -> None:
+    """Point outside all polygons returns None."""
+    from core_lens.utils.spatial import point_in_entities
+
+    entity = _make_pie_entity(
+        tmp_path,
+        "Zone",
+        [("Z1", "POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))")],
+    )
+    result = point_in_entities({"lat": 5.0, "lon": 5.0}, [entity])
+    assert result == {"Zone": None}
+
+
+def test_point_in_entities_multi_entity(tmp_path: Any) -> None:
+    """Each entity resolved independently; mixed hit/miss."""
+    from core_lens.utils.spatial import point_in_entities
+
+    entity_a = _make_pie_entity(
+        tmp_path,
+        "District",
+        [
+            ("D1", "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))"),
+            ("D2", "POLYGON ((10 0, 20 0, 20 10, 10 10, 10 0))"),
+        ],
+    )
+
+    entity_b = _make_pie_entity(
+        tmp_path,
+        "Block",
+        [("B1", "POLYGON ((0 0, 5 0, 5 5, 0 5, 0 0))")],
+    )
+
+    # Point at (3, 3) — inside D1 and B1.
+    result = point_in_entities({"lat": 3.0, "lon": 3.0}, [entity_a, entity_b])
+    assert result["District"] == "D1"
+    assert result["Block"] == "B1"
+
+    # Point at (15, 5) — inside D2, outside B1.
+    result2 = point_in_entities({"lat": 5.0, "lon": 15.0}, [entity_a, entity_b])
+    assert result2["District"] == "D2"
+    assert result2["Block"] is None
+
+
+def test_point_in_entities_lng_alias(tmp_path: Any) -> None:
+    """Accepts 'lng' as alias for longitude."""
+    from core_lens.utils.spatial import point_in_entities
+
+    entity = _make_pie_entity(
+        tmp_path,
+        "Zone",
+        [("Z1", "POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))")],
+    )
+    result = point_in_entities({"lat": 0.5, "lng": 0.5}, [entity])
+    assert result == {"Zone": "Z1"}
+
+
+def test_point_in_entities_empty_list(tmp_path: Any) -> None:
+    """Empty entity list returns empty dict."""
+    from core_lens.utils.spatial import point_in_entities
+
+    result = point_in_entities({"lat": 0.5, "lon": 0.5}, [])
+    assert result == {}
+
+
+def test_point_in_entities_on_boundary(tmp_path: Any) -> None:
+    """Point exactly on polygon boundary — Shapely treats as contained."""
+    from core_lens.utils.spatial import point_in_entities
+
+    entity = _make_pie_entity(
+        tmp_path,
+        "Zone",
+        [("Z1", "POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))")],
+    )
+    # Shapely `contains` is strict (boundary not contained) — boundary point
+    # may return None. Test documents this behaviour rather than asserting a
+    # specific id, so the test remains robust across Shapely versions.
+    result = point_in_entities({"lat": 0.0, "lon": 0.5}, [entity])
+    assert result["Zone"] in ("Z1", None)
+
+
+def test_point_in_entities_bbox_skips_exact_check(tmp_path: Any) -> None:
+    """Bbox pre-filter short-circuits: point outside all bboxes skips I/O."""
+    from core_lens.utils.spatial import point_in_entities
+
+    entity = _make_pie_entity(
+        tmp_path,
+        "Zone",
+        [("Z1", "POLYGON ((10 10, 20 10, 20 20, 10 20, 10 10))")],
+    )
+    # Point at (0, 0) is outside bbox [10,10,20,20], so candidates empty.
+    result = point_in_entities({"lat": 0.0, "lon": 0.0}, [entity])
+    assert result == {"Zone": None}

core_lens-0.1.dev178/usage.md

@@ -0,0 +1,182 @@
+# core-lens Usage Guide
+
+`core-lens` is a high-performance Python library designed for querying, filtering, and manipulating large-scale geospatial datasets using deferred execution with Polars.
+
+This guide covers the core concepts and primary workflows for using the library.
+
+## 0. Installation
+
+Install `core-lens` via `pip`. The library provides several optional dependency groups depending on your use case:
+
+```bash
+# Basic installation (Polars + core utilities)
+pip install "core-lens[core]"
+
+# Recommended for geospatial querying and exporting (adds DuckDB, GeoPandas, Shapely)
+pip install "core-lens[spatial]"
+
+# Full installation with visualization and statistical modeling (excludes GPU)
+pip install "core-lens[full]"
+
+# Full installation with Nvidia GPU acceleration via cuDF (Linux only)
+pip install "core-lens[full-gpu]" --extra-index-url=https://pypi.nvidia.com
+```
+
+Though it is recommended that you use [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+mkdir core-test && cd core-test
+uv init --bare
+uv add core-lens[full]
+```
+
+
+## 1. Initialization and Registration
+
+The primary entry point for querying data is the **Area of Interest (`AoI`)**. Before an `AoI` can be constructed, the geospatial entities (e.g., Microwatersheds, Tehsils, Villages) must be registered.
+
+```python
+from core_lens import AoI
+from core_lens.entities import MWSEntity, TehsilEntity
+
+# 1. Register available entities
+AoI.register(MWSEntity)
+AoI.register(TehsilEntity)
+
+# Path to the root directory containing your parquet files
+DATA_ROOT = "path/to/data"
+```
+
+## 2. Defining an Area of Interest (AoI)
+
+An `AoI` is scoped to a specific spatial boundary. You must initialize it using **exactly one** of three boundary modes: a bounding box, a Shapely geometry, or named entity filters.
+
+```python
+import shapely.geometry as sgeom
+
+# Mode A: Bounding Box (minx, miny, maxx, maxy)
+aoi = AoI(DATA_ROOT, bbox=(76.0, 31.0, 78.0, 33.0))
+
+# Mode B: Shapely Geometry
+polygon = sgeom.box(76.0, 31.0, 78.0, 33.0)
+aoi_geom = AoI(DATA_ROOT, geometry=polygon)
+
+# Mode C: Named Entity Attributes / IDs
+# Resolves the geometry of the matching entity (e.g., by district or specific ID)
+aoi_named = AoI(DATA_ROOT, tehsil="Pangi", district="Chamba")
+aoi_id = AoI(DATA_ROOT, mws_id="13_551")
+```
+
+## 3. Querying Entities (Lazy Views)
+
+Accessing a registered entity on the `AoI` object (e.g., `aoi.mws`) returns a lazy **`View`**. A View builds up a query plan without executing any I/O until you explicitly materialize it.
+
+### Filtering Views
+
+Views can be chained with different types of filters:
+
+```python
+# Base view: All MWS falling within the AoI
+mws_view = aoi.mws
+
+# 1. Attribute Filtering
+filtered_view = mws_view.where(state="Himachal Pradesh")
+
+# 2. Spatial Filtering (Narrowing down within the AoI)
+spatial_view = mws_view.spatial_filter(bbox=(76.5, 31.5, 77.5, 32.5))
+
+# 3. Temporal Filtering (Filters sub-annual/annual data)
+from core_lens.base.view import Season
+
+temporal_view = mws_view.between(
+    year=(2020, 2022),       # Inclusive year range
+    season=Season.KHARIF     # Filter to specific season
+)
+```
+
+### Cross-Entity Spatial Joins
+
+You can define a spatial join to enrich one entity with aggregated data from another intersecting entity. This is evaluated lazily. This is still experimental.
+
+```python
+# Join MWS with Tehsil entity to calculate the sum of tehsil areas per MWS
+joined_view = mws_view.spatial_join(
+    other=TehsilEntity(data_root=DATA_ROOT),
+    agg={"Shape_Area": "sum"}
+)
+```
+
+## 4. Materialization
+
+Once your query is fully constructed, you materialize the `View` into a concrete `Result`. You must specify the temporal grain (`static`, `annual`, or `sub_annual`) you wish to load.
+
+```python
+# Materialize the static dataset (one row per entity)
+result_static = filtered_view.static.materialise()
+
+# Materialize annual time-series data
+result_annual = filtered_view.annual.materialise()
+
+# Materialize highly granular sub-annual time-series data
+result_sub_annual = temporal_view.sub_annual.materialise()
+```
+
+## 5. Working with Results
+
+A `Result` object provides access to the materialized data. `core-lens` uses zero-copy Polars DataFrames by default for speed, but integrates with GeoPandas when spatial manipulation is required.
+
+```python
+# 1. Zero-copy access (Instantaneous)
+pl_df = result_static.df()          # Polars DataFrame
+pl_lazy = result_static.lazy()      # Polars LazyFrame
+
+# 2. Decode WKB geometries to Shapely (CPU intensive)
+gdf = result_static.gdf()           # GeoPandas GeoDataFrame
+
+# 3. Data Transformations (Returns a new Result)
+# Derive new columns using Polars expressions
+import polars as pl
+result_derived = result_annual.derive("yield_per_ha", pl.col("yield") / pl.col("area_in_ha"))
+
+# 4. Fast aggregations (Returns a new Result)
+# Aggregate by a key column using Polars expressions
+result_agg = result_derived.aggregate(
+    pl.col("yield_per_ha").mean().alias("avg_yield_per_ha"),
+    by="year"
+)
+```
+
+## 6. Exporting Data
+
+For interoperability, results can be exported to various standard formats. Avoid exporting large, country-wide datasets to GeoJSON due to significant file size bloat.
+
+```python
+from core_lens.export import formats as export
+
+# Export to GeoParquet (Fast, efficient spatial format)
+export.geoparquet(result_static, "output/mws.geoparquet")
+
+# Export to GeoJSON (Slower, text-based)
+export.geojson(result_static, "output/mws.geojson")
+
+# Export without geometries (Uses Polars directly)
+export.parquet(result_static, "output/mws.parquet")
+export.csv(result_static, "output/mws.csv")
+```
+
+## Advanced Configuration
+
+### Custom Seasons
+By default, `core-lens` uses Indian agricultural seasons. You can inject a custom `SeasonConfig` at AoI initialization if you need to map time series data to different date ranges:
+
+```python
+from core_lens.aoi import SeasonConfig
+
+custom_seasons = SeasonConfig(
+    kharif=("06-01", "10-15"),
+    rabi=("10-16", "02-28"),
+    zaid=("03-01", "05-31")
+)
+
+aoi = AoI(DATA_ROOT, bbox=(...), seasons=custom_seasons)
+```