core-lens 0.1.dev113__tar.gz → 0.1.dev117__tar.gz

{core_lens-0.1.dev113 → core_lens-0.1.dev117}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev113
+Version: 0.1.dev117
 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.dev117/docs/source/export.md

@@ -0,0 +1,47 @@
+# Data Export
+
+CoreLens provides a unified `core_lens.export` module for saving `Result` objects to various file formats. Standard tabular formats use Polars for high-speed writes, while geospatial formats leverage DuckDB's spatial extensions for robust geometry encoding.
+
+## Standard Formats
+
+Export non-spatial results to standard formats. Note that these formats cannot encode geometry columns; if your `Result` has geometry, these functions will raise a `TypeError`.
+
+```python
+from core_lens.export import parquet, csv, json
+
+res = aoi.mws.annual
+
+# Export to Parquet with ZSTD compression
+parquet(res, "output.parquet", compression="zstd")
+
+# Export to CSV
+csv(res, "output.csv", separator=",")
+
+# Export to JSON
+json(res, "output.json", pretty=True)
+```
+
+## Geospatial Formats
+
+Export spatial data to GeoParquet and GeoJSON. The result must have geometry attached (e.g., by calling `.with_geometry()`).
+
+```python
+from core_lens.export import geoparquet, geojson
+
+# Make sure geometry is attached!
+spatial_res = aoi.mws.annual.with_geometry()
+
+# Export to GeoParquet with DuckDB COPY options (e.g., partitioning)
+geoparquet(
+    spatial_res,
+    "output.geoparquet",
+    compression="ZSTD",
+    partition_by="year"
+)
+
+# Export to GeoJSON
+geojson(spatial_res, "output.json")
+```
+
+> [!NOTE]
+> Exporting to geospatial formats automatically uses DuckDB to cast WKB geometries to proper spatial types via the `spatial` extension. CoreLens handles the installation and loading of the extension seamlessly under the hood.

{core_lens-0.1.dev113 → core_lens-0.1.dev117}/docs/source/index.rst

@@ -21,5 +21,6 @@ Provides a unified interface over microwatershed hydrology, administrative bound
    queries
    stats
    plots
+   export
    plugins
    autoapi/index

{core_lens-0.1.dev113 → core_lens-0.1.dev117}/docs/source/intro.md

@@ -12,4 +12,5 @@ CoreLens provides a unified interface over microwatersheds, administrative bound
 - **Pluggable Entities**: Built-in support for standard units (MWS, Tehsil) with a simple plugin architecture for adding new domain entities.
 - **Temporal & Seasonal Awareness**: Native support for agronomic seasons (Kharif, Rabi, Zaid) and time-range filtering.
 - **Spatial Statistics & Analysis**: Built-in methods for anomaly detection, spatial similarity, temporal correlation, and hypothesis testing.
-- **Interactive Visualisation**: Generate interactive maps using Lonboard and timeseries/scatter plots using Bokeh directly from results.
+- **Interactive Visualisation**: Generate interactive maps using Lonboard with zero-copy GeoArrow rendering directly from Polars, and timeseries/scatter plots using Bokeh.
+- **High-Performance Exports**: Export results directly to Parquet, JSON, CSV, or spatially-enabled GeoParquet and GeoJSON using integrated DuckDB spatial extensions.

{core_lens-0.1.dev113 → core_lens-0.1.dev117}/docs/source/plots.md

@@ -1,6 +1,6 @@
 # Visualisation and Plots
 
-The `result.plot` namespace provides integrated plotting capabilities. Spatial plots use **Lonboard** for high-performance interactive maps, while charts and timeseries use **Bokeh**.
+The `result.plot` namespace provides integrated plotting capabilities. Spatial plots use **Lonboard** for high-performance interactive maps (achieved via zero-copy GeoArrow memory mapping directly from Polars, bypassing GeoPandas), while charts and timeseries use **Bokeh**.
 
 Plot methods return plot objects (like a Bokeh Figure or Lonboard Map) which can be displayed using `bokeh.io.show` or exported via `bokeh.io.save`.
 

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

