core-lens 0.1.dev74__tar.gz → 0.1.dev86__tar.gz

{core_lens-0.1.dev74 → core_lens-0.1.dev86}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev74
+Version: 0.1.dev86
 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.dev74 → core_lens-0.1.dev86}/SKILLS.md

@@ -91,7 +91,7 @@ Calculates correlation between columns either across entities or across time. Su
 result.stats.correlate(
     columns=["ndvi", "rainfall", "temperature"],
     method="pearson",
-    across="mws"
+    across="entity"
 )
 ```
 
@@ -112,7 +112,7 @@ result.stats.change(column="ndvi", from_period=2010, to_period=2023, method="tre
 ```
 
 ### Anomaly Detection
-Identifies anomalies cross-sectionally (vs other entities) or over time. 
+Identifies anomalies cross-sectionally (vs other entities) or over time.
 - **Cross-sectional methods:** `"zscore"`, `"iqr"`, `"percentile"`, `"threshold"`.
 - **Time-series methods:** `"stl"`, `"cusum"`, `"mad"`.
 ```python

{core_lens-0.1.dev74 → core_lens-0.1.dev86}/docs/source/queries.md

@@ -9,10 +9,12 @@ Filter time-series data using exact dates or agronomic seasons:
 annual_data = aoi.mws.between("2010-01-01", "2023-12-31").annual
 
 # Season-based filtering (defaults to Kharif, Rabi, Zaid)
-kharif_2020 = aoi.mws.between(season="kharif", year=2020).fortnightly
+from core_lens.base.view import Season
+
+kharif_2020 = aoi.mws.between(season=Season.KHARIF, year=2020).fortnightly
 
 # Current season based on today's date
-current = aoi.mws.between(season="current").fortnightly
+current = aoi.mws.between(season=Season.CURRENT).fortnightly
 ```
 
 ## Aggregations & Derived Columns

{core_lens-0.1.dev74 → core_lens-0.1.dev86}/docs/source/stats.md

@@ -17,10 +17,12 @@ desc_entity = res.stats.describe(by="entity")
 Find temporal or spatial correlations between variables:
 
 ```python
+from core_lens.base.namespaces.stats import CorrelateMethod
+
 corr = res.stats.correlate(
     columns=["ndvi", "rainfall", "temperature"],
-    method="pearson", # or "spearman", "kendall"
-    across="mws"      # correlate across entities or time
+    method=CorrelateMethod.PEARSON, # or SPEARMAN, KENDALL
+    across="entity"      # correlate across entities or time
 )
 ```
 
