core-lens 0.1.dev142__tar.gz → 0.1.dev147__tar.gz

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev142
+Version: 0.1.dev147
 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.dev142 → core_lens-0.1.dev147}/benchmarks/bench_aoi.py

@@ -116,7 +116,7 @@ view = aoi_bbox.mws
 
 t1 = time.perf_counter()
 print(f"First access     : {(t1 - t0) * 1000:.2f} ms")
-print(f"Keys shape       : {view.keys.shape}")
+print(f"Keys shape       : {view.keys.collect().shape}")
 
 # Second access — should hit _scoped cache (near-zero cost).
 t0 = time.perf_counter()

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/benchmarks/bench_export.py

@@ -45,8 +45,8 @@ aoi_small = AoI(DATA_ROOT, bbox=SMALL_BBOX)
 result_all = aoi_all.mws.static  # full dataset — geometry present
 result_small = aoi_small.mws.static  # small subset
 
-print(f"All   result : {result_all.data.shape}")
-print(f"Small result : {result_small.data.shape}")
+print(f"All   result : {result_all.df().shape}")
+print(f"Small result : {result_small.df().shape}")
 
 
 def _section(title: str) -> None:
@@ -81,9 +81,9 @@ with tempfile.TemporaryDirectory() as tmpdir:
     # Strip geometry (and nested bbox) to pass has_geometry=False and allow CSV export.
     geom_col = result_small.entity.geometry_col
     drop_cols = [geom_col]
-    if "bbox" in result_small.data.columns:
+    if "bbox" in result_small.df().columns:
         drop_cols.append("bbox")
-    df_no_geom = result_small.data.drop(drop_cols)
+    df_no_geom = result_small.df().drop(drop_cols)
     result_no_geom = result_small._replace(data=df_no_geom, has_geometry=False)
 
     REPS_IO = 5
@@ -99,7 +99,7 @@ with tempfile.TemporaryDirectory() as tmpdir:
     )
 
     # All dataset.
-    df_all_no_geom = result_all.data.drop(geom_col)
+    df_all_no_geom = result_all.df().drop(geom_col)
     result_all_no_geom = result_all._replace(data=df_all_no_geom, has_geometry=False)
     out_all = tmp / "bench_all.parquet"
     t0 = time.perf_counter()

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/benchmarks/bench_result.py

@@ -41,7 +41,7 @@ aoi_small = AoI(DATA_ROOT, bbox=SMALL_BBOX)
 # Materialise once — all benchmarks below operate on this result.
 result = aoi.mws.static
 result_small = aoi_small.mws.static
-print(f"Dataset: {result.data.shape[0]} MWS, {result.data.shape[1]} columns")
+print(f"Dataset: {result.df().shape[0]} MWS, {result.df().shape[1]} columns")
 
 
 def _section(title: str) -> None:
@@ -151,7 +151,7 @@ agg_result = result_annual.aggregate(
 )
 t1 = time.perf_counter()
 print(f"aggregate(no by) : {(t1 - t0) * 1000:.2f} ms")
-print(f"Shape            : {agg_result.data.shape}")
+print(f"Shape            : {agg_result.df().shape}")
 
 
 # ── 8. Result.aggregate(by='year') ──────────────────────────────────────────────
@@ -165,7 +165,7 @@ agg_year = result_annual.aggregate(
 )
 t1 = time.perf_counter()
 print(f"aggregate(year)  : {(t1 - t0) * 1000:.2f} ms")
-print(f"Shape            : {agg_year.data.shape}")
+print(f"Shape            : {agg_year.df().shape}")
 
 
 # ── Cleanup ───────────────────────────────────────────────────────────────

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/benchmarks/bench_season.py

@@ -25,6 +25,7 @@ import time
 from datetime import date, timedelta
 
 import polars as pl
+from typing import cast
 
 from core_lens.aoi import SeasonConfig
 from core_lens.utils.season import add_temporal_columns, resolve_time_filter