{core_lens-0.1.dev113 → core_lens-0.1.dev117}/src/core_lens/aoi.py

@@ -67,10 +67,10 @@ class SeasonConfig:
         """Return the season name for a given date.
 
         Args:
-            d: The date to classify.
+            d (date): The date to classify.
 
         Returns:
-            ``"kharif"``, ``"rabi"``, or ``"zaid"``.
+            str: ``"kharif"``, ``"rabi"``, or ``"zaid"``.
         """
         md = f"{d.month:02d}-{d.day:02d}"
         for name in ("kharif", "rabi", "zaid"):
@@ -155,16 +155,16 @@ class AoI:
         """Resolve the AoI boundary and scope all registered entities.
 
         Args:
-            data_root: Path to the root data directory.  Prepended to every
+            data_root (str): Path to the root data directory.  Prepended to every
                 relative entity path that does not start with ``/`` or a URI
                 scheme.
-            bbox: Bounding box as ``(minx, miny, maxx, maxy)`` in WGS-84.
+            bbox (tuple[float, float, float, float] | None, optional): Bounding box as ``(minx, miny, maxx, maxy)`` in WGS-84.
                 Mutually exclusive with ``geometry`` and ``entity_kwargs``.
-            geometry: Arbitrary Shapely geometry.  Used as-is.  Mutually
+            geometry (shapely.Geometry | None, optional): Arbitrary Shapely geometry.  Used as-is.  Mutually
                 exclusive with ``bbox`` and ``entity_kwargs``.
-            seasons: :class:`SeasonConfig` override.  Defaults to the library
+            seasons (SeasonConfig | None, optional): :class:`SeasonConfig` override.  Defaults to the library
                 agronomic defaults.
-            **entity_kwargs: Named filter pairs that identify the boundary,
+            **entity_kwargs (str | list[str]): Named filter pairs that identify the boundary,
                 e.g. ``tehsil="Pangi"``, ``district="Chamba"``,
                 ``state="Himachal Pradesh"``, ``mws_id="13_551"``.
                 Mutually exclusive with ``bbox`` and ``geometry``.
@@ -219,7 +219,7 @@ class AoI:
         """The season name for today's date under the AoI's SeasonConfig.
 
         Returns:
-            ``"kharif"``, ``"rabi"``, or ``"zaid"``.
+            str: ``"kharif"``, ``"rabi"``, or ``"zaid"``.
         """
         return self.seasons.season_for(date.today())
 
@@ -228,7 +228,7 @@ class AoI:
         """The current calendar year.
 
         Returns:
-            Current year as an integer.
+            int: Current year as an integer.
         """
         return date.today().year
 
@@ -236,11 +236,11 @@ class AoI:
         """Render an interactive Lonboard map of the AoI and its entity layers.
 
         Args:
-            overlay: An optional :class:`~core_lens.base.result.Result` to
+            overlay (Result | None, optional): An optional :class:`~core_lens.base.result.Result` to
                 overlay on the map.
 
         Returns:
-            A Lonboard Map object.
+            Any: A Lonboard Map object.
         """
         import lonboard
         import geopandas as gpd
@@ -309,10 +309,10 @@ class AoI:
         the unique matching row).
 
         Args:
-            entity_kwargs: Column–value pairs used to identify the boundary.
+            entity_kwargs (dict[str, str | list[str]]): Column–value pairs used to identify the boundary.
 
         Returns:
-            The union of all matching entity geometries as a Shapely object.
+            shapely.Geometry: The union of all matching entity geometries as a Shapely object.
 
         Raises:
             :class:`~core_lens.base.EntityValidationError`: If no registered entity can satisfy the filters.
@@ -391,7 +391,7 @@ class AoI:
         :class:`AoI` is instantiated (when ``data_root`` is known).
 
         Args:
-            entity_cls: A concrete subclass of
+            entity_cls (type[BaseEntity]): A concrete subclass of
                 :class:`~core_lens.base.entity.BaseEntity`.
 
         Raises:
@@ -417,7 +417,7 @@ class AoI:
         Primarily useful in tests where a clean registry is needed between runs.
 
         Args:
-            entity_cls: The entity class to remove.
+            entity_cls (type[BaseEntity]): The entity class to remove.
         """
         name = _entity_name(entity_cls)
         _REGISTRY.pop(name, None)
