core-lens 0.1.dev101__tar.gz → 0.1.dev105__tar.gz

{core_lens-0.1.dev101 → core_lens-0.1.dev105}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev101
+Version: 0.1.dev105
 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.dev101 → core_lens-0.1.dev105}/docs/source/intro.md

@@ -12,4 +12,4 @@ CoreLens provides a unified interface over microwatersheds, administrative bound
 - **Pluggable Entities**: Built-in support for standard units (MWS, Tehsil) with a simple plugin architecture for adding new domain entities.
 - **Temporal & Seasonal Awareness**: Native support for agronomic seasons (Kharif, Rabi, Zaid) and time-range filtering.
 - **Spatial Statistics & Analysis**: Built-in methods for anomaly detection, spatial similarity, temporal correlation, and hypothesis testing.
-- **Interactive Visualisation**: Generate interactive maps using Lonboard and timeseries/scatter plots using Plotly directly from results.
+- **Interactive Visualisation**: Generate interactive maps using Lonboard and timeseries/scatter plots using Bokeh directly from results.

{core_lens-0.1.dev101 → core_lens-0.1.dev105}/docs/source/plots.md

@@ -1,8 +1,8 @@
 # Visualisation and Plots
 
-The `result.plot` namespace provides integrated plotting capabilities. Spatial plots use **Lonboard** for high-performance interactive maps, while charts and timeseries use **Plotly**.
+The `result.plot` namespace provides integrated plotting capabilities. Spatial plots use **Lonboard** for high-performance interactive maps, while charts and timeseries use **Bokeh**.
 
-Plot methods return plot objects (like a Plotly Figure or Lonboard Map) which can be displayed in Jupyter notebooks or exported.
+Plot methods return plot objects (like a Bokeh Figure or Lonboard Map) which can be displayed using `bokeh.io.show` or exported via `bokeh.io.save`.
 
 ## Choropleth Maps
 
