fix: solve minor issues in the histogram selection. refactoring done

Author: ElouenGinat

docs/conf.py

@@ -9,6 +9,7 @@
 import re
 import sys
 from pathlib import Path
+import tomllib
 
 DOCS_DIR = Path(__file__).resolve().parent
 ROOT_DIR = DOCS_DIR.parent
@@ -18,15 +19,15 @@
 
 
 def _read_release() -> str:
-    init_file = ROOT_DIR / "src" / "khisto" / "__init__.py"
-    match = re.search(
-        r'^__version__\s*=\s*"(?P<version>[^"]+)"',
-        init_file.read_text(encoding="utf-8"),
-        re.MULTILINE,
-    )
-    if match is None:
-        raise RuntimeError(f"Could not determine khisto version from {init_file}")
-    return match.group("version")
+    pyproject_file = ROOT_DIR / "pyproject.toml"
+    data = tomllib.loads(pyproject_file.read_text(encoding="utf-8"))
+
+    try:
+        return data["project"]["version"]
+    except KeyError as exc:
+        raise RuntimeError(
+            f"Could not determine khisto version from {pyproject_file}"
+        ) from exc
 
 project = 'khisto-python'
 copyright = '2026, The Khiops Team'

docs/index.rst

@@ -32,7 +32,7 @@ Get started
 
    .. code-block:: bash
 
-      pip install khisto            # core (NumPy only)
+      pip install khisto                # core (NumPy only)
       pip install "khisto[matplotlib]"  # + plotting
 
 .. code-block:: python
@@ -100,4 +100,3 @@ Get started
 
    API Comparison <api_comparison>
    Demo <demo>
-

src/khisto/array/histogram/api.py