@@ -427,7 +427,7 @@ class AoI:
         """Return the names of all currently registered entities.
 
         Returns:
-            A sorted list of entity name strings.
+            list[str]: A sorted list of entity name strings.
         """
         return sorted(_REGISTRY)
 

{core_lens-0.1.dev113 → core_lens-0.1.dev117}/src/core_lens/base/entity.py

@@ -84,7 +84,7 @@ class BaseEntity(ABC):
         """Initialise the entity with an optional data root directory.
 
         Args:
-            data_root: Absolute path to the root data directory.  When
+            data_root (pathlib.Path | None, optional): Absolute path to the root data directory.  When
                 supplied, relative :attr:`static_path`, :attr:`annual_path`,
                 and :attr:`fortnightly_path` values are resolved against this
                 directory.  Defaults to ``None``, in which case relative paths
@@ -100,10 +100,10 @@ class BaseEntity(ABC):
         otherwise against the current working directory.
 
         Args:
-            path: A filesystem path, absolute or relative.
+            path (str): A filesystem path, absolute or relative.
 
         Returns:
-            An absolute path string.
+            str: An absolute path string.
 
         Raises:
             FileNotFoundError: If the resolved path does not exist.
@@ -131,7 +131,7 @@ class BaseEntity(ABC):
         ``[\"mws_id\"]``), but the contract allows composite keys for plugins.
 
         Returns:
-            A list of column name strings present in the static file.
+            list[str]: A list of column name strings present in the static file.
         """
 
     @property
@@ -143,7 +143,7 @@ class BaseEntity(ABC):
         (WKB bytes, WKT string, or a native geometry column).
 
         Returns:
-            The column name as a string.
+            str: The column name as a string.
         """
 
     @property
@@ -156,7 +156,7 @@ class BaseEntity(ABC):
         ``FileNotFoundError`` is raised if the file does not exist.
 
         Returns:
-            A path string.
+            str: A path string.
         """
 
     @property
@@ -168,7 +168,7 @@ class BaseEntity(ABC):
         :class:`EntityValidationError` is raised.
 
         Returns:
-            A path string, or ``None`` if the entity has no annual data.
+            str | None: A path string, or ``None`` if the entity has no annual data.
         """
         return None
 
@@ -181,7 +181,7 @@ class BaseEntity(ABC):
         :class:`EntityValidationError` is raised.
 
         Returns:
-            A path string, or ``None`` if the entity has no fortnightly data.
+            str | None: A path string, or ``None`` if the entity has no fortnightly data.
         """
         return None
 
@@ -194,7 +194,7 @@ class BaseEntity(ABC):
         instead of relying on detection.
 
         Returns:
