core-lens 0.1.dev130__tar.gz → 0.1.dev132__tar.gz

{core_lens-0.1.dev130 → core_lens-0.1.dev132}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev130
+Version: 0.1.dev132
 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.dev130 → core_lens-0.1.dev132}/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.dev130'
-__version_tuple__ = version_tuple = (0, 1, 'dev130')
+__version__ = version = '0.1.dev132'
+__version_tuple__ = version_tuple = (0, 1, 'dev132')
 
 __commit_id__ = commit_id = None

{core_lens-0.1.dev130 → core_lens-0.1.dev132}/src/core_lens/aoi.py

@@ -22,7 +22,7 @@ if TYPE_CHECKING:
     from core_lens.base.view import View
 
 
-@dataclass
+@dataclass(frozen=True)
 class SeasonConfig:
     """Date-range definitions for the three Indian crop seasons.
 
@@ -96,6 +96,29 @@ def _md_in_range(md: str, start: str, end: str) -> bool:
     return md >= start or md <= end
 
 
+# Singleton for the default SeasonConfig — constructed once per process.
+# SeasonConfig.__post_init__ runs 6× datetime.strptime calls for validation;
+# sharing the default instance eliminates that cost for every AoI() call
+# that does not supply a custom season config.
+_DEFAULT_SEASON_CONFIG: SeasonConfig | None = None
+
+
+def _default_season_config() -> SeasonConfig:
+    """Return the shared default :class:`SeasonConfig` instance.
+
+    Constructed once per process and reused thereafter.  Callers that need
+    a custom config should construct their own :class:`SeasonConfig` and
+    pass it to :class:`AoI`.
+
+    Returns:
+        SeasonConfig: The shared default instance.
+    """
+    global _DEFAULT_SEASON_CONFIG
+    if _DEFAULT_SEASON_CONFIG is None:
+        _DEFAULT_SEASON_CONFIG = SeasonConfig()
+    return _DEFAULT_SEASON_CONFIG
+
+
 # Class-level registry: entity name → entity **class**.
 # Shared across all AoI instances in a process.  Explicit registration is
 # required; there is no auto-discovery (design §6.1).
@@ -191,7 +214,7 @@ class AoI:
             self.data_root = pathlib.Path(data_root_str).resolve()
 
         self._storage_options: dict[str, Any] = storage_options or {}
-        self.seasons: SeasonConfig = seasons or SeasonConfig()
+        self.seasons: SeasonConfig = seasons or _default_season_config()
         logger.info("Initializing AoI with data_root={}", self.data_root)
 
         n_modes = sum(

{core_lens-0.1.dev130 → core_lens-0.1.dev132}/src/core_lens/base/view.py

@@ -407,28 +407,18 @@ class View:
             if time_col is not None:
                 from core_lens.utils.season import resolve_time_filter
 
-                # Fall back to a no-op SeasonConfig if none was supplied on this View.
-                from core_lens.aoi import SeasonConfig
-
-                season_cfg = self._season_config or SeasonConfig()
-
-                # Detect whether the time column is an integer year column so
-                # _date_range_expr can branch at expression-build time (avoids
-                # the cast-to-string + runtime when/then triple-copy).
-                try:
-                    pq_schema = pl.scan_parquet(
-                        abs_path,
-                        storage_options=self._storage_options or None,
-                    ).collect_schema()
-                    _time_dtype = pq_schema.get(time_col)
-                    _is_year_col = _time_dtype is not None and _time_dtype in (
-                        pl.Int32,
-                        pl.Int64,
-                        pl.UInt32,
-                        pl.UInt16,
-                    )
-                except Exception:
-                    _is_year_col = False
+                # Fall back to the default SeasonConfig if none was supplied on this View.
+                from core_lens.aoi import _default_season_config
+
+                season_cfg = self._season_config or _default_season_config()
+
+                # Read is_year_col from the cached schema profile — populated at
+                # detect() time from the Parquet schema, so no extra I/O here.
+                _is_year_col: bool | None = (
+                    profile.annual_is_year_col
+                    if resolution == Resolution.ANNUAL
+                    else profile.fortnightly_is_year_col
+                )
 
                 # Pass as a private hint inside the filter dict (non-mutating copy).
                 _tf = dict(self.time_filter)
@@ -454,9 +444,9 @@ class View:
             and profile.fortnightly_time_col is not None
         ):
             from core_lens.utils.season import add_temporal_columns
-            from core_lens.aoi import SeasonConfig
+            from core_lens.aoi import _default_season_config
 
-            season_cfg = self._season_config or SeasonConfig()
+            season_cfg = self._season_config or _default_season_config()
             data = add_temporal_columns(data, profile.fortnightly_time_col, season_cfg)
 
         if self.join_spec is not None:

{core_lens-0.1.dev130 → core_lens-0.1.dev132}/src/core_lens/schema/detection.py

@@ -104,6 +104,7 @@ def detect(
 
     annual_time_col: str | None = None
     extra_annual_cols: list[str] = []
+    annual_is_year_col: bool | None = None
     if annual_path:
         annual_schema = _read_schema(
             annual_path, label="annual", storage_options=_so or None
@@ -113,9 +114,11 @@ def detect(
             {annual_time_col} if annual_time_col else set()
         )
         extra_annual_cols = [c for c in annual_schema if c not in reserved_annual]
+        annual_is_year_col = _is_year_col_from_schema(annual_schema, annual_time_col)
 
     fortnightly_time_col: str | None = None
     extra_fortnightly_cols: list[str] = []
+    fortnightly_is_year_col: bool | None = None
     if fortnightly_path:
         fortnightly_schema = _read_schema(
             fortnightly_path, label="fortnightly", storage_options=_so or None
@@ -125,6 +128,9 @@ def detect(
             {fortnightly_time_col} if fortnightly_time_col else set()
         )
         extra_fortnightly_cols = [c for c in fortnightly_schema if c not in reserved_fn]
+        fortnightly_is_year_col = _is_year_col_from_schema(
+            fortnightly_schema, fortnightly_time_col
+        )
 
     return SchemaProfile(
         key_cols=key_cols,
@@ -136,6 +142,8 @@ def detect(
         extra_static_cols=extra_static_cols,
         extra_annual_cols=extra_annual_cols,
         extra_fortnightly_cols=extra_fortnightly_cols,
+        annual_is_year_col=annual_is_year_col,
+        fortnightly_is_year_col=fortnightly_is_year_col,
     )
 
 
@@ -237,3 +245,31 @@ def _infer_time_col(schema: pl.Schema, path: str) -> str | None:
             return col
 
     return None
+
+
+_YEAR_COL_DTYPES = (pl.Int32, pl.Int64, pl.UInt32, pl.UInt16)
+
+
+def _is_year_col_from_schema(
+    schema: pl.Schema,
+    time_col: str | None,
+) -> bool | None:
+    """Return whether *time_col* is an integer-year column, or ``None`` if absent.
+
+    ``True``  — integer dtype (``Int32`` / ``Int64`` / ``UInt32`` / ``UInt16``).
+    ``False`` — ``Date`` / ``Datetime`` column.
+    ``None``  — *time_col* is ``None`` or not found in *schema*.
+
+    Args:
+        schema (pl.Schema): The Parquet schema returned by ``collect_schema()``.
+        time_col (str | None): The name of the time column, or ``None``.
+
+    Returns:
+        bool | None: ``True`` for integer-year, ``False`` for Date/Datetime, ``None`` if absent.
+    """
+    if time_col is None:
+        return None
+    dtype = schema.get(time_col)
+    if dtype is None:
+        return None
+    return dtype in _YEAR_COL_DTYPES

{core_lens-0.1.dev130 → core_lens-0.1.dev132}/src/core_lens/schema/profile.py

@@ -69,6 +69,12 @@ class SchemaProfile(BaseModel):
     extra_static_cols: list[str] = []
     extra_annual_cols: list[str] = []
     extra_fortnightly_cols: list[str] = []
+    # Whether the time column is an integer-year column (True), a Date/Datetime
+    # column (False), or absent/unknown (None).  Determined at detect() time from
+    # the Parquet schema — eliminates a redundant collect_schema() call in
+    # View._materialise for every .annual / .fortnightly access.
+    annual_is_year_col: bool | None = None
+    fortnightly_is_year_col: bool | None = None
 
     @classmethod
     def from_file(cls, path: str | pathlib.Path) -> "SchemaProfile":

{core_lens-0.1.dev130 → core_lens-0.1.dev132}/src/core_lens/utils/spatial.py

@@ -247,28 +247,39 @@ def exact_spatial_filter(
     else:
         geoms = shapely.from_wkt(geom_array)
 
+    import numpy as np
+
     if relationship == "centroid":
         # Centroid mode: entity centroid must lie within the AoI geometry.
-        # STRtree.query(aoi_geometry, predicate="contains") returns i where
-        # aoi_geometry.contains(centroid[i]) — i.e. centroid inside the AoI.
-        test_geoms = [g.centroid for g in geoms]
-        tree = shapely.STRtree(test_geoms)
-        hit_indices = tree.query(aoi_geometry, predicate="contains").tolist()
+        # STRtree is overkill for a single-query containment test — building
+        # the tree costs O(n log n) with no payoff when there is only one query
+        # geometry.  Vectorised shapely ops stay in C and avoid the overhead.
+        centroids = shapely.centroid(geoms)  # vectorised, C-level
+        mask = shapely.contains(aoi_geometry, centroids)  # vectorised bool array
+        hit_indices = np.where(mask)[0].tolist()
 
     else:  # area mode
-        # Area mode: intersection area / entity area > threshold.
+        # Area mode: intersection area / entity area >= threshold.
+        # Vectorise: compute all areas and intersections in C via numpy arrays.
         tree = shapely.STRtree(geoms)
-        # Candidate indices whose envelope intersects aoi_geometry.
-        intersect_idx = tree.query(aoi_geometry, predicate="intersects").tolist()
-        hit_indices = []
-        for i in intersect_idx:
-            entity_geom = geoms[i]
-            entity_area = entity_geom.area  # pyright: ignore[reportAttributeAccessIssue]
-            if entity_area == 0.0:
-                continue
-            inter_area = entity_geom.intersection(aoi_geometry).area  # pyright: ignore[reportAttributeAccessIssue]
-            if inter_area / entity_area >= threshold:
-                hit_indices.append(i)
+        intersect_idx = np.asarray(
+            tree.query(aoi_geometry, predicate="intersects"), dtype=np.intp
+        )
+        if len(intersect_idx) == 0:
+            hit_indices = []
+        else:
+            candidate_geoms = geoms[intersect_idx]
+            entity_areas = shapely.area(candidate_geoms)  # vectorised
+            valid = entity_areas > 0
+            if not valid.any():
+                hit_indices = []
+            else:
+                inter_geoms = shapely.intersection(
+                    candidate_geoms[valid], aoi_geometry
+                )  # vectorised
+                inter_areas = shapely.area(inter_geoms)  # vectorised
+                ratios = inter_areas / entity_areas[valid]
+                hit_indices = intersect_idx[valid][ratios >= threshold].tolist()
 
     del geoms  # free all decoded Shapely geometries before assembling result