core-lens 0.1.dev155__tar.gz → 0.1.dev160__tar.gz

{core_lens-0.1.dev155 → core_lens-0.1.dev160}/PKG-INFO

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

{core_lens-0.1.dev155 → core_lens-0.1.dev160}/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,113 @@ 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,
+        clamped_min: bool = False,
+        clamped_max: bool = False,
+    ) -> None:
+        self._map = map_widget
+        self._cmap = cmap
+        self._v_min = v_min
+        self._v_max = v_max
+        self._column_name = column_name
+        self._clamped_min = clamped_min
+        self._clamped_max = clamped_max
+
+    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)
+
+                prefix = ""
+                if i == stops - 1 and self._clamped_min:
+                    prefix = "&lt; "
+                elif i == 0 and self._clamped_max:
+                    prefix = "&gt; "
+
+                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;">{prefix}{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`.
 
@@ -238,8 +344,12 @@ class PlotNamespace:
         self.result = result
 
     def choropleth(
-        self, column: str, subplot_on: SubplotOn | None = None
-    ) -> "lonboard.Map":
+        self,
+        column: str,
+        subplot_on: SubplotOn | None = None,
+        v_min: float | None = None,
+        v_max: float | None = None,
+    ) -> "MapWithLegend":
         """Render an interactive choropleth map using Lonboard.
 
         If the Result does not already have geometry, it will be attached
@@ -312,20 +422,33 @@ class PlotNamespace:
 
         with warnings.catch_warnings():
             warnings.simplefilter("ignore", category=RuntimeWarning)
-            v_min, v_max = np.nanmin(values), np.nanmax(values)
+            actual_min, actual_max = np.nanmin(values), np.nanmax(values)
+
+        calc_v_min = float(v_min) if v_min is not None else float(actual_min)
+        calc_v_max = float(v_max) if v_max is not None else float(actual_max)
+
+        clamped_min = v_min is not None and actual_min < v_min
+        clamped_max = v_max is not None and actual_max > v_max
 
-        if np.isnan(v_min) or np.isnan(v_max) or v_min >= v_max:
+        if np.isnan(calc_v_min) or np.isnan(calc_v_max) or calc_v_min >= calc_v_max:
             norm_values = np.where(np.isnan(values), np.nan, 0.0)
         else:
-            norm_values = (values - v_min) / (v_max - v_min)
+            norm_values = np.clip(
+                (values - calc_v_min) / (calc_v_max - calc_v_min), 0.0, 1.0
+            )
 
-        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=[255, 255, 255, 180],
+            line_width_min_pixels=0.25,
+        )
+        map_widget = lonboard.Map(layers=[layer])
+        return MapWithLegend(
+            map_widget, cmap, calc_v_min, calc_v_max, column, clamped_min, clamped_max
         )
-        return lonboard.Map(layers=[layer])
 
     def timeseries(
         self,

{core_lens-0.1.dev155 → core_lens-0.1.dev160}/src/core_lens/base/namespaces/stats.py

@@ -515,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(
@@ -538,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": (

{core_lens-0.1.dev155 → core_lens-0.1.dev160}/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)