-            A fully-validated :class:`~core_lens.schema.profile.SchemaProfile`.
+            SchemaProfile: A fully-validated :class:`~core_lens.schema.profile.SchemaProfile`.
         """
         if not hasattr(self, "_schema_profile"):
             from core_lens.schema.detection import detect
@@ -247,7 +247,7 @@ class BaseEntity(ABC):
                 are resolved as entity-name lookups.
 
         Returns:
-            A lazy :class:`~core_lens.base.view.View` with resolved key pairs.
+            View: A lazy :class:`~core_lens.base.view.View` with resolved key pairs.
 
         Raises:
             ValueError: If a kwarg cannot be resolved as either an attribute
@@ -354,21 +354,21 @@ class BaseEntity(ABC):
         refines with a Shapely STRtree exact-relationship check.
 
         Args:
-            geometry: A Shapely geometry representing the spatial extent.
-            bbox: Bounding box as ``(minx, miny, maxx, maxy)`` in WGS-84.
+            geometry (shapely.Geometry | None, optional): A Shapely geometry representing the spatial extent.
+            bbox (tuple[float, float, float, float] | None, optional): Bounding box as ``(minx, miny, maxx, maxy)`` in WGS-84.
                 Converted to a ``shapely.geometry.box`` internally.
-            relationship: Spatial relationship mode.
+            relationship (str, optional): Spatial relationship mode.
 
                 * ``"centroid"`` (default) — entity centroid must lie within
                   the geometry.
                 * ``"area"`` — intersection area / entity area must exceed
                   ``threshold``.
 
-            threshold: Area coverage threshold for ``"area"`` mode (0–1).
+            threshold (float, optional): Area coverage threshold for ``"area"`` mode (0–1).
                 Default 0.5.
 
         Returns:
-            A lazy :class:`~core_lens.base.view.View` scoped to the given
+            View: A lazy :class:`~core_lens.base.view.View` scoped to the given
             spatial extent.
 
         Raises:
@@ -411,15 +411,15 @@ class BaseEntity(ABC):
         Joined columns are namespaced as ``{entity_name}_{column_name}``.
 
         Args:
-            other: The secondary :class:`BaseEntity` whose columns will be
+            other (BaseEntity): The secondary :class:`BaseEntity` whose columns will be
                 joined and aggregated onto ``self``.
-            agg: Mapping of ``{column: aggregation}`` specifying which columns
+            agg (dict[str, str]): Mapping of ``{column: aggregation}`` specifying which columns
                 from ``other`` to bring in and how to aggregate them.  Valid
                 aggregation strings are ``\"area\"``, ``\"count\"``, ``\"mean\"``,
                 ``\"sum\"``, ``\"min\"``, and ``\"max\"``.
 
         Returns:
-            A lazy :class:`~core_lens.base.view.View` with the join spec
+            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-0.1.dev113 → core_lens-0.1.dev117}/src/core_lens/base/namespaces/plot.py

@@ -220,13 +220,13 @@ class PlotNamespace:
         automatically via :meth:`~core_lens.base.result.Result.with_geometry`.
 
         Args:
-            column: The column to use for colour mapping.
-            subplot_on: Optional temporal dimension to split data across.
+            column (str): The column to use for colour mapping.
+            subplot_on (SubplotOn | None, optional): Optional temporal dimension to split data across.
                 A :class:`~core_lens.base.namespaces.plot.SubplotOn` enum value. When set, one layer is rendered per unique
                 value of ``subplot_on`` in the data.
 
         Returns:
-            A Lonboard Map object.
+            lonboard.Map: A Lonboard Map object.
 
         Raises:
             ValueError: If ``column`` or ``subplot_on`` column not found in data.
@@ -311,16 +311,16 @@ class PlotNamespace:
         plain :class:`bokeh.plotting.figure`.
 
         Args:
-            x: The temporal column to plot on the x-axis.
-            y: The value column(s) to plot on the y-axis.
+            x (str | None, optional): The temporal column to plot on the x-axis.
+            y (str | list[str] | None, optional): The value column(s) to plot on the y-axis.
                 If ``None``, all numeric columns (except ``x``) are used.
-            subplot_on: Optional temporal dimension to split data across.
+            subplot_on (SubplotOn | str | None, optional): Optional temporal dimension to split data across.
                 A :class:`~core_lens.base.namespaces.plot.SubplotOn` enum value or string.
-            top_n: Maximum number of entities rendered in per-entity view.
-            aggregate: If ``True``, renders only the aggregated mean view.
+            top_n (int, optional): Maximum number of entities rendered in per-entity view.
+            aggregate (bool, optional): If ``True``, renders only the aggregated mean view.
 
         Returns:
-            A Bokeh Tabs object (or a single Figure when ``aggregate=True``).
+            Any: A Bokeh Tabs object (or a single Figure when ``aggregate=True``).
         """
         import polars as pl
         import polars.selectors as cs
