core-lens 0.1.dev154__tar.gz → 0.1.dev159__tar.gz

{core_lens-0.1.dev154 → core_lens-0.1.dev159}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev154
+Version: 0.1.dev159
 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.dev159/src/core_lens/__main__.py

@@ -0,0 +1,36 @@
+from . import __version__
+
+
+def hello() -> str:
+    hello_str = """Hello from core-lens!
+
+The following primary capabilities are available:
+- AoI: Construct Area of Interest queries (e.g., `AoI(district="Godda")`)
+- Result: Lazy evaluation and computation graph materialisation
+
+Analytics (via `result.stats`):
+- anomaly(): Timeseries and cross-sectional anomaly detection
+- change(): Absolute, percentage, and trend changes over time
+- similarity(): Multi-feature similarity search across entities
+- test(): Statistical hypothesis testing
+- correlate(): Feature correlation analysis
+
+Visualisation (via `result.plot`):
+- choropleth(): Interactive Lonboard spatial mapping
+- timeseries(): Temporal data visualisation
+- scatter(): Scatter plots for variable comparison
+- distribution(): Histograms and density plots
+- correlation(): Correlation heatmaps between variables
+- heatmap(): 2D density/binned heatmaps
+- matrix(): Scatter matrix/pair plots
+"""
+    return hello_str
+
+
+def version() -> str:
+    return str(__version__)
+
+
+if __name__ == "__main__":
+    print(hello())
+    print(f"Version: {version()}")

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

{core_lens-0.1.dev154 → core_lens-0.1.dev159}/src/core_lens/base/namespaces/plot.py

@@ -27,7 +27,6 @@ class SubplotOn(Enum):
 
 
 if TYPE_CHECKING:
-    import lonboard
     from bokeh.plotting import figure as BokehFigure
     from core_lens.base.result import Result
 
@@ -224,6 +223,102 @@ def _apply_theme(fig: Any, result: "Result", title: str) -> None:
     fig.add_layout(subtitle)
 
 
+class MapWithLegend:
+    """Wrapper around lonboard.Map that adds a legend for Jupyter and HTML exports."""
+
+    def __init__(
+        self,
+        map_widget: Any,
+        cmap: Any,
+        v_min: float,
+        v_max: float,
+        column_name: str,
+    ) -> None:
+        self._map = map_widget
+        self._cmap = cmap
+        self._v_min = v_min
+        self._v_max = v_max
+        self._column_name = column_name
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._map, name)
+
+    def _generate_legend_div(self, absolute: bool = True) -> str:
+        import matplotlib.colors as mcolors
+        import numpy as np
+
+        stops = 5
+        style = (
+            "position:absolute; bottom:35px; left:20px; z-index:999; "
+            if absolute
+            else ""
+        )
+        style += (
+            "background:white; padding:8px 12px; border-radius:4px; "
+            "box-shadow:0 1px 4px rgba(0,0,0,.3); font-family:sans-serif; font-size:12px;"
+        )
+
+        html = [
+            f'<div style="{style}">',
+            f'<b style="margin-bottom:4px;display:inline-block;">{self._column_name}</b><br>',
+        ]
+
+        if np.isnan(self._v_min) or np.isnan(self._v_max) or self._v_min >= self._v_max:
+            html.append('<span style="color:gray;">No Data</span>')
+        else:
+            for i in range(stops):
+                frac = (stops - 1 - i) / (
+                    stops - 1
+                )  # Reverse order so highest is on top
+                val = self._v_min + frac * (self._v_max - self._v_min)
+                rgba = self._cmap(frac)
+                hex_color = mcolors.to_hex(rgba)
+                html.append(
+                    f'<div style="margin-top:2px;">'
+                    f'<span style="background:{hex_color};width:12px;height:12px;'
+                    f"display:inline-block;margin-right:8px;vertical-align:middle;"
+                    f'border:1px solid #ccc;"></span>'
+                    f'<span style="vertical-align:middle;">{val:.2f}</span></div>'
+                )
+        html.append("</div>")
+        return "".join(html)
+
+    def _ipython_display_(self) -> None:
+        import ipywidgets  # type: ignore[import-untyped]
+        from IPython.display import display
+
+        legend_div = self._generate_legend_div(absolute=False)
+        legend_html = ipywidgets.HTML(legend_div)
+
+        display(ipywidgets.VBox([legend_html, self._map]))  # type: ignore[no-untyped-call]
+
+    def to_html(
+        self, filename: str | None = None, title: str | None = None
+    ) -> str | None:
+        """Export the map to a static HTML string or file, injecting the legend."""
+        # lonboard.Map to_html doesn't accept title in all versions,
+        # so we conditionally pass it if it's not None or we can just omit title if we aren't sure.
+        # But wait, we can just use `self._map.to_html()`
+        if title is not None:
+            try:
+                html_str = self._map.to_html(title=title)
+            except TypeError:
+                html_str = self._map.to_html()
+        else:
+            html_str = self._map.to_html()
+
+        legend_div = self._generate_legend_div(absolute=True)
+
+        # Inject right before closing </body> tag
+        html_str = html_str.replace("</body>", legend_div + "</body>")
+
+        if filename is not None:
+            with open(filename, "w", encoding="utf-8") as f:
+                f.write(html_str)
+            return None
+        return str(html_str)
+
+
 class PlotNamespace:
     """Visualisation namespace for :class:`~core_lens.base.result.Result`.
 
@@ -239,7 +334,7 @@ class PlotNamespace:
 
     def choropleth(
         self, column: str, subplot_on: SubplotOn | None = None
-    ) -> "lonboard.Map":
+    ) -> "MapWithLegend":
         """Render an interactive choropleth map using Lonboard.
 
         If the Result does not already have geometry, it will be attached