@@ -167,9 +168,9 @@ t0 = time.perf_counter()
 result_df = add_temporal_columns(FORTNIGHTLY_DF, "date", cfg)
 t1 = time.perf_counter()
 print(f"add_temporal_columns: {(t1 - t0) * 1000:.2f} ms")
-print(f"Output shape        : {result_df.shape}")
+print(f"Output shape        : {cast(pl.DataFrame, result_df).shape}")
 print(
-    f"New columns added   : {[c for c in result_df.columns if c not in FORTNIGHTLY_DF.columns]}"
+    f"New columns added   : {[c for c in cast(pl.DataFrame, result_df).columns if c not in FORTNIGHTLY_DF.columns]}"
 )
 
 # Second call — all columns already present, should be near-zero.
@@ -186,6 +187,8 @@ t0 = time.perf_counter()
 filtered = result_df.filter(expr)
 t1 = time.perf_counter()
 print(f"filter(kharif 2022) : {(t1 - t0) * 1000:.2f} ms")
-print(f"Rows matched        : {len(filtered):,} / {len(result_df):,}")
+print(
+    f"Rows matched        : {len(cast(pl.DataFrame, filtered)):,} / {len(cast(pl.DataFrame, result_df)):,}"
+)
 
 print("\n✓ bench_season.py complete")

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/benchmarks/bench_spatial.py

@@ -180,7 +180,7 @@ view = entity.spatial_filter(bbox=SMALL_BBOX)
 
 t1 = time.perf_counter()
 print(f"spatial_filter (bbox) : {(t1 - t0) * 1000:.2f} ms")
-print(f"View keys             : {view.keys.shape}")
+print(f"View keys             : {view.keys.collect().shape}")
 
 t0 = time.perf_counter()
 view2 = entity.spatial_filter(geometry=small_poly)

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/benchmarks/bench_view.py

@@ -50,7 +50,7 @@ t0 = time.perf_counter()
 view_all = aoi.mws
 t1 = time.perf_counter()
 print(f"aoi.mws          : {(t1 - t0) * 1000:.2f} ms")
-print(f"Keys             : {view_all.keys.shape}")
+print(f"Keys             : {view_all.keys.collect().shape}")
 
 
 # ── 2. View.where() — single filter ──────────────────────────────────────────
@@ -59,7 +59,7 @@ t0 = time.perf_counter()
 view_bihar = view_all.where(state="Bihar")
 t1 = time.perf_counter()
 print(f"where(state)     : {(t1 - t0) * 1000:.2f} ms")
-print(f"Bihar keys       : {view_bihar.keys.shape}")
+print(f"Bihar keys       : {view_bihar.keys.collect().shape}")
 
 
 # ── 3. View.where() — composite AND filter ────────────────────────────────────
@@ -68,7 +68,7 @@ t0 = time.perf_counter()
 view_banka = view_all.where(state="Bihar", district="Banka", tehsil="Banka")
 t1 = time.perf_counter()
 print(f"where(3 cols)    : {(t1 - t0) * 1000:.2f} ms")
-print(f"Banka keys       : {view_banka.keys.shape}")
+print(f"Banka keys       : {view_banka.keys.collect().shape}")
 
 
 # ── 4. View.spatial_filter() — further narrow ─────────────────────────────────
@@ -78,7 +78,7 @@ t0 = time.perf_counter()
 view_spatial = view_all.spatial_filter(bbox=SMALL_BBOX)
 t1 = time.perf_counter()
 print(f"spatial_filter   : {(t1 - t0) * 1000:.2f} ms")
-print(f"Spatial keys     : {view_spatial.keys.shape}")
+print(f"Spatial keys     : {view_spatial.keys.collect().shape}")
 
 
 # ── 5. View.between() — date range (no I/O) ───────────────────────────────────
@@ -112,14 +112,14 @@ t0 = time.perf_counter()
 result_static = aoi.mws.static
 t1 = time.perf_counter()
 print(f"static (all)     : {(t1 - t0) * 1000:.2f} ms")