@@ -486,12 +486,12 @@ class PlotNamespace:
         """Render a scatter plot using Bokeh.
 
         Args:
-            x: The column to plot on the x-axis.
-            y: The column(s) to plot on the y-axis. If None, auto-selects all numeric.
-            top_n: Maximum number of entities to plot.
+            x (str | None, optional): The column to plot on the x-axis.
+            y (str | list[str] | None, optional): The column(s) to plot on the y-axis. If None, auto-selects all numeric.
+            top_n (int, optional): Maximum number of entities to plot.
 
         Returns:
-            A Bokeh Figure or Tabs object.
+            Any: A Bokeh Figure or Tabs object.
         """
         import polars as pl
         import polars.selectors as cs
@@ -562,11 +562,11 @@ class PlotNamespace:
         """Render a distribution (histogram) plot using Bokeh.
 
         Args:
-            x: The column(s) to plot the distribution for. If None, auto-selects all numeric.
-            top_n: Maximum number of entities to include.
+            x (str | list[str] | None, optional): The column(s) to plot the distribution for. If None, auto-selects all numeric.
+            top_n (int, optional): Maximum number of entities to include.
 
         Returns:
-            A Bokeh Figure or Tabs object.
+            Any: A Bokeh Figure or Tabs object.
         """
         import numpy as np
         import pandas as pd
@@ -631,11 +631,11 @@ class PlotNamespace:
         """Render a correlation heatmap using Bokeh.
 
         Args:
-            columns: Optional list of columns to correlate. Defaults to all numeric.
-            top_n: Maximum number of entities to include (currently unused).
+            columns (list[str] | None, optional): Optional list of columns to correlate. Defaults to all numeric.
+            top_n (int, optional): Maximum number of entities to include (currently unused).
 
         Returns:
-            A Bokeh Figure object.
+            Any: A Bokeh Figure object.
         """
         import polars.selectors as cs
         from bokeh.models import BasicTicker, ColumnDataSource, LinearColorMapper