@@ -29,18 +31,20 @@ corr = res.stats.correlate(
 Test for significant differences between groups or periods:
 
 ```python
+from core_lens.base.namespaces.stats import TestMethod
+
 # Group-based testing
 test_res = res.stats.test(
     column="cropping_intensity",
     groups="temperature_zone",
-    method="mann-whitney"
+    method=TestMethod.MANN_WHITNEY
 )
 
 # Period-based testing
 test_period = res.stats.test(
     column="ndvi",
     periods=[(2010, 2015), (2016, 2023)],
-    method="t-test"
+    method=TestMethod.T_TEST
 )
 ```
 
@@ -49,12 +53,14 @@ test_period = res.stats.test(
 Analyse absolute, percentage, or trend changes over time:
 
 ```python
+from core_lens.base.namespaces.stats import ChangeMethod
+
 # Trend over time
 trend = res.stats.change(
     column="ndvi",
     from_period=2010,
     to_period=2023,
-    method="trend"
+    method=ChangeMethod.TREND
 )
 
 # Absolute or percentage change
@@ -62,7 +68,7 @@ pct_change = res.stats.change(
     column="tree_cover",
     from_period=2018,
     to_period=2023,
-    method="percentage"
+    method=ChangeMethod.PERCENTAGE
 )
 ```
 
@@ -71,11 +77,13 @@ pct_change = res.stats.change(
 Identify anomalies against a historical baseline or cross-sectionally:
 
 ```python
+from core_lens.base.namespaces.stats import AnomalyTsMethod, AnomalyCrossMethod
+
 # Timeseries anomaly against its own history
 ts_anomalies = res.stats.anomaly(
     column="ndvi",
     mode="timeseries",
-    method="stl",
+    method=AnomalyTsMethod.STL,
     baseline=(2010, 2018)
 )
 
@@ -83,7 +91,7 @@ ts_anomalies = res.stats.anomaly(
 cross_anomalies = res.stats.anomaly(
     column="ndvi",
     mode="cross_sectional",
-    method="zscore",
+    method=AnomalyCrossMethod.ZSCORE,
     baseline=(2010, 2020)
 )
 ```
@@ -93,13 +101,15 @@ cross_anomalies = res.stats.anomaly(
 Find entities similar to a target entity across multiple dimensions:
 
 ```python
+from core_lens.base.namespaces.stats import SimilarityMethod
+
 similar = res.stats.similarity(
     target="13_551",
     columns={
         "rainfall": ("annual", {"year": 2018}),
         "ndvi": ("fortnightly", {"season": "kharif", "year": 2020})
     },
-    method="euclidean",
+    method=SimilarityMethod.EUCLIDEAN,
     top_n=10
 )
 ```

{core_lens-0.1.dev74 → core_lens-0.1.dev86}/examples/demo_mws.py

@@ -171,7 +171,7 @@ print(desc_annual_by_entity.df().head(5))
 corr = result_fn.stats.correlate(
     columns=["df_precipitation", "df_et"],
     method="pearson",
-    across="mws",
+    across="entity",
 )
 print("\nCorrelation (Precipitation vs ET):")
 print(corr.df())
@@ -279,14 +279,6 @@ except Exception:
 
 # ── 23. Export ───────────────────────────────────────────────────────────────
 
-# Tabular (JSON or standard Parquet) — drop geometry first
-# The static table might have 'geom' or 'geometry' as the geometry column.
-# mws.py specifies geometry_col as "geometry".
-geom_col = MWSEntity().schema_profile.geometry_col
-pl_df = result_static_derived.df().drop(geom_col)
-pl_df.write_parquet("output_mws.parquet")
-print("\nParquet written: output_mws.parquet")
-
 # GeoParquet — preserves geometry
 geoparquet(result_static_derived, "output_mws.geoparquet")
 print("GeoParquet written: output_mws.geoparquet")

{core_lens-0.1.dev74 → core_lens-0.1.dev86}/examples/demo_tehsil.py

@@ -164,7 +164,7 @@ print(desc_by_entity.df().head(5))
 corr = result_with_area.stats.correlate(
     columns=["area_km2", "Shape_Leng", "compactness"],
     method="spearman",
-    across="mws",
+    across="entity",
 )
 print("\nCorrelation (Spearman):")
 print(corr.df())

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

{core_lens-0.1.dev74 → core_lens-0.1.dev86}/src/core_lens/base/namespaces/plot.py

@@ -2,8 +2,29 @@
 
 from __future__ import annotations
 
+from enum import Enum
 from typing import TYPE_CHECKING, Any
 
+
+class SubplotOn(Enum):
+    """Temporal dimensions to split plot data across.
+
+    Used to specify how data should be partitioned into subplots or map layers
+    based on temporal columns added during materialisation.
+
+    Attributes:
+        YEAR: Split data by year.
+        MONTH: Split data by month.
+        SEASON: Split data by meteorological season.
+        SEASON_YEAR: Split data by season and year.
+    """
+
+    YEAR = "year"
+    MONTH = "month"
+    SEASON = "season"
+    SEASON_YEAR = "season_year"
+
+
 if TYPE_CHECKING:
     import lonboard
     from core_lens.base.result import Result
@@ -50,7 +71,9 @@ class PlotNamespace:
     def __init__(self, result: "Result") -> None:
         self.result = result
 
-    def choropleth(self, column: str, subplot_on: str | None = None) -> "lonboard.Map":
+    def choropleth(
+        self, column: str, subplot_on: SubplotOn | None = None
+    ) -> "lonboard.Map":
         """Render an interactive choropleth map using Lonboard.
 
         If the Result does not already have geometry, it will be attached
@@ -59,8 +82,7 @@ class PlotNamespace:
         Args:
             column: The column to use for colour mapping.
             subplot_on: Optional temporal dimension to split data across.
-                Valid values: ``\"year\"``, ``\"month\"``, ``\"season\"``,
-                ``\"season_year\"``.  When set, one layer is rendered per unique
+                A :class:`~core_lens.base.namespaces.plot.SubplotOn` enum value. When set, one layer is rendered per unique
                 value of ``subplot_on`` in the data.
 
         Returns:
@@ -74,23 +96,23 @@ class PlotNamespace:
         import lonboard
         from lonboard.colormap import apply_continuous_cmap
 
-        _VALID_SUBPLOT_ON = {"year", "month", "season", "season_year"}
-
-        if subplot_on is not None and subplot_on not in _VALID_SUBPLOT_ON:
+        if subplot_on is not None and not isinstance(subplot_on, SubplotOn):
             raise ValueError(
-                f"PlotNamespace.choropleth: Unknown subplot_on={subplot_on!r}. "
-                f"Valid options: {sorted(_VALID_SUBPLOT_ON)}."
+                f"PlotNamespace.choropleth: subplot_on must be a SubplotOn enum. "
+                f"Valid options: {[e.name for e in SubplotOn]}."
             )
 
+        subplot_col = subplot_on.value if subplot_on is not None else None
+
         res = self.result if self.result.has_geometry else self.result.with_geometry()
         gdf = res.gdf()
 
         if column not in gdf.columns:
             raise ValueError(f"Column {column!r} not found in Result.")
 
-        if subplot_on is not None and subplot_on not in gdf.columns:
+        if subplot_col is not None and subplot_col not in gdf.columns:
             raise ValueError(
-                f"PlotNamespace.choropleth: subplot_on column {subplot_on!r} not found "
+                f"PlotNamespace.choropleth: subplot_on column {subplot_col!r} not found "
                 "in Result. Ensure fortnightly data is materialised and temporal columns "
                 "are present (they are added automatically by the materialisation layer)."
             )
@@ -120,13 +142,13 @@ class PlotNamespace:
         import matplotlib as mpl
         import numpy as np
 
-        if subplot_on is not None:
+        if subplot_col is not None:
             # Render the most-recent/first unique value of subplot_on so that the
             # map is still useful.  True multi-panel subplots are not supported by
             # Lonboard's single-Map API.
-            unique_vals = sorted(gdf[subplot_on].dropna().unique().tolist())
+            unique_vals = sorted(gdf[subplot_col].dropna().unique().tolist())
             if unique_vals:
-                gdf = gdf[gdf[subplot_on] == unique_vals[-1]].copy()
+                gdf = gdf[gdf[subplot_col] == unique_vals[-1]].copy()
 
         values = gdf[column].to_numpy()
         v_min, v_max = np.nanmin(values), np.nanmax(values)