-print(f"Shape            : {result_static.data.shape}")
+print(f"Shape            : {result_static.df().shape}")
 
 _section("8. aoi_small.mws.static  [small-bbox materialisation]")
 t0 = time.perf_counter()
 result_small = aoi_small.mws.static
 t1 = time.perf_counter()
 print(f"static (small)   : {(t1 - t0) * 1000:.2f} ms")
-print(f"Shape            : {result_small.data.shape}")
+print(f"Shape            : {result_small.df().shape}")
 
 
 # ── 9. Chained pipeline: where → spatial_filter → static ─────────────────────
@@ -128,7 +128,7 @@ t0 = time.perf_counter()
 result_chain = aoi.mws.spatial_filter(bbox=SMALL_BBOX).static
 t1 = time.perf_counter()
 print(f"Chain            : {(t1 - t0) * 1000:.2f} ms")
-print(f"Shape            : {result_chain.data.shape}")
+print(f"Shape            : {result_chain.df().shape}")
 
 
 # ── 10. annual materialisation ──────────────────────────────────────────────────
@@ -137,7 +137,7 @@ t0 = time.perf_counter()
 result_annual = aoi_small.mws.between("2018-01-01", "2023-12-31").annual
 t1 = time.perf_counter()
 print(f"annual           : {(t1 - t0) * 1000:.2f} ms")
-print(f"Shape            : {result_annual.data.shape}")
+print(f"Shape            : {result_annual.df().shape}")
 
 
 # ── 11. fortnightly materialisation ───────────────────────────────────────────
@@ -146,7 +146,7 @@ t0 = time.perf_counter()
 result_fn = aoi_small.mws.between(season=Season.KHARIF, year=2022).fortnightly
 t1 = time.perf_counter()
 print(f"fortnightly      : {(t1 - t0) * 1000:.2f} ms")
-print(f"Shape            : {result_fn.data.shape}")
+print(f"Shape            : {result_fn.df().shape}")
 
 
 # ── Cleanup ───────────────────────────────────────────────────────────────────

core_lens-0.1.dev147/docs/source/concepts.md

@@ -0,0 +1,7 @@
+# Core Concepts
+
+CoreLens is built on three main layers:
+
+1. **AoI (Area of Interest)**: The primary entry point. It represents a spatial boundary and acts as a gateway to all registered entities that intersect that boundary.
+2. **View**: A lazy, immutable query definition. Filtering by attributes (`where`), space (`spatial_filter`), or time (`between`) returns a new `View` without reading any Parquet data.
+3. **Result**: The lazy computation graph. Accessing `.static`, `.annual`, or `.fortnightly` on a `View` resolves the query plan and returns a `Result` object wrapping a Polars `LazyFrame`. Data is not actually read until you materialise it by calling `.df()` or `.gdf()`. This delays execution and reduces memory footprint, allowing the Polars streaming engine (automatically routed to the GPU if RAPIDS `cudf-polars` is installed) to optimize the query globally. All statistical operations, aggregations, and plotting are done on `Result` objects.

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/docs/source/quickstart.md