@@ -34,20 +34,19 @@ def _select_histogram(
     """
     if max_bins is not None:
         # Find the finest granularity that respects max_bins
-        selected = None
-        for r in histogram_results:
+        for r in reversed(histogram_results):
             if len(r) <= max_bins:
-                selected = r
-            else:
-                break
+                return r
         # If no histogram respects the constraint, use the coarsest one
-        return selected if selected is not None else histogram_results[0]
+        return histogram_results[0]
     else:
-        # Return the best (optimal) histogram
+        # Return the best histogram (optimal in terms of interpretability)
+        # There is only one best histogram, so we return the first one we find
         for r in reversed(histogram_results):
             if r.is_best:
                 return r
         # Fallback to finest granularity if no best is marked
+        # It is assumed to be the best because it is the finest granularity
         return histogram_results[-1]
 
 

src/khisto/core/backend.py

@@ -11,13 +11,16 @@
 import subprocess
 import tempfile
 from dataclasses import dataclass, field
-from typing import Any, Optional
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
-from numpy.typing import NDArray
 
 from khisto import KHISTO_BIN_DIR, logger
 
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
 
 @dataclass
 class _HistogramPayload:
@@ -68,18 +71,18 @@ class _KhistoOutput:
 
     tool: str = ""
     version: str = ""
-    bestHistogram: Optional[_HistogramPayload] = None
-    histogramSeries: Optional[_SeriesPayload] = None
+    bestHistogram: _HistogramPayload = field(default_factory=_HistogramPayload)
+    histogramSeries: _SeriesPayload = field(default_factory=_SeriesPayload)
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> _KhistoOutput:
-        best = data.get("bestHistogram")
-        series = data.get("histogramSeries")
+        if "bestHistogram" not in data or "histogramSeries" not in data:
+            raise ValueError("Missing required fields: bestHistogram, histogramSeries")
         return cls(
             tool=data.get("tool", ""),
             version=data.get("version", ""),
-            bestHistogram=_HistogramPayload.from_dict(best) if best else None,
-            histogramSeries=_SeriesPayload.from_dict(series) if series else None,
+            bestHistogram=_HistogramPayload.from_dict(data["bestHistogram"]),
+            histogramSeries=_SeriesPayload.from_dict(data["histogramSeries"]),
         )
 
 
@@ -128,9 +131,42 @@ class HistogramResult:
     spike_interval_number: int = 0
     empty_interval_number: int = 0
 
+    def __post_init__(self) -> None:
+        """Validate the histogram data."""
+
+        # Verify all arrays have the same length
+        n_bins = {
+            len(self.lower_bounds),
+            len(self.upper_bounds),
+            len(self.frequencies),
+            len(self.probabilities),
+            len(self.densities),
+        }
+        if len(n_bins) != 1:
+            raise ValueError("all array sizes must be equal")
+        elif len(self.lower_bounds) < 1:
+            raise ValueError("all arrays must have at least one element")
+
+        if not np.all(self.lower_bounds <= self.upper_bounds):
+            raise ValueError("lower_bounds must be less than upper_bounds")
+        if not np.all(self.frequencies >= 0):
+            raise ValueError("frequencies must be non-negative")
+        if not np.all(self.probabilities >= 0):
+            raise ValueError("probabilities must be non-negative")
+        if not np.all(self.densities >= 0):
+            raise ValueError("densities must be non-negative")
+
+        # Verify lower_bounds are equal to upper_bounds for adjacent bins
+        print(self.lower_bounds, self.upper_bounds)
+        if not np.all(self.lower_bounds[1:] == self.upper_bounds[:-1]):
+            raise ValueError(
+                "lower_bounds must be equal to upper_bounds for adjacent bins"
+            )
+
     @property
     def bin_edges(self) -> NDArray[np.float64]:
-        """Return bin edges array (n_bins + 1 values)."""
+        """Return bin edges array (n_bins + 1 values).
+        lower_bounds and upper_bounds are equal for adjacent bins."""
         return np.concatenate([self.lower_bounds, [self.upper_bounds[-1]]])
 
     @property
@@ -148,18 +184,6 @@ def __len__(self) -> int:
         return len(self.lower_bounds)
 
 
-def _to_result(h: _HistogramPayload, **kwargs: Any) -> HistogramResult:
-    """Convert a JSON histogram payload to a HistogramResult."""
-    return HistogramResult(
-        lower_bounds=np.asarray(h.lowerBounds, dtype=np.float64),
-        upper_bounds=np.asarray(h.upperBounds, dtype=np.float64),
-        frequencies=np.asarray(h.frequencies, dtype=np.int64),
-        probabilities=np.asarray(h.probabilities, dtype=np.float64),
-        densities=np.asarray(h.densities, dtype=np.float64),
-        **kwargs,
-    )
-
-
 def _format_runtime_error(
     summary: str, cmd: list[str], details: str | None = None
 ) -> str:
@@ -170,21 +194,21 @@ def _format_runtime_error(
     return message
 
 
-def _process_histogram_file(
-    file_path: str,
-) -> list[HistogramResult]:
+def _process_histogram_file(file_path: Path) -> list[HistogramResult]:
     """Process exploratory JSON generated by khisto CLI."""
-    with open(file_path, "r") as temp_output_file:
-        khisto_output: _KhistoOutput = _KhistoOutput.from_dict(
-            json.load(temp_output_file)
-        )
+    with open(file_path, "r") as file:
+        khisto_output: _KhistoOutput = _KhistoOutput.from_dict(json.load(file))
 
     histogram_series = khisto_output.histogramSeries
     best_idx = histogram_series.interpretableHistogramNumber - 1
 
     return [
-        _to_result(
-            h,
+        HistogramResult(
+            lower_bounds=np.asarray(h.lowerBounds, dtype=np.float64),
+            upper_bounds=np.asarray(h.upperBounds, dtype=np.float64),
+            frequencies=np.asarray(h.frequencies, dtype=np.int64),
+            probabilities=np.asarray(h.probabilities, dtype=np.float64),
+            densities=np.asarray(h.densities, dtype=np.float64),
             is_best=(i == best_idx),
             granularity=histogram_series.granularities[i],
             level=histogram_series.levels[i],
@@ -268,7 +292,7 @@ def compute_histograms(x: np.ndarray) -> list[HistogramResult]:
             raise RuntimeError(message) from e
 
         try:
-            return _process_histogram_file(temp_output_file.name)
+            return _process_histogram_file(Path(temp_output_file.name))
         except json.JSONDecodeError as e:
             message = _format_runtime_error(
                 "khisto produced invalid JSON output",

src/khisto/matplotlib/hist.py

@@ -8,9 +8,8 @@
 
 from typing import TYPE_CHECKING, Any, Literal, Optional
 
-import numpy as np
-
 import matplotlib.pyplot as plt
+import numpy as np
 from matplotlib.axes import Axes
 
 from khisto.array import histogram as khisto_histogram
@@ -36,7 +35,7 @@ def _apply_cumulative(
     hist_values: NDArray[np.float64],
     bin_edges: NDArray[np.float64],
     *,
-    density: bool,
+    density: bool = False,
     reverse: bool = False,
 ) -> NDArray[np.float64]:
     """Accumulate histogram values using matplotlib-compatible semantics."""