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

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

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

{core_lens-0.1.dev130 → core_lens-0.1.dev133}/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.dev133}/src/core_lens/base/entity.py

@@ -11,6 +11,7 @@ Plugin authors import from the public surface::
 
 from __future__ import annotations
 
+import functools
 import pathlib
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any
@@ -35,6 +36,96 @@ if TYPE_CHECKING:
     from core_lens.schema.profile import SchemaProfile
 
 
+# ---------------------------------------------------------------------------
+# Process-level caches — shared across all BaseEntity instances in a process.
+#
+# Both caches are backed by functools.cache (lru_cache with maxsize=None).
+# maxsize=None means unbounded — intentional: evicting an index or schema
+# profile forces an expensive rebuild on the next access.
+#
+# _cached_detect       eliminates repeated detect() calls (OPT-2).
+# _cached_build_index  eliminates repeated build_bbox_index() calls (OPT-1).
+#
+# Cache diagnostics:  _cached_detect.cache_info() / _cached_build_index.cache_info()
+# Cache reset (tests): _cached_detect.cache_clear() / _cached_build_index.cache_clear()
+# ---------------------------------------------------------------------------
+
+
+def _so_key(storage_options: dict[str, Any]) -> tuple[tuple[str, Any], ...]:
+    """Convert a ``storage_options`` dict to a hashable, order-stable tuple.
+
+    All args passed to :func:`_cached_detect` and :func:`_cached_build_index`
+    must be hashable (``functools.cache`` requirement).  ``storage_options``
+    is a plain dict, so we convert it here before passing to the cached
+    functions.  Different cloud credentials for the same path produce
+    different cache keys.
+
+    Args:
+        storage_options (dict[str, Any]): Cloud credential / configuration dict.
+
+    Returns:
+        tuple[tuple[str, Any], ...]: A sorted tuple of ``(key, value)`` pairs.
+    """
+    return tuple(sorted(storage_options.items()))
+
+
+@functools.cache
+def _cached_detect(
+    static_path: str,
+    key_cols: tuple[str, ...],
+    geometry_col: str,
+    annual_path: str | None,
+    fortnightly_path: str | None,
+    storage_options_key: tuple[tuple[str, Any], ...],
+) -> "SchemaProfile":
+    """Cached wrapper around :func:`~core_lens.schema.detection.detect`.
+
+    All arguments must be hashable so they can form the cache key.  Pass
+    ``storage_options`` through :func:`_so_key` before calling this function.
+
+    Returns:
+        SchemaProfile: Detected schema profile for the given entity paths.
+    """
+    from core_lens.schema.detection import detect
+
+    return detect(
+        static_path=static_path,
+        key_cols=list(key_cols),
+        geometry_col=geometry_col,
+        annual_path=annual_path,
+        fortnightly_path=fortnightly_path,
+        storage_options=dict(storage_options_key) or None,
+    )
+
+
+@functools.cache
+def _cached_build_index(
+    static_path: str,
+    key_cols: tuple[str, ...],
+    bbox_cols: tuple[str, str, str, str] | None,
+    geometry_col: str,
+    geometry_type: str,
+    storage_options_key: tuple[tuple[str, Any], ...],
+) -> pl.DataFrame:
+    """Cached wrapper around :func:`~core_lens.utils.spatial.build_bbox_index`.
+
+    All arguments must be hashable so they can form the cache key.  Pass
+    ``storage_options`` through :func:`_so_key` before calling this function.
+
+    Returns:
+        pl.DataFrame: The bounding-box index DataFrame.
+    """
+    logger.debug("Building bbox index for {} (cache miss)", static_path)
+    return build_bbox_index(
+        static_path=static_path,
+        key_cols=list(key_cols),
+        bbox_cols=bbox_cols,
+        geometry_col=geometry_col,
+        geometry_type=geometry_type,
+        storage_options=dict(storage_options_key) or None,
+    )
+
+
 class BaseEntity(ABC):
     """Abstract base class for every entity in the core_lens plugin system.
 
@@ -228,19 +319,29 @@ class BaseEntity(ABC):
     def schema_profile(self) -> "SchemaProfile":
         """Validated schema descriptor for this entity's data files.
 
-        Auto-detected from Parquet file metadata on first access and cached on
-        the instance.  Override in subclasses to provide an explicit profile
-        instead of relying on detection.
+        Auto-detected from Parquet file metadata on first access.  The result
+        is cached at two levels:
+
+        1. **Instance level** — ``_schema_profile`` attribute set on ``self``
+           so that repeated property access within the same instance is a bare
+           attribute lookup with no dict overhead.
+        2. **Process level** — :func:`_cached_detect` (backed by
+           ``functools.cache``) keyed on the resolved paths and entity
+           configuration.  Different ``AoI()`` calls that point at the same
+           data directory share one ``SchemaProfile`` object, avoiding
+           redundant ``collect_schema()`` I/O.
+
+        Override in subclasses to provide an explicit profile instead of
+        relying on detection.
 
         Returns:
             SchemaProfile: A fully-validated :class:`~core_lens.schema.profile.SchemaProfile`.
         """
         if not hasattr(self, "_schema_profile"):
-            from core_lens.schema.detection import detect
-
-            self._schema_profile: SchemaProfile = detect(
+            _so = self._storage_options or {}
+            self._schema_profile: SchemaProfile = _cached_detect(
                 static_path=self._resolve(self.static_path),
-                key_cols=self.key_cols,
+                key_cols=tuple(self.key_cols),
                 geometry_col=self.geometry_col,
                 annual_path=(
                     self._resolve(self.annual_path)
@@ -252,24 +353,36 @@ class BaseEntity(ABC):
                     if self.fortnightly_path is not None
                     else None
                 ),
-                storage_options=self._storage_options or None,
+                storage_options_key=_so_key(_so),
             )
         return self._schema_profile
 
     @property
     def _index(self) -> pl.DataFrame:
+        """In-memory bounding-box index for spatial pre-filtering.
+
+        Cached at two levels (same strategy as :attr:`schema_profile`):
+
+        1. **Instance level** — ``_cached_index`` attribute on ``self``.
+        2. **Process level** — :func:`_cached_build_index` (backed by
+           ``functools.cache``) keyed on the resolved static path, key
+           columns, and bbox/geometry schema.  All entity instances that
+           resolve to the same static file share one index ``pl.DataFrame``,
+           eliminating repeated geometry decodes.
+
+        Returns:
+            pl.DataFrame: DataFrame with columns ``(*key_cols, minx, miny, maxx, maxy)``.
+        """
         if not hasattr(self, "_cached_index"):
-            logger.debug(
-                "Building lazy bounding box index for {}", self.__class__.__name__
-            )
-            profile = self.schema_profile
-            self._cached_index: pl.DataFrame = build_bbox_index(
+            profile = self.schema_profile  # already cached — no extra I/O
+            _so = self._storage_options or {}
+            self._cached_index: pl.DataFrame = _cached_build_index(
                 static_path=self._resolve(self.static_path),
-                key_cols=self.key_cols,
+                key_cols=tuple(self.key_cols),
                 bbox_cols=profile.bbox_cols,
                 geometry_col=profile.geometry_col,
                 geometry_type=profile.geometry_type,
-                storage_options=self._storage_options or None,
+                storage_options_key=_so_key(_so),
             )
         return self._cached_index
 

{core_lens-0.1.dev130 → core_lens-0.1.dev133}/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.dev133}/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.dev133}/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.dev133}/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