@@ -18,9 +18,11 @@ map_view = res.plot.choropleth(column="ndvi")
 Plot timeseries data. You can aggregate the data or plot the top N entities individually.
 
 ```python
+from bokeh.io import show
+
 # Aggregate timeseries
 fig_agg = res.plot.timeseries(x="year", y="ndvi", aggregate=True)
-fig_agg.show()
+show(fig_agg)
 
 # Timeseries for top entities
 fig_top = res.plot.timeseries(x="year", y=["ndvi", "rainfall"], top_n=5)

{core_lens-0.1.dev101 → core_lens-0.1.dev105}/docs/source/queries.md

@@ -31,7 +31,7 @@ derived_res = res_annual.derive(
     pl.when(pl.col("rainfall") < 500).then(1).otherwise(0)
 )
 
-# 2. Aggregate (temporal grouping requires fortnightly resolution)
+# 2. Aggregate (temporal grouping like "month" requires fortnightly, but "year" works on annual too)
 res_fortnightly = aoi.mws.fortnightly
 monthly_avg = res_fortnightly.aggregate(pl.mean("ndvi"), by="month")
 seasonal_avg = res_fortnightly.aggregate(pl.mean("ndvi"), by="season_year")

{core_lens-0.1.dev101 → core_lens-0.1.dev105}/docs/source/quickstart.md

@@ -34,6 +34,12 @@ aoi = AoI(
     tehsil="Pangi"
 )
 
+# Or scope it directly to a specific list of entity IDs
+aoi_specific = AoI(
+    data_root="/path/to/data",
+    mws_id=["13_001", "13_002"]
+)
+
 # You can now access entities scoped to this AoI:
 mws_view = aoi.mws
 

core_lens-0.1.dev105/plot_wb.py

@@ -0,0 +1,29 @@
+import polars as pl
+from core_lens import AoI
+from core_lens.base.entity import BaseEntity
+
+from core_lens.entities.waterbody import WaterbodyEntity
+
+def main():
+    # Register the entity
+    AoI.register(WaterbodyEntity)
+    
+    # Init AoI with a bounding box for India (or you can adjust bbox)
+    DATA_ROOT = "data/"
+    aoi = AoI(DATA_ROOT, bbox=(68.0, 6.0, 98.0, 38.0))
+    
+    # Materialise the static waterbodies data
+    print("Loading waterbodies...")
+    wb_result = aoi.waterbody.static
+    
+    # Plot using the area column for choropleth colors
+    print("Plotting waterbodies...")
+    choropleth_map = wb_result.plot.choropleth("area_ha")
+    
+    # Save the map to HTML
+    output_file = "wb_map.html"
+    choropleth_map.to_html(output_file)
+    print(f"Saved waterbodies map to {output_file}")
+
+if __name__ == "__main__":
+    main()

{core_lens-0.1.dev101 → core_lens-0.1.dev105}/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.dev101'
-__version_tuple__ = version_tuple = (0, 1, 'dev101')
+__version__ = version = '0.1.dev105'
+__version_tuple__ = version_tuple = (0, 1, 'dev105')
 
 __commit_id__ = commit_id = None

{core_lens-0.1.dev101 → core_lens-0.1.dev105}/src/core_lens/base/result.py

@@ -15,8 +15,9 @@ if TYPE_CHECKING:
     from core_lens.base.namespaces.stats import StatsNamespace
     from core_lens.base.namespaces.plot import PlotNamespace
 
-_FORTNIGHTLY_ONLY_BY = {"year", "month", "year_month", "season", "season_year"}
-_VALID_BY = {None} | _FORTNIGHTLY_ONLY_BY
+_FORTNIGHTLY_ONLY_BY = {"month", "year_month", "season", "season_year"}
+_ANNUAL_OR_FORTNIGHTLY_BY = {"year"}
+_VALID_BY = {None} | _FORTNIGHTLY_ONLY_BY | _ANNUAL_OR_FORTNIGHTLY_BY
 
 
 class Result:
@@ -194,7 +195,11 @@ class Result:
              - ❌
              - ✅
              - ✅
-           * - ``"year"`` / ``"month"`` / ``"year_month"`` / ``"season"`` / ``"season_year"``
+           * - ``"year"``
+             - ❌
+             - ✅
+             - ✅
+           * - ``"month"`` / ``"year_month"`` / ``"season"`` / ``"season_year"``
              - ❌
              - ❌
              - ✅
@@ -203,7 +208,9 @@ class Result:
             *exprs: One or more Polars aggregation expressions
                 (e.g. ``pl.mean("ndvi")``, ``pl.max("rainfall")``).
             by: Grouping dimension.  ``None`` collapses all rows to one.
-                Temporal groupings (``"year"``, ``"month"``, ``"year_month"``,
+                ``"year"`` groups by entity + year and is valid for both
+                annual and fortnightly resolution.
+                Other temporal groupings (``"month"``, ``"year_month"``,
                 ``"season"``, ``"season_year"``) require
                 ``resolution="fortnightly"``.
 

{core_lens-0.1.dev101 → core_lens-0.1.dev105}/src/core_lens/entities/__init__.py

@@ -2,5 +2,6 @@ __module__: str = "core_lens.entities"
 
 from core_lens.entities.tehsil import TehsilEntity
 from core_lens.entities.mws import MWSEntity
+from core_lens.entities.waterbody import WaterbodyEntity
 
-__all__ = ["TehsilEntity", "MWSEntity"]
+__all__ = ["TehsilEntity", "MWSEntity", "WaterbodyEntity"]

core_lens-0.1.dev105/src/core_lens/entities/waterbody.py

@@ -0,0 +1,32 @@
+from core_lens.base.entity import BaseEntity
+
+
+class WaterbodyEntity(BaseEntity):
+    """Waterbody entity.
+
+    Backed by:
+    - Static: waterbodies/static
+    - Annual: waterbodies/annual (partitioned by basin)
+
+    All paths are relative to the AoI ``data_root``.
+    """
+
+    @property
+    def key_cols(self) -> list[str]:
+        return ["wb_id"]
+
+    @property
+    def geometry_col(self) -> str:
+        return "geometry"
+
+    @property
+    def static_path(self) -> str:
+        return "waterbodies/static"
+
+    @property
+    def annual_path(self) -> str | None:
+        return "waterbodies/annual"
+
+    @property
+    def fortnightly_path(self) -> str | None:
+        return "waterbodies/fortnightly"

{core_lens-0.1.dev101 → core_lens-0.1.dev105}/tests/unit/test_result.py

@@ -220,11 +220,27 @@ class TestResultAggregate:
         with pytest.raises(ValueError, match="not supported on static"):
             result.aggregate(pl.mean("ndvi_mean"))
 
-    def test_aggregate_temporal_by_on_annual_raises(self, entity_cls: Any) -> None:
+    def test_aggregate_by_year_on_annual_succeeds(self, entity_cls: Any) -> None:
+        df = pl.DataFrame(
+            {
+                "mws_id": ["1", "1"],
+                "year": [2021, 2022],
+                "ndvi_mean": [0.4, 0.5],
+            }
+        )
+        result = _make_result(entity_cls(), resolution=Resolution.ANNUAL, data=df)
+        agg = result.aggregate(pl.mean("ndvi_mean"), by="year")
+
+        assert "year" in agg.df().columns
+        assert "mws_id" in agg.df().columns
+
+    def test_aggregate_fortnightly_only_by_on_annual_raises(
+        self, entity_cls: Any
+    ) -> None:
         result = _make_result(entity_cls(), resolution=Resolution.ANNUAL)
 
         with pytest.raises(ValueError, match="requires data at fortnightly resolution"):
-            result.aggregate(pl.mean("ndvi_mean"), by="year")
+            result.aggregate(pl.mean("ndvi_mean"), by="month")
 
     def test_aggregate_unknown_by_raises(self, entity_cls: Any) -> None:
         result = _make_result(entity_cls())
@@ -232,10 +248,8 @@ class TestResultAggregate:
         with pytest.raises(ValueError, match="Unknown grouping"):
             result.aggregate(pl.mean("ndvi_mean"), by="quarter")
 
-    @pytest.mark.parametrize(
-        "by", ["year", "month", "year_month", "season", "season_year"]
-    )
-    def test_all_fortnightly_by_keys_accepted(self, entity_cls: Any, by: Any) -> None:
+    @pytest.mark.parametrize("by", ["month", "year_month", "season", "season_year"])
+    def test_fortnightly_only_by_keys_accepted(self, entity_cls: Any, by: Any) -> None:
         df = pl.DataFrame(
             {
                 "mws_id": ["1"],

core_lens-0.1.dev105/wb_annual.txt

@@ -0,0 +1,11 @@
+tehsil                         String
+district                       String
+state                          String
+area_in_ha                     Float64
+wb_id                          String
+ba_name                        String
+year                           Int32
+area_ha                        Float64
+kharif                         Float64
+karif_rabi                     Float64
+kharif_rabi_zaid               Float64

core_lens-0.1.dev105/wb_static.txt

@@ -0,0 +1,11 @@
+tehsil                         String
+district                       String
+state                          String
+area_in_ha                     Float64
+wb_id                          String
+ba_name                        String
+year                           Int32
+area_ha                        Float64
+kharif                         Float64
+karif_rabi                     Float64
+kharif_rabi_zaid               Float64