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

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

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

{core_lens-0.1.dev129 → 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.dev129 → core_lens-0.1.dev132}/src/core_lens/base/result.py

@@ -100,10 +100,12 @@ class Result:
                 "Call .with_geometry() first to join the static geometry column before extracting GeoDataFrame."
             )
         import geopandas as gpd
-        import shapely.wkb as wkb
+        import shapely
 
         geometry_col = self.entity.geometry_col
-        geometries = [wkb.loads(b) for b in self.data[geometry_col].to_list()]
+        # Vectorised C-level decode — shapely.from_wkb operates on the whole
+        # numpy array at once, avoiding a Python-loop per row.
+        geometries = shapely.from_wkb(self.data[geometry_col].to_numpy())
         geo_series = gpd.GeoSeries(geometries, crs="EPSG:4326")
         return gpd.GeoDataFrame(
             self.data.drop(geometry_col).to_pandas(),

{core_lens-0.1.dev129 → 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.dev129 → core_lens-0.1.dev132}/src/core_lens/export/formats.py

@@ -162,12 +162,17 @@ def geoparquet(result: "Result", path: str | pathlib.Path, **kwargs: Any) -> Non
 def geojson(result: "Result", path: str | pathlib.Path, **kwargs: Any) -> None:
     """Export the result data to a GeoJSON file.
 
-    This function uses DuckDB to write the data frame with spatial extensions.
+    This function uses GeoPandas to write the data frame.  It prefers the
+    ``pyogrio`` engine (faster, C-backed) when available and falls back to
+    ``fiona`` automatically.  The ``engine`` kwarg can override this:
+    ``engine="fiona"`` or ``engine="pyogrio"``.
 
     Args:
         result (Result): The Result object to export.
         path (str | pathlib.Path): Destination path for the GeoJSON file.
-        **kwargs (Any): Additional options to pass to DuckDB's COPY statement.
+        **kwargs (Any): Additional options forwarded to
+            ``GeoDataFrame.to_file()`` (e.g. ``driver="GeoJSON"``,
+            ``engine="pyogrio"``).
 
     Example:
         >>> from core_lens.export import geojson
@@ -182,37 +187,20 @@ def geojson(result: "Result", path: str | pathlib.Path, **kwargs: Any) -> None:
             "Call .with_geometry() first to join the static geometry column before exporting to geojson."
         )
 
-    df = result.df()
-    geom_col = result.entity.geometry_col
-
-    cols = []
-    for c in df.columns:
-        if c == geom_col:
-            cols.append(f'ST_GeomFromWKB("{c}") AS "{c}"')
-        else:
-            cols.append(f'"{c}"')
-
-    select_clause = ", ".join(cols)
-
-    conn = _get_duckdb_conn()
+    gdf = result.gdf()
 
-    path_str = str(path).replace("'", "''")
+    # Resolve write engine: prefer pyogrio (C-backed, no GDAL Python overhead),
+    # fall back to fiona if not installed.
+    engine = kwargs.pop("engine", None)
+    if engine is None:
+        try:
+            import pyogrio as _  # type: ignore[import-untyped]  # noqa: F401
 
-    options = ["FORMAT GDAL", "DRIVER 'GeoJSON'"]
-    for k, v in kwargs.items():
-        if isinstance(v, bool):
-            options.append(f"{k.upper()} {'TRUE' if v else 'FALSE'}")
-        elif isinstance(v, str):
-            options.append(f"{k.upper()} '{v}'")
-        else:
-            options.append(f"{k.upper()} {v}")
+            engine = "pyogrio"
+        except ModuleNotFoundError:
+            engine = "fiona"
 
-    options_str = ", ".join(options)
+    # Always write as GeoJSON unless the caller overrides driver.
+    kwargs.setdefault("driver", "GeoJSON")
 
-    query = f"""
-    COPY (
-        SELECT {select_clause}
-        FROM df
-    ) TO '{path_str}' ({options_str});
-    """
-    conn.execute(query)
+    gdf.to_file(path, engine=engine, **kwargs)

{core_lens-0.1.dev129 → 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.dev129 → 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.dev129 → 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
 

{core_lens-0.1.dev129 → core_lens-0.1.dev132}/tests/unit/test_export.py

@@ -152,8 +152,10 @@ def test_geoparquet_options_partition(
 
 
 def test_geojson_options(sample_result: Result, tmp_path: pathlib.Path) -> None:
+    """Unknown kwargs are forwarded to the write engine; unrecognised ones raise
+    ValueError (pyogrio) rather than silently being ignored.  The test simply
+    verifies the call path is exercised without an unexpected exception type."""
     result_with_geom = sample_result.with_geometry()
-    import duckdb
 
     out_path = tmp_path / "out_opts.json"
     try:
@@ -165,5 +167,6 @@ def test_geojson_options(sample_result: Result, tmp_path: pathlib.Path) -> None:
             flag=False,
             number=10,
         )
-    except duckdb.BinderException:
+    except ValueError:
+        # pyogrio rejects unrecognised driver options — that's expected.
         pass