@@ -319,13 +414,16 @@ class PlotNamespace:
         else:
             norm_values = (values - v_min) / (v_max - v_min)
 
-        cmap = mpl.colormaps["plasma"]
+        cmap = mpl.colormaps["plasma_r"]
 
         layer = lonboard.PolygonLayer(
             arrow_table,
             get_fill_color=apply_continuous_cmap(norm_values, cmap),
+            get_line_color=[211, 211, 211, 255],
+            line_width_min_pixels=0.5,
         )
-        return lonboard.Map(layers=[layer])
+        map_widget = lonboard.Map(layers=[layer])
+        return MapWithLegend(map_widget, cmap, v_min, v_max, column)
 
     def timeseries(
         self,

{core_lens-0.1.dev154 → core_lens-0.1.dev159}/src/core_lens/base/namespaces/stats.py

@@ -489,18 +489,24 @@ class StatsNamespace:
             )
 
         if method in (ChangeMethod.ABSOLUTE, ChangeMethod.PERCENTAGE):
+            join_keys = [key]
+            if "season" in df.columns:
+                join_keys.append("season")
+
             from_df = (
                 df.filter(pl.col(year_col) == from_period)
-                .select([key, column])
+                .select(join_keys + [column])
                 .rename({column: "value_from"})
             )
             to_df = (
                 df.filter(pl.col(year_col) == to_period)
-                .select([key, column])
+                .select(join_keys + [column])
                 .rename({column: "value_to"})
             )