@@ -43,8 +43,9 @@ aoi_specific = AoI(
 # You can now access entities scoped to this AoI:
 mws_view = aoi.mws
 
-# Materialise the static data (GeoDataFrame)
+# Resolve the static data query
 static_result = mws_view.static
+# Materialise as a GeoDataFrame (or use .df() for a Polars DataFrame)
 gdf = static_result.gdf()
 
 # Plot the AoI and its microwatersheds on an interactive map

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/docs/source/stats.md

@@ -1,6 +1,6 @@
 # Statistical Analysis
 
-The `result.stats` namespace provides powerful analytical tools for geospatial and timeseries data. All statistical methods return a new `Result` object with computed `data` and populated `metadata`.
+The `result.stats` namespace provides powerful analytical tools for geospatial and timeseries data. All statistical methods return a new `Result` object with the computed lazy `data` and populated `metadata`.
 
 ## Descriptive Statistics
 

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

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/src/core_lens/aoi.py

@@ -20,6 +20,7 @@ from loguru import logger
 
 from core_lens.base.entity import BaseEntity, EntityValidationError
 from core_lens.utils.paths import is_cloud_uri
+from core_lens.utils.polars_utils import cached_read_schema
 
 if TYPE_CHECKING:
     from core_lens.base.view import View
@@ -219,7 +220,7 @@ def _cached_resolve_boundary(
 
     lf = pl.scan_parquet(static_path, storage_options=storage_options or None)
     filter_expr = pl.lit(True)
-    schema_types = lf.collect_schema()
+    schema_types = cached_read_schema(static_path, storage_options)
     for col, val in entity_kwargs.items():
         if col in schema.key_cols or col in schema.extra_static_cols:
             is_list_col = isinstance(schema_types.get(col), pl.List)
@@ -383,19 +384,16 @@ class AoI:
         # Entity instances are created lazily on first access via _get_entity().
         self._entity_instances: dict[str, BaseEntity] = {}
 
-        # Initialise boundary-entity cache.  Only populated by the
-        # named-boundary path (_resolve_named_boundary); bbox= / geometry=
-        # construction leaves these as None so __getattr__ falls through
-        # to the normal spatial_filter path for every entity.
-        self._boundary_entity_name: str | None = None
-        self._boundary_keys: pl.DataFrame | None = None
+        # Initialise boundary kwargs and lazily computed geometry.
+        self._boundary_kwargs: dict[str, str | list[str]] | None = None
+        self._geometry: shapely.Geometry | None = None
 
         if geometry is not None:
-            self.geometry: "shapely.Geometry" = geometry
+            self._geometry = geometry
         elif bbox is not None:
-            self.geometry = _bbox_to_polygon(bbox)
+            self._geometry = _bbox_to_polygon(bbox)
         else:
-            self.geometry = self._resolve_named_boundary(entity_kwargs)
+            self._boundary_kwargs = entity_kwargs
 
         # Entity views are created lazily on demand in __getattr__.
         self._scoped: dict[str, "View"] = {}
@@ -406,6 +404,17 @@ class AoI:
         if validate_all:
             self.validate()
 
+    @property
+    def geometry(self) -> "shapely.Geometry":
+        """The resolved boundary of this AoI as a Shapely geometry."""
+        if self._geometry is None:
+            if self._boundary_kwargs is not None:
+                self._geometry = self._resolve_named_boundary(self._boundary_kwargs)
+            else:
+                # Should not happen if initialization was correct
+                raise ValueError("No boundary defined.")
+        return self._geometry
+
     @property
     def current_season(self) -> str:
         """The season name for today's date under the AoI's SeasonConfig.
@@ -466,7 +475,7 @@ class AoI:
                     list(overlay.key_cols) if hasattr(overlay, "key_cols") else []
                 )
                 arrow_table = _wkb_to_arrow_table(
-                    overlay.data, geom_col, extra_cols=key_cols
+                    overlay.df(), geom_col, extra_cols=key_cols
                 )
                 overlay_layer = lonboard.PolygonLayer(
                     arrow_table,
@@ -538,23 +547,12 @@ class AoI:
         if name in _REGISTRY:
             if name not in self._scoped:
                 entity = self._get_entity(name)
-                if name == self._boundary_entity_name:
-                    # This entity *defined* the AoI boundary — we already
-                    # have its exact matching keys from
-                    # _resolve_named_boundary.  Skip the bbox-index build
-                    # and geometric predicate entirely.
-                    from core_lens.base.view import View
-
-                    assert (
-                        self._boundary_keys is not None
-                    )  # set by _resolve_named_boundary
-                    view = View(
-                        keys=self._boundary_keys,
-                        entity=entity,
-                        entity_name=name,
-                    )
+
+                if self._boundary_kwargs is not None:
+                    view = entity.where(**self._boundary_kwargs)
                 else:
                     view = entity.spatial_filter(geometry=self.geometry)
+
                 view._season_config = self.seasons
                 self._scoped[name] = view
             return self._scoped[name]
@@ -608,24 +606,6 @@ class AoI:
         # Reconstruct the boundary geometry from cached WKB bytes (fast).
         geometry: shapely.Geometry = shapely.from_wkb(geom_wkb)
 
-        # Reconstruct _boundary_keys DataFrame from cached key_rows.
-        # We need the key column names — get them from the boundary entity.
-        boundary_entity_cls = _REGISTRY.get(boundary_entity_name)
-        if boundary_entity_cls is not None:
-            key_cols = boundary_entity_cls().key_cols
-            self._boundary_entity_name = boundary_entity_name
-            self._boundary_keys = pl.DataFrame(
-                {col: [row[i] for row in key_rows] for i, col in enumerate(key_cols)}
-            )
-        else:
-            # Registry changed since cache was populated — defensive fallback.
-            logger.warning(
-                "Boundary cache returned entity name '{}' not found in current registry.",
-                boundary_entity_name,
-            )
-            self._boundary_entity_name = None
-            self._boundary_keys = None
-
         return geometry
 
     @classmethod

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/src/core_lens/base/entity.py

@@ -29,6 +29,7 @@ from core_lens.utils.spatial import (
     build_bbox_index,
     exact_spatial_filter,
 )
+from core_lens.utils.polars_utils import cached_read_schema
 
 if TYPE_CHECKING:
     import shapely
@@ -371,6 +372,20 @@ class BaseEntity(ABC):
             )
         return self._schema_profile
 
+    @property
+    def geometry_lazy(self) -> pl.LazyFrame:
+        """A cached LazyFrame representing the geometry of this entity.
+
+        Contains only the key columns and the geometry column. Used to avoid
+        repeatedly scanning and selecting geometries in downstream operations.
+        """
+        if not hasattr(self, "_geometry_lazy"):
+            self._geometry_lazy = pl.scan_parquet(
+                self._resolve(self.static_path),
+                storage_options=self._storage_options or None,
+            ).select(self.key_cols + [self.schema_profile.geometry_col])
+        return self._geometry_lazy
+
     @property
     def _index(self) -> pl.DataFrame:
         """In-memory bounding-box index for spatial pre-filtering.
@@ -434,7 +449,7 @@ class BaseEntity(ABC):
         )
 
         static = self._resolve(self.static_path)
-        schema = pl.read_parquet_schema(static)
+        schema = cached_read_schema(static, self._storage_options)
 
         attr_kwargs = {k: v for k, v in kwargs.items() if k in schema}
         entity_kwargs = {k: v for k, v in kwargs.items() if k not in schema}
@@ -453,77 +468,96 @@ class BaseEntity(ABC):
                     f"Available columns: {sorted(schema)}."
                 )
 