@@ -708,13 +708,13 @@ class PlotNamespace:
         """Render a heatmap using Bokeh.
 
         Args:
-            x: The column for the x-axis.
-            y: The column for the y-axis.
-            value: The column for the colour values.
-            top_n: Maximum number of entities to include (currently unused).
+            x (str | None, optional): The column for the x-axis.
+            y (str | None, optional): The column for the y-axis.
+            value (str | None, optional): The column for the colour values.
+            top_n (int, optional): Maximum number of entities to include (currently unused).
 
         Returns:
-            A Bokeh Figure object.
+            Any: A Bokeh Figure object.
         """
         from bokeh.models import (
             BasicTicker,
@@ -789,7 +789,7 @@ class PlotNamespace:
         """Render a scatter matrix (pairs plot) using Bokeh.
 
         Returns:
-            A Bokeh ``gridplot`` object.
+            Any: A Bokeh ``gridplot`` object.
         """
         import polars.selectors as cs
         from bokeh.layouts import gridplot

{core_lens-0.1.dev113 → core_lens-0.1.dev117}/src/core_lens/base/namespaces/stats.py

@@ -170,12 +170,12 @@ class StatsNamespace:
         """Per-column or per-entity descriptive statistics.
 
         Args:
-            columns: Numeric columns to describe. Defaults to all numeric cols.
-            by: ``"column"`` (one row per column, design default) or
+            columns (list[str] | None, optional): Numeric columns to describe. Defaults to all numeric cols.
+            by (str, optional): ``"column"`` (one row per column, design default) or
                 ``"entity"`` (one row per entity with mean/std per column).
 
         Returns:
-            New :class:`~core_lens.base.result.Result` with descriptive stats.
+            Result: New :class:`~core_lens.base.result.Result` with descriptive stats.
 
         Raises:
             ValueError: If ``by`` is not ``\"column\"`` or ``\"entity\"``.
@@ -227,12 +227,12 @@ class StatsNamespace:
         """Pairwise correlations between columns.
 
         Args:
-            columns: At least 2 column names.
-            method: A :class:`~core_lens.base.namespaces.stats.CorrelateMethod` enum value.
-            across: ``"entity"`` or ``"time"`` — recorded in metadata only.
+            columns (list[str]): At least 2 column names.
+            method (CorrelateMethod, optional): A :class:`~core_lens.base.namespaces.stats.CorrelateMethod` enum value.
+            across (str, optional): ``"entity"`` or ``"time"`` — recorded in metadata only.
 
         Returns:
-            Result whose data has columns
+            Result: Result whose data has columns
             ``column_a | column_b | correlation | p_value``.
 
         Raises:
@@ -296,16 +296,16 @@ class StatsNamespace:
         """Hypothesis test in three modes: group-based, period-based, single-sample.
 
         Args:
-            column: Numeric column to test.
-            groups: Categorical column to split groups on.
-            periods: List of ``(from_year, to_year)`` period tuples.
-            against: Reference value for a one-sample test.
-            method: A :class:`~core_lens.base.namespaces.stats.TestMethod` enum value.
+            column (str): Numeric column to test.
+            groups (str | None, optional): Categorical column to split groups on.
+            periods (list[tuple[int, int]] | None, optional): List of ``(from_year, to_year)`` period tuples.
+            against (float | None, optional): Reference value for a one-sample test.
+            method (TestMethod | None, optional): A :class:`~core_lens.base.namespaces.stats.TestMethod` enum value.
                 Auto-selected via Shapiro-Wilk if ``None``.
-            significance_level: Alpha level for ``significant`` flag (default 0.05).
+            significance_level (float, optional): Alpha level for ``significant`` flag (default 0.05).
 
         Returns:
-            Result whose data has per-group descriptive stats
+            Result: Result whose data has per-group descriptive stats
             ``group | n | mean | std | median`` and
             ``metadata`` with ``statistic``, ``p_value``, ``significant``.
 
@@ -447,13 +447,13 @@ class StatsNamespace:
         """Change between two time periods per entity.
 
         Args:
-            column: Value column to compute change for.
-            from_period: Start year/period integer.
-            to_period: End year/period integer.
-            method: A :class:`~core_lens.base.namespaces.stats.ChangeMethod` enum value.
+            column (str): Value column to compute change for.
+            from_period (int): Start year/period integer.
+            to_period (int): End year/period integer.
+            method (ChangeMethod, optional): A :class:`~core_lens.base.namespaces.stats.ChangeMethod` enum value.
 
         Returns:
-            For *absolute* / *percentage*: data has
+            Result: For *absolute* / *percentage*: data has
             ``key_col | value_from | value_to | change | pct_change``.
             For *trend*: ``key_col | slope | r_squared | direction``.
 
@@ -550,15 +550,15 @@ class StatsNamespace:
         """Anomaly detection in cross-sectional or timeseries mode.
 
         Args:
-            column: Value column to analyse.
-            mode: ``"cross_sectional"`` or ``"timeseries"``.
-            method: An :class:`~core_lens.base.namespaces.stats.AnomalyCrossMethod` or :class:`~core_lens.base.namespaces.stats.AnomalyTsMethod` enum value.
-            baseline: ``(from_year, to_year)`` inclusive.  Required for
+            column (str): Value column to analyse.
+            mode (str): ``"cross_sectional"`` or ``"timeseries"``.
+            method (AnomalyCrossMethod | AnomalyTsMethod): An :class:`~core_lens.base.namespaces.stats.AnomalyCrossMethod` or :class:`~core_lens.base.namespaces.stats.AnomalyTsMethod` enum value.
+            baseline (tuple[int, int] | None, optional): ``(from_year, to_year)`` inclusive.  Required for
                 timeseries; optional for cross-sectional.
-            threshold: Sigma / score threshold for anomaly flag (default 2.0).
+            threshold (float, optional): Sigma / score threshold for anomaly flag (default 2.0).
 
         Returns:
-            Result whose data has ``key_col | anomaly_score | is_anomaly``
+            Result: Result whose data has ``key_col | anomaly_score | is_anomaly``
             (cross-sectional) or ``key_col | year | anomaly_score | is_anomaly``
             (timeseries, baseline period excluded).
 

{core_lens-0.1.dev113 → core_lens-0.1.dev117}/src/core_lens/base/result.py

@@ -78,7 +78,7 @@ class Result:
         """Return the underlying ``pl.DataFrame``.
 
         Returns:
-            The materialised data frame.
+            pl.DataFrame: The materialised data frame.
         """
         return self.data
 
@@ -89,7 +89,7 @@ class Result:
         :meth:`with_geometry` first on non-static results.
 
         Returns:
-            A ``geopandas.GeoDataFrame`` built from :attr:`data`.
+            gpd.GeoDataFrame: A ``geopandas.GeoDataFrame`` built from :attr:`data`.
 
         Raises:
             TypeError: If :attr:`has_geometry` is ``False``.
@@ -118,7 +118,7 @@ class Result:
         are responsible for collecting and wrapping the output themselves.
 
         Returns:
-            A lazy frame backed by :attr:`data`.
+            pl.LazyFrame: A lazy frame backed by :attr:`data`.
         """
         return self.data.lazy()
 
@@ -134,7 +134,7 @@ class Result:
         ``result.plot.choropleth()``.
 
         Returns:
-            A new :class:`Result` with the geometry column merged in and
+            Result: A new :class:`Result` with the geometry column merged in and
             ``has_geometry=True``.  If ``has_geometry`` is already ``True``,
             returns ``self`` unchanged.
         """
@@ -164,11 +164,11 @@ class Result:
                   .derive("drought_flag", pl.when(pl.col("rainfall") < 500).then(1).otherwise(0))
 
         Args:
-            name: Name for the new column.
-            expr: A Polars expression that evaluates to the column values.
+            name (str): Name for the new column.
+            expr (pl.Expr): A Polars expression that evaluates to the column values.
 
         Returns:
-            A new :class:`Result` with ``name`` appended to :attr:`data`.
+            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)
@@ -201,9 +201,9 @@ class Result:
              - ✅
 
         Args:
-            *exprs: One or more Polars aggregation expressions
+            *exprs (pl.Expr): One or more Polars aggregation expressions
                 (e.g. ``pl.mean("ndvi")``, ``pl.max("rainfall")``).
-            by: Grouping dimension.  ``None`` collapses all rows to one.
+            by (str | None, optional): Grouping dimension.  ``None`` collapses all rows to one.
                 ``"year"`` groups by entity + year and is valid for both
                 annual and fortnightly resolution.
                 Other temporal groupings (``"month"``, ``"year_month"``,
@@ -211,7 +211,7 @@ class Result:
                 ``resolution="fortnightly"``.
 
         Returns:
-            A new :class:`Result` whose ``data`` is the aggregated frame.
+            Result: A new :class:`Result` whose ``data`` is the aggregated frame.
 
         Raises:
             ValueError: If ``by`` is incompatible with :attr:`resolution`, or
@@ -257,6 +257,9 @@ class Result:
             result.stats.describe()
             result.stats.correlate(["ndvi", "rainfall"], method="spearman")
             result.stats.anomaly("ndvi", mode="cross_sectional", method="zscore")
+
+        Returns:
+            StatsNamespace: The statistical analysis namespace.
         """
         from core_lens.base.namespaces.stats import StatsNamespace
 
@@ -272,6 +275,9 @@ class Result:
 
             result.plot.choropleth("ndvi")
             result.plot.timeseries(x="year", y="rainfall")
+
+        Returns:
+            PlotNamespace: The visualisation namespace.
         """
         from core_lens.base.namespaces.plot import PlotNamespace