-            joined = from_df.join(to_df, on=key, how="inner").with_columns(
+            joined = from_df.join(to_df, on=join_keys, how="inner").with_columns(
                 [
+                    pl.lit(from_period).alias("year_from").cast(pl.Int32),
+                    pl.lit(to_period).alias("year_to").cast(pl.Int32),
                     (pl.col("value_to") - pl.col("value_from")).alias("change"),
                     (
                         (pl.col("value_to") - pl.col("value_from"))
@@ -509,7 +515,16 @@ class StatsNamespace:
                     ).alias("pct_change"),
                 ]
             )
-            data = joined
+
+            final_cols = join_keys + [
+                "year_from",
+                "year_to",
+                "value_from",
+                "value_to",
+                "change",
+                "pct_change",
+            ]
+            data = joined.select(final_cols)
 
         else:  # trend
             period_df = df.filter(
@@ -532,6 +547,8 @@ class StatsNamespace:
                 rows.append(
                     {
                         key: eid,
+                        "year_from": int(from_period),
+                        "year_to": int(to_period),
                         "slope": float(cast(float, slope)),
                         "r_squared": float(cast(float, r_val) ** 2),
                         "direction": (
@@ -859,12 +876,9 @@ class StatsNamespace:
         df = self._r.df()
         key = self._r.key_cols[0]
 
-        min_year: int | None = None
-        max_year: int | None = None
-
         # --- Build feature DataFrame ------------------------------------------
         # Universe of entity keys from result.data.
-        feat = df.select([key]).unique()
+        feat = df.select([key])
 
         for col_name, spec in columns.items():
             if spec is None:
@@ -884,23 +898,6 @@ class StatsNamespace:
             resolution_str, filter_dict = spec
             filter_dict = dict(filter_dict) if filter_dict else {}
 
-            if "year" in filter_dict:
-                yr = filter_dict["year"]
-                y0: int | None = None
-                y1: int | None = None
-
-                if isinstance(yr, (list, tuple)) and len(yr) >= 2:
-                    y0, y1 = int(yr[0]), int(yr[1])
-                elif isinstance(yr, int):
-                    y0, y1 = yr, yr
-
-                if y0 is not None:
-                    if min_year is None or y0 < min_year:
-                        min_year = y0
-                if y1 is not None:
-                    if max_year is None or y1 > max_year:
-                        max_year = y1
-
             entity = self._r.entity
             path: str | None
             if resolution_str == "static":
@@ -1026,26 +1023,13 @@ class StatsNamespace:
         dists[tidx] = float("inf")  # exclude target itself
         top_idx = np.argsort(dists)[:top_n]
 
-        if min_year is None and max_year is None:
-            year_col = self._year_col()
-            if year_col and year_col in df.columns:
-                yr_min = df[year_col].min()
-                yr_max = df[year_col].max()
-                if yr_min is not None and yr_max is not None:
-                    min_year = int(cast(int, yr_min))
-                    max_year = int(cast(int, yr_max))
-
-        output_dict: dict[str, Any] = {
-            key: [ids[i] for i in top_idx],
-            "similarity_score": [float(1.0 / (1.0 + dists[i])) for i in top_idx],
-            "rank": list(range(1, len(top_idx) + 1)),
-        }
-
-        if min_year is not None and max_year is not None:
-            output_dict["year_from"] = [min_year] * len(top_idx)
-            output_dict["year_to"] = [max_year] * len(top_idx)
-
-        data = pl.DataFrame(output_dict)
+        data = pl.DataFrame(
+            {
+                key: [ids[i] for i in top_idx],
+                "similarity_score": [float(1.0 / (1.0 + dists[i])) for i in top_idx],
+                "rank": list(range(1, len(top_idx) + 1)),
+            }
+        )
         metadata: dict[str, Any] = {
             "method": method.value if method is not None else None,
             "target": target,

{core_lens-0.1.dev154 → core_lens-0.1.dev159}/tests/unit/test_main.py

@@ -8,7 +8,11 @@ def test_version() -> None:
 def test_hello() -> None:
     from core_lens.__main__ import hello
 
-    assert hello() == "Hello from core-lens!"
+    msg = hello()
+    assert msg.startswith("Hello from core-lens!")
+    assert "AoI: Construct Area of Interest queries" in msg
+    assert "Analytics (via `result.stats`):" in msg
+    assert "Visualisation (via `result.plot`):" in msg
 
 
 def test_version_type() -> None:

{core_lens-0.1.dev154 → core_lens-0.1.dev159}/tests/unit/test_plot.py

@@ -9,7 +9,7 @@ from typing import Any
 from core_lens.base.entity import BaseEntity
 from core_lens.base.result import Result
 from core_lens.schema.profile import Resolution, SchemaProfile
-from core_lens.base.namespaces.plot import SubplotOn
+from core_lens.base.namespaces.plot import SubplotOn, MapWithLegend
 
 
 class DummyEntity(BaseEntity):
@@ -79,7 +79,7 @@ def test_choropleth_basic(dummy_result: Result) -> None:
     """Test choropleth creates a lonboard Map correctly."""
     plot_map = dummy_result.plot.choropleth("value")
 
-    assert isinstance(plot_map, lonboard.Map)
+    assert isinstance(plot_map, MapWithLegend)
     assert len(plot_map.layers) == 1
     layer = plot_map.layers[0]
     assert isinstance(layer, lonboard.PolygonLayer)

core_lens-0.1.dev154/src/core_lens/__main__.py

@@ -1,14 +0,0 @@
-from . import __version__
-
-
-def hello() -> str:
-    return "Hello from core-lens!"
-
-
-def version() -> str:
-    return str(__version__)
-
-
-if __name__ == "__main__":
-    print(hello())
-    print(f"Version: {version()}")