-        # --- Attribute filter -----------------------------------------------
+        # --- Combine attribute and spatial filters into a single lazy pipeline ---
+        lf = pl.scan_parquet(static)
+
         if attr_kwargs:
             filter_expr = pl.lit(True)
             for col, val in attr_kwargs.items():
                 filter_expr = filter_expr & (pl.col(col) == val)
-            keys = (
-                pl.scan_parquet(static)
-                .filter(filter_expr)
-                .select(self.key_cols)
-                .collect()
-            )
+            lf = lf.filter(filter_expr)
+
+        if not entity_kwargs:
+            keys = lf.select(self.key_cols).collect()
         else:
-            # No attribute filter: start with all entities.
-            keys = pl.scan_parquet(static).select(self.key_cols).collect()
-
-        # --- Spatial entity lookups -----------------------------------------
-        for entity_kwarg_name, entity_kwarg_val in entity_kwargs.items():
-            other_entity = _REGISTRY[entity_kwarg_name](data_root=self._data_root)
-            other_profile = other_entity.schema_profile
-            other_static = other_entity._resolve(other_entity.static_path)
+            import shapely
             import shapely.wkb as swkb
+            import shapely.wkt as swkt
             import shapely.ops as sops
-
-            # Find the geometry of the named entity.
-            lf = pl.scan_parquet(other_static)
-            match_expr = pl.lit(False)
-            for col in other_entity.key_cols + list(other_profile.extra_static_cols):
-                if col in pl.read_parquet_schema(other_static):
-                    match_expr = match_expr | (pl.col(col) == entity_kwarg_val)
-            matched = (
-                lf.filter(match_expr).select([other_profile.geometry_col]).collect()
-            )
-
-            if matched.is_empty():
-                logger.error(
-                    "BaseEntity.where failed: No rows matched {}={!r} in {}",
-                    entity_kwarg_name,
-                    entity_kwarg_val,
-                    other_entity.static_path,
+            import numpy as np
+            from core_lens.utils.spatial import bbox_intersects_geometry
+
+            lookup_geoms = []
+            for entity_kwarg_name, entity_kwarg_val in entity_kwargs.items():
+                other_entity = _REGISTRY[entity_kwarg_name](data_root=self._data_root)
+                other_profile = other_entity.schema_profile
+                other_static = other_entity._resolve(other_entity.static_path)
+
+                other_lf = pl.scan_parquet(other_static)
+                match_expr = pl.lit(False)
+                other_schema = cached_read_schema(
+                    other_static, other_entity._storage_options
                 )
-                raise ValueError(
-                    f"BaseEntity.where: No rows matched {entity_kwarg_name}={entity_kwarg_val!r} "
-                    f"in {other_entity.static_path!r}."
+                for col in other_entity.key_cols + list(
+                    other_profile.extra_static_cols
+                ):
+                    if col in other_schema:
+                        match_expr = match_expr | (pl.col(col) == entity_kwarg_val)
+                matched = (
+                    other_lf.filter(match_expr)
+                    .select([other_profile.geometry_col])
+                    .collect()
                 )
 
-            raw_geoms = matched[other_profile.geometry_col].to_list()
-            if other_profile.geometry_type == "wkb":
-                geoms = [swkb.loads(v) for v in raw_geoms]
+                if matched.is_empty():
+                    logger.error(
+                        "BaseEntity.where failed: No rows matched {}={!r} in {}",
+                        entity_kwarg_name,
+                        entity_kwarg_val,
+                        other_entity.static_path,
+                    )
+                    raise ValueError(
+                        f"BaseEntity.where: No rows matched {entity_kwarg_name}={entity_kwarg_val!r} "
+                        f"in {other_entity.static_path!r}."
+                    )
+
+                raw_geoms = matched[other_profile.geometry_col].to_list()
+                if other_profile.geometry_type == "wkb":
+                    geoms = [swkb.loads(v) for v in raw_geoms]
+                else:
+                    geoms = [swkt.loads(v) for v in raw_geoms]
+                lookup_geom = sops.unary_union(geoms) if len(geoms) > 1 else geoms[0]
+                lookup_geoms.append(lookup_geom)
+
+            candidates = self._index
+            for geom in lookup_geoms:
+                candidates = bbox_intersects_geometry(candidates, geom)
+
+            if candidates.is_empty():
+                keys = candidates.select(self.key_cols)
             else:
-                import shapely.wkt as swkt
-
-                geoms = [swkt.loads(v) for v in raw_geoms]
-            lookup_geom = sops.unary_union(geoms) if len(geoms) > 1 else geoms[0]
-
-            # Spatial filter: narrow keys to those whose centroid is within the geometry.
-            from core_lens.utils.spatial import (
-                bbox_intersects_geometry,
-                exact_spatial_filter,
-            )
-
-            current_keys = self._index.join(keys, on=self.key_cols, how="inner")
-            candidates = bbox_intersects_geometry(current_keys, lookup_geom)
-            keys = exact_spatial_filter(
-                candidates=candidates,
-                static_path=static,
-                key_cols=self.key_cols,
-                geometry_col=self.schema_profile.geometry_col,
-                geometry_type=self.schema_profile.geometry_type,
-                aoi_geometry=lookup_geom,
-                relationship="centroid",
-            )
+                lf = lf.select(self.key_cols + [self.schema_profile.geometry_col]).join(
+                    candidates.select(self.key_cols).lazy(),
+                    on=self.key_cols,
+                    how="semi",
+                )
+                df = lf.collect()
+
+                if df.is_empty():
+                    keys = df.select(self.key_cols)
+                else:
+                    geom_array = df[self.schema_profile.geometry_col].to_numpy()
+                    if self.schema_profile.geometry_type == "wkb":
+                        decoded_geoms = shapely.from_wkb(geom_array)
+                    else:
+                        decoded_geoms = shapely.from_wkt(geom_array)
+
+                    centroids = shapely.centroid(decoded_geoms)
+                    mask = np.ones(len(centroids), dtype=bool)
+                    for geom in lookup_geoms:
+                        mask = mask & shapely.contains(geom, centroids)
+
+                    keys = df.filter(mask).select(self.key_cols)
 
         entity_name = _entity_name(type(self))
         return View(keys=keys, entity=self, entity_name=entity_name)

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/src/core_lens/base/namespaces/plot.py

@@ -291,7 +291,7 @@ class PlotNamespace:
         if subplot_col is not None:
             extra.append(subplot_col)
 
-        df = res.data
+        df = res.df()
 
         if subplot_col is not None:
             # Render most-recent unique value of subplot_on only.

{core_lens-0.1.dev142 → core_lens-0.1.dev147}/src/core_lens/base/namespaces/stats.py

@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING, Any, cast
 import numpy as np
 import polars as pl
 
-from core_lens.utils.polars_utils import collect_lf
+from core_lens.utils.polars_utils import collect_lf, cached_read_schema
 
 if TYPE_CHECKING:
     from core_lens.base.result import Result
@@ -164,7 +164,7 @@ class StatsNamespace:
         return [c for c in df.columns if df[c].dtype.is_numeric()]
 
     def _year_col(self) -> str | None:
-        if "year" in self._r.data.columns:
+        if "year" in self._r.df().columns:
             return "year"
         profile = self._r.entity.schema_profile
         return profile.annual_time_col
@@ -190,7 +190,7 @@ class StatsNamespace:
             ValueError: If ``by`` is not ``\"column\"`` or ``\"entity\"``.
 
         """
-        df = self._r.data
+        df = self._r.df()
         cols = columns if columns is not None else self._numeric_cols(df)
 
         if by == "column":
@@ -261,7 +261,7 @@ class StatsNamespace:
 
         import scipy.stats as sp
 
-        df = self._r.data
+        df = self._r.df()
         n_obs = len(df)
         rows: list[dict[str, Any]] = []
 
@@ -327,7 +327,7 @@ class StatsNamespace:
         """
         import scipy.stats as sp
 
-        df = self._r.data
+        df = self._r.df()
         all_vals = df[column].drop_nulls().to_numpy().astype(float)
 
         # auto-select
@@ -480,7 +480,7 @@ class StatsNamespace:
 
         import scipy.stats as sp
 
-        df = self._r.data
+        df = self._r.df()
         key = self._r.key_cols[0]
         year_col = self._year_col()
         if year_col is None:
@@ -580,7 +580,7 @@ class StatsNamespace:
             ValueError: If ``mode``, ``method``, or observation count invalid.
 
         """
-        df = self._r.data
+        df = self._r.df()
         key = self._r.key_cols[0]
 
         if mode == "cross_sectional":
@@ -856,7 +856,7 @@ class StatsNamespace:
                 f"Valid options: {[e.name for e in SimilarityMethod]}."
             )
 
-        df = self._r.data
+        df = self._r.df()
         key = self._r.key_cols[0]
 
         # --- Build feature DataFrame ------------------------------------------
@@ -903,11 +903,13 @@ class StatsNamespace:
             except FileNotFoundError:
                 continue
 
-            schema = pl.read_parquet_schema(abs_path)
+            schema = cached_read_schema(abs_path, entity._storage_options)
             if col_name not in schema:
                 continue  # column doesn't exist in this file
 
-            col_lf = pl.scan_parquet(abs_path)
+            col_lf = pl.scan_parquet(
+                abs_path, storage_options=entity._storage_options or None
+            )
 
             # Apply year filter.
             if "year" in filter_dict: