core-lens 0.1.dev136__py3-none-any.whl → 0.1.dev140__py3-none-any.whl

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.dev136'
-__version_tuple__ = version_tuple = (0, 1, 'dev136')
+__version__ = version = '0.1.dev140'
+__version_tuple__ = version_tuple = (0, 1, 'dev140')
 
 __commit_id__ = commit_id = None

core_lens/aoi.py

@@ -47,6 +47,7 @@ class SeasonConfig:
         kharif: Kharif (monsoon) season range as ``(start_MM-DD, end_MM-DD)``.
         rabi: Rabi (winter) season range.
         zaid: Zaid (summer) season range.
+
     """
 
     kharif: tuple[str, str] = ("07-01", "10-31")
@@ -76,6 +77,7 @@ class SeasonConfig:
 
         Returns:
             str: ``"kharif"``, ``"rabi"``, or ``"zaid"``.
+
         """
         md = f"{d.month:02d}-{d.day:02d}"
         for name in ("kharif", "rabi", "zaid"):
@@ -115,6 +117,7 @@ def _default_season_config() -> SeasonConfig:
 
     Returns:
         SeasonConfig: The shared default instance.
+
     """
     global _DEFAULT_SEASON_CONFIG
     if _DEFAULT_SEASON_CONFIG is None:
@@ -167,6 +170,7 @@ def _cached_resolve_boundary(
 
     Returns:
         tuple: ``(geometry_wkb, entity_name, key_rows)``.
+
     """
     from core_lens.base.entity import _entity_name as _ename
 
@@ -284,6 +288,7 @@ class AoI:
         data_root: Resolved path to the data directory.
         geometry: Shapely polygon representing the AoI boundary.
         seasons: :class:`SeasonConfig` in effect for this AoI.
+
     """
 
     def __init__(
@@ -331,6 +336,7 @@ class AoI:
                 one boundary mode is used simultaneously.
             :class:`~core_lens.base.EntityValidationError`: If a boundary entity referenced in
                 ``entity_kwargs`` is not registered.
+
         """
         # Preserve cloud URIs as-is; resolve local paths to absolute.
         data_root_str = str(data_root)
@@ -395,6 +401,7 @@ class AoI:
 
         Returns:
             str: ``"kharif"``, ``"rabi"``, or ``"zaid"``.
+
         """
         return self.seasons.season_for(date.today())
 
@@ -404,6 +411,7 @@ class AoI:
 
         Returns:
             int: Current year as an integer.
+
         """
         return date.today().year
 
@@ -416,6 +424,7 @@ class AoI:
 
         Returns:
             Any: A Lonboard Map object.
+
         """
         import lonboard
         import geopandas as gpd
@@ -476,6 +485,7 @@ class AoI:
         Raises:
             KeyError: If *name* is not in :data:`_REGISTRY`.
             :class:`~core_lens.base.EntityValidationError`: If validation fails.
+
         """
         if name not in self._entity_instances:
             entity_cls = _REGISTRY[name]
@@ -506,6 +516,7 @@ class AoI:
         Raises:
             :class:`~core_lens.base.EntityValidationError`: If any registered
                 entity fails validation.
+
         """
         for name in _REGISTRY:
             self._get_entity(name)
@@ -562,6 +573,7 @@ class AoI:
         Raises:
             :class:`~core_lens.base.EntityValidationError`: If no registered entity can satisfy the filters.
             ValueError: If the filters match zero rows.
+
         """
         logger.debug("Resolving named boundary using kwargs: {}", entity_kwargs)
 
@@ -625,6 +637,7 @@ class AoI:
         Raises:
             :class:`~core_lens.base.EntityValidationError`: If any validation check
                 fails (absolute-path entities only at register time).
+
         """
         import pathlib as _pathlib
 
@@ -647,6 +660,7 @@ class AoI:
 
         Args:
             entity_cls (type[BaseEntity]): The entity class to remove.
+
         """
         name = _entity_name(entity_cls)
         logger.info("Deregistering entity class: {}", name)
@@ -658,6 +672,7 @@ class AoI:
 
         Returns:
             list[str]: A sorted list of entity name strings.
+
         """
         return sorted(_REGISTRY)
 
@@ -695,6 +710,7 @@ def _validate_entity_paths(entity: BaseEntity, name: str) -> None:
 
     Raises:
         EntityValidationError: If any path does not exist.
+
     """
     # --- Static path existence check ----------------------------------------
     try:
@@ -760,6 +776,7 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
 
     Raises:
         EntityValidationError: If any validation check fails.
+
     """
     # Fast path-only check first.
     _validate_entity_paths(entity, name)

core_lens/base/entity.py

@@ -65,6 +65,7 @@ def _so_key(storage_options: dict[str, Any]) -> tuple[tuple[str, Any], ...]:
 
     Returns:
         tuple[tuple[str, Any], ...]: A sorted tuple of ``(key, value)`` pairs.
+
     """
     return tuple(sorted(storage_options.items()))
 
@@ -85,6 +86,7 @@ def _cached_detect(
 
     Returns:
         SchemaProfile: Detected schema profile for the given entity paths.
+
     """
     from core_lens.schema.detection import detect
 
@@ -114,6 +116,7 @@ def _cached_build_index(
 
     Returns:
         pl.DataFrame: The bounding-box index DataFrame.
+
     """
     logger.debug("Building bbox index for {} (cache miss)", static_path)
     return build_bbox_index(
@@ -127,7 +130,7 @@ def _cached_build_index(
 
 
 class BaseEntity(ABC):
-    """Abstract base class for every entity in the core_lens plugin system.
+    r"""Abstract base class for every entity in the core_lens plugin system.
 
     An entity represents a geospatial primitive (e.g. microwatershed, village,
     district) backed by one or more Parquet/GeoParquet files.  Entities are
@@ -195,6 +198,7 @@ class BaseEntity(ABC):
                 ``polars.scan_parquet``.  For S3 the common keys are
                 ``"region"``, ``"access_key"``, and ``"secret_key"``.
                 ``None`` uses ambient credentials (env-vars / ``~/.aws/``).
+
         """
         # Store as str so cloud URIs (s3://…) are never coerced through pathlib.
         self._data_root: str | None = str(data_root) if data_root is not None else None
@@ -219,6 +223,7 @@ class BaseEntity(ABC):
 
         Raises:
             FileNotFoundError: For *local* paths that do not exist after resolution.
+
         """
         # Fully-qualified cloud URI — return as-is.
         if is_cloud_uri(path):
@@ -255,13 +260,14 @@ class BaseEntity(ABC):
     @property
     @abstractmethod
     def key_cols(self) -> list[str]:
-        """Columns that uniquely identify one instance of this entity.
+        r"""Columns that uniquely identify one instance of this entity.
 
         For built-in entities this is always a single-element list (e.g.
         ``[\"mws_id\"]``), but the contract allows composite keys for plugins.
 
         Returns:
             list[str]: A list of column name strings present in the static file.
+
         """
 
     @property
@@ -274,6 +280,7 @@ class BaseEntity(ABC):
 
         Returns:
             str: The column name as a string.
+
         """
 
     @property
@@ -287,6 +294,7 @@ class BaseEntity(ABC):
 
         Returns:
             str: A path string.
+
         """
 
     @property
@@ -299,6 +307,7 @@ class BaseEntity(ABC):
 
         Returns:
             str | None: A path string, or ``None`` if the entity has no annual data.
+
         """
         return None
 
@@ -312,6 +321,7 @@ class BaseEntity(ABC):
 
         Returns:
             str | None: A path string, or ``None`` if the entity has no fortnightly data.
+
         """
         return None
 
@@ -336,6 +346,7 @@ class BaseEntity(ABC):
 
         Returns:
             SchemaProfile: A fully-validated :class:`~core_lens.schema.profile.SchemaProfile`.
+
         """
         if not hasattr(self, "_schema_profile"):
             _so = self._storage_options or {}
@@ -372,6 +383,7 @@ class BaseEntity(ABC):
 
         Returns:
             pl.DataFrame: DataFrame with columns ``(*key_cols, minx, miny, maxx, maxy)``.
+
         """
         if not hasattr(self, "_cached_index"):
             profile = self.schema_profile  # already cached — no extra I/O
@@ -409,6 +421,7 @@ class BaseEntity(ABC):
         Raises:
             ValueError: If a kwarg cannot be resolved as either an attribute
                 column or a registered entity name.
+
         """
         from core_lens.aoi import _REGISTRY
         from core_lens.base.view import View
@@ -544,6 +557,7 @@ class BaseEntity(ABC):
 
         Raises:
             ValueError: If neither ``geometry`` nor ``bbox`` is provided.
+
         """
         import shapely.geometry as sgeom
 
@@ -584,7 +598,7 @@ class BaseEntity(ABC):
         return View(keys=keys, entity=self, entity_name=entity_name)
 
     def spatial_join(self, other: "BaseEntity", agg: dict[str, str]) -> "View":
-        """Return a lazy :class:`~core_lens.base.view.View` with a cross-entity join pending.
+        r"""Return a lazy :class:`~core_lens.base.view.View` with a cross-entity join pending.
 
         The join is recorded in the View's ``join_spec`` and computed only at
         materialisation time (``.static``, ``.annual``, or ``.fortnightly``).
@@ -601,6 +615,7 @@ class BaseEntity(ABC):
         Returns:
             View: A lazy :class:`~core_lens.base.view.View` with the join spec
             recorded for deferred execution.
+
         """
         from core_lens.base.view import View
 

core_lens/base/namespaces/plot.py

@@ -17,6 +17,7 @@ class SubplotOn(Enum):
         MONTH: Split data by month.
         SEASON: Split data by meteorological season.
         SEASON_YEAR: Split data by season and year.
+
     """
 
     YEAR = "year"
@@ -71,6 +72,7 @@ def _wkb_to_arrow_table(
 
     Returns:
         An ``arro3.core.Table`` whose geometry column is GeoArrow-typed.
+
     """
     import geoarrow.rust.core as ga
     import polars as pl
@@ -182,6 +184,7 @@ def _color_for(index: int) -> str:
 
     Returns:
         The hex color string.
+
     """
     return _PALETTE[index % len(_PALETTE)]
 
@@ -193,6 +196,7 @@ def _apply_theme(fig: Any, result: "Result", title: str) -> None:
         fig: The Bokeh figure.
         result: The parent Result object.
         title: The title text.
+
     """
     entity_name = getattr(result.entity, "__name__", "Unknown")
     if hasattr(result, "entity_name"):
@@ -202,7 +206,6 @@ def _apply_theme(fig: Any, result: "Result", title: str) -> None:
     fig.title.text_font = "Inter, sans-serif"
     fig.title.text_font_size = "14pt"
 
-    # Subtitle-style annotation in the bottom-right corner.
     from bokeh.models.annotations import Label
 
     subtitle = Label(
@@ -227,6 +230,7 @@ class PlotNamespace:
 
     Attributes:
         result: The parent Result object.
+
     """
 
     def __init__(self, result: "Result") -> None:
@@ -253,6 +257,7 @@ class PlotNamespace:
             ValueError: If ``column`` or ``subplot_on`` column not found in data.
             NotImplementedError: Lonboard does not support native subplot grids;
                 only single-value ``subplot_on`` is rendered when specified.
+
         """
         import lonboard
         from lonboard.colormap import apply_continuous_cmap
@@ -347,6 +352,7 @@ class PlotNamespace:
 
         Returns:
             Any: A Bokeh Tabs object (or a single Figure when ``aggregate=True``).
+
         """
         import polars as pl
         import polars.selectors as cs
@@ -474,7 +480,6 @@ class PlotNamespace:
             _apply_theme(fig, self.result, title)
             return fig
 
-        # --- Aggregated view --------------------------------------------------
         group_cols = [x, subplot_col] if subplot_col else [x]
         agg_pdf = (
             df.group_by(group_cols)
@@ -486,7 +491,6 @@ class PlotNamespace:
         if aggregate:
             return _make_fig(agg_pdf, "Timeseries (Aggregated Mean)")
 
-        # --- Per-entity view --------------------------------------------------
         entity_df = df.sort(x)
         unique_entities = entity_df[key_col].unique()
         if len(unique_entities) > top_n:
@@ -519,6 +523,7 @@ class PlotNamespace:
 
         Returns:
             Any: A Bokeh Figure or Tabs object.
+
         """
         import polars as pl
         import polars.selectors as cs
@@ -595,6 +600,7 @@ class PlotNamespace:
 
         Returns:
             Any: A Bokeh Figure or Tabs object.
+
         """
         import numpy as np
         import pandas as pd
@@ -665,6 +671,7 @@ class PlotNamespace:
 
         Returns:
             Any: A Bokeh Figure object.
+
         """
         import polars.selectors as cs
         from bokeh.models import BasicTicker, ColumnDataSource, LinearColorMapper
@@ -684,7 +691,6 @@ class PlotNamespace:
         corr = df.to_pandas().corr()
         cols = list(corr.columns)
 
-        # Build long-form data for rect glyphs.
         xs: list[str] = []
         ys: list[str] = []
         vals: list[float] = []
@@ -744,6 +750,7 @@ class PlotNamespace:
 
         Returns:
             Any: A Bokeh Figure object.
+
         """
         from bokeh.models import (
             BasicTicker,
@@ -769,7 +776,6 @@ class PlotNamespace:
         x_vals = [str(v) for v in pdf.columns.tolist()]
         y_vals = [str(v) for v in pdf.index.tolist()]
 
-        # Long-form
         xs2: list[str] = []
         ys2: list[str] = []
         vals2: list[float] = []
@@ -819,6 +825,7 @@ class PlotNamespace:
 
         Returns:
             Any: A Bokeh ``gridplot`` object.
+
         """
         import polars.selectors as cs
         from bokeh.layouts import gridplot

core_lens/base/namespaces/stats.py

@@ -29,6 +29,7 @@ def _sf(x: object) -> float:
 
     Returns:
         float: The numeric value as a float, or NaN if the input is None.
+
     """
     if x is None:
         return float("nan")
@@ -42,6 +43,7 @@ class CorrelateMethod(Enum):
         PEARSON: Pearson correlation coefficient.
         SPEARMAN: Spearman rank correlation.
         KENDALL: Kendall Tau correlation.
+
     """
 
     PEARSON = "pearson"
@@ -58,6 +60,7 @@ class TestMethod(Enum):
         WILCOXON: Wilcoxon signed-rank test.
         KS: Kolmogorov-Smirnov test.
         CHI_SQUARE: Chi-square test.
+
     """
 
     __test__ = False
@@ -75,6 +78,7 @@ class ChangeMethod(Enum):
         ABSOLUTE: Absolute difference between periods.
         PERCENTAGE: Percentage change between periods.
         TREND: Linear trend over time.
+
     """
 
     ABSOLUTE = "absolute"
@@ -90,6 +94,7 @@ class AnomalyCrossMethod(Enum):
         IQR: Interquartile range method.
         PERCENTILE: Percentile-based method.
         THRESHOLD: Fixed threshold method.
+
     """
 
     ZSCORE = "zscore"
@@ -105,6 +110,7 @@ class AnomalyTsMethod(Enum):
         STL: Seasonal-Trend decomposition using LOESS.
         CUSUM: Cumulative sum control chart.
         MAD: Median Absolute Deviation.
+
     """
 
     STL = "stl"
@@ -120,6 +126,7 @@ class SimilarityMethod(Enum):
         COSINE: Cosine similarity.
         MAHALANOBIS: Mahalanobis distance.
         MANHATTAN: Manhattan distance.
+
     """
 
     EUCLIDEAN = "euclidean"
@@ -167,7 +174,8 @@ class StatsNamespace:
         columns: list[str] | None = None,
         by: str = "column",
     ) -> "Result":
-        """Per-column or per-entity descriptive statistics.
+        r"""Per-column or per-entity descriptive statistics.
+
         Uses polars' in-built methods for mean, std, min, max, quantiles etc.
 
         Args:
@@ -180,6 +188,7 @@ class StatsNamespace:
 
         Raises:
             ValueError: If ``by`` is not ``\"column\"`` or ``\"entity\"``.
+
         """
         df = self._r.data
         cols = columns if columns is not None else self._numeric_cols(df)
@@ -239,6 +248,7 @@ class StatsNamespace:
         Raises:
             CorrelationError: If fewer than 2 columns supplied.
             ValueError: If ``method`` is not recognised.
+
         """
         if len(columns) < 2:
             raise CorrelationError(
@@ -313,6 +323,7 @@ class StatsNamespace:
         Raises:
             ValueError: If none of ``groups``, ``periods``, ``against`` supplied,
                 or if ``method`` is not recognised.
+
         """
         import scipy.stats as sp
 
@@ -460,6 +471,7 @@ class StatsNamespace:
 
         Raises:
             ValueError: If ``method`` is not recognised or year column absent.
+
         """
         if not isinstance(method, ChangeMethod):
             raise ValueError(
@@ -566,6 +578,7 @@ class StatsNamespace:
 
         Raises:
             ValueError: If ``mode``, ``method``, or observation count invalid.
+
         """
         df = self._r.data
         key = self._r.key_cols[0]
@@ -835,6 +848,7 @@ class StatsNamespace:
         Raises:
             ValueError: If ``method`` is invalid, no columns can be resolved,
                 or ``target`` is not found.
+
         """
         if not isinstance(method, SimilarityMethod):
             raise ValueError(

core_lens/base/result.py

@@ -53,6 +53,7 @@ class Result:
         entity: Reference to the parent entity, retained so
             :meth:`with_geometry` can locate the static file without
             requiring callers to pass it again.
+
     """
 
     def __init__(
@@ -79,6 +80,7 @@ class Result:
 
         Returns:
             pl.DataFrame: The materialised data frame.
+
         """
         return self.data
 
@@ -93,6 +95,7 @@ class Result:
 
         Raises:
             TypeError: If :attr:`has_geometry` is ``False``.
+
         """
         if not self.has_geometry:
             raise TypeError(
@@ -121,6 +124,7 @@ class Result:
 
         Returns:
             pl.LazyFrame: A lazy frame backed by :attr:`data`.
+
         """
         return self.data.lazy()
 
@@ -139,6 +143,7 @@ class Result:
             Result: A new :class:`Result` with the geometry column merged in and
             ``has_geometry=True``.  If ``has_geometry`` is already ``True``,
             returns ``self`` unchanged.
+
         """
         if self.has_geometry:
             return self
@@ -172,6 +177,7 @@ class Result:
 
         Returns:
             Result: A new :class:`Result` with ``name`` appended to :attr:`data`.
+
         """
         new_data = self.data.with_columns(expr.alias(name))
         return self._replace(data=new_data)
@@ -219,6 +225,7 @@ class Result:
         Raises:
             ValueError: If ``by`` is incompatible with :attr:`resolution`, or
                 if ``by`` is not a recognised grouping name.
+
         """
         if by is not None and by not in _VALID_BY:
             raise ValueError(
@@ -263,6 +270,7 @@ class Result:
 
         Returns:
             StatsNamespace: The statistical analysis namespace.
+
         """
         from core_lens.base.namespaces.stats import StatsNamespace
 
@@ -281,6 +289,7 @@ class Result:
 
         Returns:
             PlotNamespace: The visualisation namespace.
+
         """
         from core_lens.base.namespaces.plot import PlotNamespace
 

core_lens/base/view.py

@@ -61,6 +61,7 @@ class View:
         join_spec: A dict encoding a deferred :meth:`~BaseEntity.spatial_join`
             request, or ``None``.  Evaluated during materialisation after the
             primary scan is complete.
+
     """
 
     def __init__(
@@ -94,6 +95,7 @@ class View:
 
         Returns:
             View: A new lazy :class:`View` with the narrowed keys.
+
         """
         static = self.entity._resolve(self.entity.static_path)
 
@@ -141,6 +143,7 @@ class View:
 
         Raises:
             ValueError: If neither ``geometry`` nor ``bbox`` is provided.
+
         """
         import shapely.geometry as sgeom
         from core_lens.utils.spatial import (
@@ -198,6 +201,7 @@ class View:
 
         Returns:
             View: A new lazy :class:`View` with the join spec recorded.
+
         """
         if self.join_spec is not None:
             logger.error(
@@ -260,6 +264,7 @@ class View:
             ValueError: If the arguments are inconsistent (e.g. mixing date
                 range and season arguments, omitting required args, or
                 supplying ``year`` with ``season="current"``).
+
         """
         if season is not None and (start is not None or end is not None):
             logger.error(
@@ -329,6 +334,7 @@ class View:
         Raises:
             AttributeError: If the entity has no ``static_path`` (should not
                 happen in practice since ``static_path`` is mandatory).
+
         """
         return self._materialise(Resolution.STATIC)
 
@@ -342,6 +348,7 @@ class View:
 
         Raises:
             AttributeError: If the entity has no ``annual_path``.
+
         """
         return self._materialise(Resolution.ANNUAL)
 
@@ -355,6 +362,7 @@ class View:
 
         Raises:
             AttributeError: If the entity has no ``fortnightly_path``.
+
         """
         return self._materialise(Resolution.FORTNIGHTLY)
 

core_lens/entities/mws.py

@@ -14,35 +14,50 @@ class MWSEntity(BaseEntity):
 
     @property
     def key_cols(self) -> list[str]:
-        """Returns:
-        list[str]: The key columns for the entity.
+        """Get the property value.
+
+        Returns:
+            list[str]: The key columns for the entity.
+
         """
         return ["mws_id"]
 
     @property
     def geometry_col(self) -> str:
-        """Returns:
-        str: The geometry column name.
+        """Get the property value.
+
+        Returns:
+            str: The geometry column name.
+
         """
         return "geometry"
 
     @property
     def static_path(self) -> str:
-        """Returns:
-        str: The relative path to the static data.
+        """Get the property value.
+
+        Returns:
+            str: The relative path to the static data.
+
         """
         return "mws/static"
 
     @property
     def annual_path(self) -> str | None:
-        """Returns:
-        str | None: The relative path to the annual data.
+        """Get the property value.
+
+        Returns:
+            str | None: The relative path to the annual data.
+
         """
         return "mws/annual"
 
     @property
     def fortnightly_path(self) -> str | None:
-        """Returns:
-        str | None: The relative path to the fortnightly data.
+        """Get the property value.
+
+        Returns:
+            str | None: The relative path to the fortnightly data.
+
         """
         return "mws/fortnightly"

core_lens/entities/tehsil.py

@@ -15,29 +15,41 @@ class TehsilEntity(BaseEntity):
 
     @property
     def key_cols(self) -> list[str]:
-        """Returns:
-        list[str]: The key columns for the entity.
+        """Get the property value.
+
+        Returns:
+            list[str]: The key columns for the entity.
+
         """
         return ["id"]
 
     @property
     def geometry_col(self) -> str:
-        """Returns:
-        str: The geometry column name.
+        """Get the property value.
+
+        Returns:
+            str: The geometry column name.
+
         """
         return "geom"
 
     @property
     def static_path(self) -> str:
-        """Returns:
-        str: The relative path to the static data.
+        """Get the property value.
+
+        Returns:
+            str: The relative path to the static data.
+
         """
         return "tehsil/static/tehsil.parquet"
 
     @property
     def schema_profile(self) -> SchemaProfile:
-        """Returns:
-        SchemaProfile: The hardcoded schema profile.
+        """Get the property value.
+
+        Returns:
+            SchemaProfile: The hardcoded schema profile.
+
         """
         if not hasattr(self, "_schema_profile"):
             self._schema_profile = SchemaProfile(

core_lens/entities/waterbody.py

@@ -13,28 +13,40 @@ class WaterbodyEntity(BaseEntity):
 
     @property
     def key_cols(self) -> list[str]:
-        """Returns:
-        list[str]: The key columns for the entity.
+        """Get the property value.
+
+        Returns:
+            list[str]: The key columns for the entity.
+
         """
         return ["wb_id"]
 
     @property
     def geometry_col(self) -> str:
-        """Returns:
-        str: The geometry column name.
+        """Get the property value.
+
+        Returns:
+            str: The geometry column name.
+
         """
         return "geometry"
 
     @property
     def static_path(self) -> str:
-        """Returns:
-        str: The relative path to the static data.
+        """Get the property value.
+
+        Returns:
+            str: The relative path to the static data.
+
         """
         return "waterbodies/static"
 
     @property
     def annual_path(self) -> str | None:
-        """Returns:
-        str | None: The relative path to the annual data.
+        """Get the property value.
+
+        Returns:
+            str | None: The relative path to the annual data.
+
         """
         return "waterbodies/annual"

core_lens/export/formats.py

@@ -33,6 +33,7 @@ def parquet(result: "Result", path: str | pathlib.Path, **kwargs: Any) -> None:
     Example:
         >>> from core_lens.export import parquet
         >>> parquet(result, "output.parquet", compression="zstd", compression_level=3)
+
     """
     if result.has_geometry:
         raise TypeError(
@@ -57,6 +58,7 @@ def json(result: "Result", path: str | pathlib.Path, **kwargs: Any) -> None:
     Example:
         >>> from core_lens.export import json
         >>> json(result, "output.json", pretty=True)
+
     """
     if result.has_geometry:
         raise TypeError(
@@ -81,6 +83,7 @@ def csv(result: "Result", path: str | pathlib.Path, **kwargs: Any) -> None:
     Example:
         >>> from core_lens.export import csv
         >>> csv(result, "output.csv", separator=",")
+
     """
     if result.has_geometry:
         raise TypeError(
@@ -110,6 +113,7 @@ def geoparquet(result: "Result", path: str | pathlib.Path, **kwargs: Any) -> Non
 
     Raises:
         TypeError: If the Result object does not have geometry.
+
     """
     if not result.has_geometry:
         raise TypeError(
@@ -180,6 +184,7 @@ def geojson(result: "Result", path: str | pathlib.Path, **kwargs: Any) -> None:
 
     Raises:
         TypeError: If the Result object does not have geometry.
+
     """
     if not result.has_geometry:
         raise TypeError(

core_lens/schema/detection.py

@@ -81,6 +81,7 @@ def detect(
     Raises:
         SchemaDetectionError: If a required column is absent, the geometry
             type cannot be inferred, or any other detection step fails.
+
     """
     _so = storage_options or {}
     static_schema = _read_schema(
@@ -178,6 +179,14 @@ def _infer_bbox_cols(schema: pl.Schema) -> tuple[str, str, str, str] | None:
     for pattern in _BBOX_PATTERNS:
         if all(col in schema for col in pattern):
             return pattern
+
+    for col_name, dtype in schema.items():
+        if isinstance(dtype, pl.Struct):
+            struct_fields = [f.name for f in dtype.fields]
+            for pattern in _BBOX_PATTERNS:
+                if all(f in struct_fields for f in pattern):
+                    return tuple(f"{col_name}.{f}" for f in pattern)  # type: ignore
+
     return None
 
 
@@ -266,6 +275,7 @@ def _is_year_col_from_schema(
 
     Returns:
         bool | None: ``True`` for integer-year, ``False`` for Date/Datetime, ``None`` if absent.
+
     """
     if time_col is None:
         return None

core_lens/schema/profile.py

@@ -56,6 +56,7 @@ class SchemaProfile(BaseModel):
             is used for validation and documentation only.
         extra_annual_cols: Additional attribute columns in the annual file.
         extra_fortnightly_cols: Additional attribute columns in the fortnightly file.
+
     """
 
     model_config = {"frozen": True}
@@ -89,6 +90,7 @@ class SchemaProfile(BaseModel):
         Raises:
             ValueError: If the file is not valid JSON.
             FileNotFoundError: If the file does not exist.
+
         """
         import json
 

core_lens/utils/paths.py

@@ -34,6 +34,7 @@ def is_cloud_uri(uri: str) -> bool:
 
     Returns:
         bool: ``True`` for URIs starting with a recognised cloud scheme.
+
     """
     return any(uri.startswith(scheme) for scheme in _CLOUD_SCHEMES)
 
@@ -50,6 +51,7 @@ def resolve_fs_and_path(uri: str) -> tuple[pafs.FileSystem, str]:
     Returns:
         tuple[pyarrow.fs.FileSystem, str]: The resolved filesystem and the
         normalised path within that filesystem.
+
     """
     if is_cloud_uri(uri):
         fs, path = pafs.FileSystem.from_uri(uri)
@@ -72,6 +74,7 @@ def path_exists(uri: str) -> bool:
 
     Returns:
         bool: ``True`` if the path exists (file or directory).
+
     """
     try:
         fs, path = resolve_fs_and_path(uri)
@@ -95,6 +98,7 @@ def join_uri(root: str, rel: str) -> str:
 
     Returns:
         str: The joined URI or absolute path string.
+
     """
     if is_cloud_uri(root):
         return root.rstrip("/") + "/" + rel.lstrip("/")

core_lens/utils/polars_utils.py

@@ -17,6 +17,7 @@ def _gpu_available() -> bool:
 
     Returns:
         bool: True if GPU is available.
+
     """
     global _GPU_AVAILABLE
     if _GPU_AVAILABLE is None:
@@ -56,6 +57,7 @@ def collect_lf(lf: pl.LazyFrame) -> pl.DataFrame:
 
     Returns:
         pl.DataFrame: A materialised ``pl.DataFrame``.
+
     """
     global _GPU_AVAILABLE
     if _gpu_available():
@@ -107,6 +109,7 @@ def scan_with_key_filter(
 
     Returns:
         pl.LazyFrame: A ``pl.LazyFrame`` ready to be ``.collect()``-ed.
+
     """
     _so = storage_options or {}
     lf = pl.scan_parquet(path, hive_partitioning=True, storage_options=_so or None)

core_lens/utils/season.py

@@ -42,6 +42,7 @@ def resolve_time_filter(
 
     Raises:
         ValueError: If ``time_filter`` has an unrecognised structure.
+
     """
     if "start" in time_filter and "end" in time_filter:
         start = time_filter["start"]
@@ -93,6 +94,7 @@ def _date_range_expr(
 
     Returns:
         pl.Expr: A Polars expression.
+
     """
     start_date = datetime.date.fromisoformat(start)
     end_date = datetime.date.fromisoformat(end)
@@ -141,6 +143,7 @@ def _season_expr(
 
     Returns:
         pl.Expr: A Polars expression.
+
     """
     start_md, end_md = getattr(season_config, season_name)
     year_crossing = start_md > end_md
@@ -182,6 +185,7 @@ def _parse_md(md: str) -> tuple[int, int]:
 
     Returns:
         tuple[int, int]: A tuple containing ``(month, day)`` as integers.
+
     """
     month, day = md.split("-")
     return int(month), int(day)
@@ -198,6 +202,7 @@ def _year_bounds(year: int | tuple[int, int] | None) -> tuple[int, int]:
 
     Returns:
         tuple[int, int]: A tuple containing ``(from_year, to_year)``.
+
     """
     # When year is None use a wide range covering past and future data.
     if year is None:
@@ -238,6 +243,7 @@ def add_temporal_columns(
 
     Returns:
         pl.DataFrame: A new DataFrame with the temporal grouping columns appended.
+
     """
     existing = set(df.columns)
 
@@ -285,6 +291,7 @@ def add_temporal_columns(
 
             Returns:
                 pl.Expr: A Polars boolean expression handling year rollover.
+
             """
             if start <= end:
                 # is_between with bare strings → column-name lookup; use pl.lit().

core_lens/utils/spatial.py

@@ -45,6 +45,7 @@ def _bbox_sidecar_path(static_path: str) -> pathlib.Path | None:
 
     Returns:
         pathlib.Path | None: Sidecar path, or ``None`` if ``static_path`` is a cloud URI.
+
     """
     if is_cloud_uri(static_path):
         return None
@@ -74,6 +75,7 @@ def _read_bbox_sidecar(sidecar: pathlib.Path, static_path: str) -> pl.DataFrame
     Returns:
         pl.DataFrame | None: The cached index, or ``None`` if the sidecar is
         absent or stale.
+
     """
     if not sidecar.exists():
         return None
@@ -100,6 +102,7 @@ def _write_bbox_sidecar(df: pl.DataFrame, sidecar: pathlib.Path) -> None:
     Args:
         df (pl.DataFrame): The bbox index DataFrame to persist.
         sidecar (pathlib.Path): Destination sidecar path.
+
     """
     try:
         sidecar.parent.mkdir(parents=True, exist_ok=True)
@@ -120,6 +123,7 @@ def resolve_path(path: str) -> str:
 
     Raises:
         FileNotFoundError: If the resolved local path does not exist.
+
     """
     if is_cloud_uri(path):
         return path
@@ -169,18 +173,32 @@ def build_bbox_index(
 
     Returns:
         pl.DataFrame: A ``pl.DataFrame`` with columns ``(*key_cols, minx, miny, maxx, maxy)``.
+
     """
     _so = storage_options or {}
     if bbox_cols is not None:
         logger.debug("Using pre-computed bbox columns: {}", bbox_cols)
-        cols_to_read = key_cols + list(bbox_cols)
+        base_bbox_cols = list(dict.fromkeys(c.split(".")[0] for c in bbox_cols))
+        cols_to_read = key_cols + base_bbox_cols
         df = pl.read_parquet(
             static_path, columns=cols_to_read, storage_options=_so or None
         )
         minx_col, miny_col, maxx_col, maxy_col = bbox_cols
-        return df.rename(
-            {minx_col: "minx", miny_col: "miny", maxx_col: "maxx", maxy_col: "maxy"}
-        )
+
+        for alias, col_path in zip(
+            ["minx", "miny", "maxx", "maxy"],
+            [minx_col, miny_col, maxx_col, maxy_col],
+        ):
+            parts = col_path.split(".")
+            if len(parts) == 1:
+                df = df.rename({col_path: alias})
+            else:
+                expr = pl.col(parts[0])
+                for p in parts[1:]:
+                    expr = expr.struct.field(p)
+                df = df.with_columns(expr.alias(alias))
+
+        return df.select(key_cols + ["minx", "miny", "maxx", "maxy"])
 
     cols_to_read = key_cols + [geometry_col]
     if geometry_type == "latlon":
@@ -271,6 +289,7 @@ def bbox_intersects_geometry(
 
     Returns:
         pl.DataFrame: The subset of ``index_df`` whose rows overlap the geometry bounds.
+
     """
     gminx, gminy, gmaxx, gmaxy = geometry.bounds  # type: ignore[attr-defined]
     return index_df.filter(
@@ -320,6 +339,7 @@ def exact_spatial_filter(
 
     Raises:
         ValueError: If ``relationship`` is not one of the valid options.
+
     """
     logger.debug(
         "Refining {} candidates with exact spatial filter (relationship='{}')",
@@ -423,6 +443,7 @@ def execute_spatial_join(
     Returns:
         pl.DataFrame: ``primary_df`` with additional columns
         ``{other_entity_name}_{col}`` appended for each ``agg`` entry.
+
     """
     logger.info(
         "Starting execute_spatial_join for other_entity_name={}", other_entity_name

{core_lens-0.1.dev136.dist-info → core_lens-0.1.dev140.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev136
+Version: 0.1.dev140
 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.dev140.dist-info/RECORD

@@ -0,0 +1,30 @@
+core_lens/__init__.py,sha256=orecTblbuvC112H3VSOVu60ABsP-fZ1q9Xq0mk5N_as,307
+core_lens/__main__.py,sha256=ydzrJGjWcTIIsw9jqftIKvd-XMPSzD-uIY6RoBRvKGc,218
+core_lens/_version.py,sha256=L2XU-ObkCHZUrKUrnKSt1WjwGMtJ04XzlG1c2qTbR3M,532
+core_lens/aoi.py,sha256=FRwC_XMYxFj9ad58vLy9Q7l0hkUzBfrWkBcSxPfSYU0,31765
+core_lens/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+core_lens/base/__init__.py,sha256=UyuirsO1YtbXmGVgPFcQcGsnVq0skH5IlhdVOmS2yGE,476
+core_lens/base/entity.py,sha256=n-3fL5VY744u-wXYtBg3_oIHH_Z_mW_kHybCS2EFCnw,25224
+core_lens/base/result.py,sha256=-I4eWChO1FxJGwmGHfauMcAaivZjrXnCXbb7EXAcop4,11934
+core_lens/base/view.py,sha256=23s3IRRP4VQxVAbT0BIJ_TbH5UAbT512MZ_xJMlUf1o,19739
+core_lens/base/namespaces/__init__.py,sha256=ktQAfiL-tjJFqFzw6FudepZz-pfDodIJUTCCOWshupc,210
+core_lens/base/namespaces/plot.py,sha256=tY7-kkEnMOkkOsIaJy1Q2ItBtzdGqBx1DBoHTN3qrf4,30663
+core_lens/base/namespaces/stats.py,sha256=9lfjTXpJU5TjvO9P0aqppUN9-l2rpP0VNTQ55fz0T0g,38922
+core_lens/entities/__init__.py,sha256=66IshOBiTObYf9h3FD92lXQaJ0W-_DGFT9vudDeuVdU,253
+core_lens/entities/mws.py,sha256=SvlDcTnqUwMzj_jMOZPcIGqq2D_b12z0wUOq0uCbrpM,1373
+core_lens/entities/tehsil.py,sha256=7HbUoJwuSsBnrZQtrxLMw1-yuB18Y3_ckcA6JnTAE3o,1757
+core_lens/entities/waterbody.py,sha256=4_2S-uGKCtOAfl2NCBSNMu4N5yyzM8z7H1Do1rPTgIY,1083
+core_lens/export/__init__.py,sha256=vMF9Qb3uo9eciOh0OXI3BpZhCbufxccPt0YjaDtcl7M,178
+core_lens/export/formats.py,sha256=-CTHltcDy0UPzEKZNrtnWnqsoj2t65imUxYTOz7l0oE,7454
+core_lens/schema/__init__.py,sha256=fNCBoGh_Imr2KVpzERn_EoDmaREoac-gYkT3oJBGfcs,133
+core_lens/schema/detection.py,sha256=DlIQR8OqYMtW49JEQFipch1Kjcr8uKUG-jNMYKwj9Ng,10127
+core_lens/schema/profile.py,sha256=iYpBEjBzQVTl9_vQ8FtBZ_MmZOhU8cylNVFxZL2RVls,5095
+core_lens/utils/__init__.py,sha256=jOWDmI8XtZ0NWosH-zbeOHHxHale4Dyz2MiS9MGP9sE,36
+core_lens/utils/paths.py,sha256=-ARFoVwxs5Ht0pHi1PXApDwgRkptXPZ7nqFZy_mPZmA,3455
+core_lens/utils/polars_utils.py,sha256=PL27FB9LlA5HVcW965x1SS7PzlUj-6DiY1I38ERWnVQ,4712
+core_lens/utils/season.py,sha256=X-Z4im3q-O6gN6yRX6awC-7dy77CRGMPSggfEh5ZdD4,11969
+core_lens/utils/spatial.py,sha256=AnGKa4SCOUJRkX2Wzp8DZgz5hjdGti65PlpzRQrHPJY,23418
+core_lens-0.1.dev140.dist-info/METADATA,sha256=5olAVFUWY94nf9YnCKUqUEj5SIroaKZbZg0ctZ2gL4I,6175
+core_lens-0.1.dev140.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+core_lens-0.1.dev140.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+core_lens-0.1.dev140.dist-info/RECORD,,

core_lens-0.1.dev136.dist-info/RECORD

@@ -1,30 +0,0 @@
-core_lens/__init__.py,sha256=orecTblbuvC112H3VSOVu60ABsP-fZ1q9Xq0mk5N_as,307
-core_lens/__main__.py,sha256=ydzrJGjWcTIIsw9jqftIKvd-XMPSzD-uIY6RoBRvKGc,218
-core_lens/_version.py,sha256=XOs-eSiptQsximat6U5vD_upBt2K_Ml1u8bvjm-d6TY,532
-core_lens/aoi.py,sha256=o-g41E8CPm-kAp_dD-T7KtbD6x1lQgRmvCQnubm2HAo,31748
-core_lens/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-core_lens/base/__init__.py,sha256=UyuirsO1YtbXmGVgPFcQcGsnVq0skH5IlhdVOmS2yGE,476
-core_lens/base/entity.py,sha256=KvU9cb34M8F_YUAu8qHVtsTtVyZmmWcyU_j0SYOmI9Y,25206
-core_lens/base/result.py,sha256=YZ5ShAX7l_DUHTBppa0wflPvm16K0LMtJRHTMkluGtU,11925
-core_lens/base/view.py,sha256=HxD2ZPgt3THWA6r4M6OfAnYAScJo_NODtBXGFZijfb4,19731
-core_lens/base/namespaces/__init__.py,sha256=ktQAfiL-tjJFqFzw6FudepZz-pfDodIJUTCCOWshupc,210
-core_lens/base/namespaces/plot.py,sha256=nDg3SH41OPCLaxRNpEMMb1z4ZLchKVFKvYsYfw2gbTk,30941
-core_lens/base/namespaces/stats.py,sha256=x6SIoO9Hfs1MoSKSOkZNKHF5VTnskW_OIk5cMkY0G4U,38907
-core_lens/entities/__init__.py,sha256=66IshOBiTObYf9h3FD92lXQaJ0W-_DGFT9vudDeuVdU,253
-core_lens/entities/mws.py,sha256=ZKox2zG-j5GF9Jld3vabfRmirWapQp62v6jRrY5GjYY,1183
-core_lens/entities/tehsil.py,sha256=qULw32bMX0R9eMBCz5Y2M3r_40v2KhbUCFpZllhUQ7Q,1605
-core_lens/entities/waterbody.py,sha256=7MnoB7siUzkeKyoIwZY6d98FEAzV0e4uqFYdCml5pNk,931
-core_lens/export/__init__.py,sha256=vMF9Qb3uo9eciOh0OXI3BpZhCbufxccPt0YjaDtcl7M,178
-core_lens/export/formats.py,sha256=yDS_PgSn4fGRR4402gVWvpT0dq57X02bog95yedk2l4,7449
-core_lens/schema/__init__.py,sha256=fNCBoGh_Imr2KVpzERn_EoDmaREoac-gYkT3oJBGfcs,133
-core_lens/schema/detection.py,sha256=zcUM9DaxAzKbX-_4vM6aST3MNkZmxi2Yu4EyZuTFbR0,9791
-core_lens/schema/profile.py,sha256=5Pbfv_4jtzFJnRQA5Z680hxywpiV7882_NJGoT327hc,5093
-core_lens/utils/__init__.py,sha256=jOWDmI8XtZ0NWosH-zbeOHHxHale4Dyz2MiS9MGP9sE,36
-core_lens/utils/paths.py,sha256=-b6_NwwnyjyYD6i7Cwze64LhzhHNRlvrKBTqR4rjojA,3451
-core_lens/utils/polars_utils.py,sha256=dcUO4Sn64swF343kbFKz5UYldPSZ6kfNFJ14iUt505c,4709
-core_lens/utils/season.py,sha256=5H8QRjbu5-kQlVnqE_qGQtt_JcX2CuNJm-Wyhgps5ro,11962
-core_lens/utils/spatial.py,sha256=onhJwyap4OIKvjNEOCFtb4zkQ6ZYqki6lVF_YJ4spH4,22912
-core_lens-0.1.dev136.dist-info/METADATA,sha256=l72l8jxxKO06hEQEdRGVkHiT5U4THoPRz-9vkWUf9B8,6175
-core_lens-0.1.dev136.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-core_lens-0.1.dev136.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-core_lens-0.1.dev136.dist-info/RECORD,,