Merge pull request #12 from KhiopsML/json

Refactor histogram computation: remove cli_adapter, add backend tests

Author: ElouenGinat

docs/core/index.rst

@@ -11,4 +11,4 @@ Main Modules
   :recursive:
   :nosignatures:
 
-  cli_adapter
+  backend

sandbox/khisto_demo.ipynb

@@ -453,7 +453,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": null,
    "id": "1190f8aa",
    "metadata": {},
    "outputs": [
@@ -470,26 +470,26 @@
       "  Granularity 3: 4 bins\n",
       "  Granularity 4: 7 bins\n",
       "  Granularity 5: 8 bins\n",
-      "  Granularity 6: 7 bins ← BEST\n"
+      "  Granularity 7: 7 bins ← BEST\n"
      ]
     }
    ],
    "source": [
-    "from khisto.core import compute_histogram\n",
+    "from khisto.core import compute_histograms\n",
     "\n",
     "# Get all granularity levels\n",
-    "results = compute_histogram(data)\n",
+    "results = compute_histograms(data)\n",
     "\n",
     "print(f\"Number of granularity levels: {len(results)}\")\n",
     "print(\"\\nGranularity levels:\")\n",
     "for r in results:\n",
     "    marker = \" ← BEST\" if r.is_best else \"\"\n",
-    "    print(f\"  Granularity {r.granularity}: {len(r.frequency)} bins{marker}\")"
+    "    print(f\"  Granularity {r.granularity}: {len(r.frequencies)} bins{marker}\")"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": null,
    "id": "bf2ba150",
    "metadata": {},
    "outputs": [
@@ -512,8 +512,8 @@
     "\n",
     "for i, r in enumerate(results[:n_levels]):\n",
     "    ax = axes[i]\n",
-    "    ax.stairs(r.frequency, r.bin_edges, fill=True, alpha=0.7)\n",
-    "    title = f\"Granularity {r.granularity} ({len(r.frequency)} bins)\"\n",
+    "    ax.stairs(r.frequencies, r.bin_edges, fill=True, alpha=0.7)\n",
+    "    title = f\"Granularity {r.granularity} ({len(r.frequencies)} bins)\"\n",
     "    if r.is_best:\n",
     "        title += \" ★ BEST\"\n",
     "        ax.set_facecolor(\"#ffffee\")\n",

src/khisto/array/histogram/api.py

@@ -11,11 +11,11 @@
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
 
-from khisto.core import HistogramResult, compute_histogram
+from khisto.core import HistogramResult, compute_histograms
 
 
 def _select_histogram(
-    results: list[HistogramResult],
+    histogram_results: list[HistogramResult],
     max_bins: Optional[int] = None,
 ) -> HistogramResult:
     """Select the appropriate histogram from the list of results.
@@ -35,38 +35,20 @@ def _select_histogram(
     if max_bins is not None:
         # Find the finest granularity that respects max_bins
         selected = None
-        for r in results:
+        for r in histogram_results:
             if len(r) <= max_bins:
                 selected = r
             else:
                 break
         # If no histogram respects the constraint, use the coarsest one
-        return selected if selected is not None else results[0]
+        return selected if selected is not None else histogram_results[0]
     else:
         # Return the best (optimal) histogram
-        for r in results:
+        for r in reversed(histogram_results):
             if r.is_best:
                 return r
         # Fallback to finest granularity if no best is marked
-        return results[-1]
-
-
-def _apply_cumulative(
-    hist_values: NDArray[np.float64],
-    bin_edges: NDArray[np.float64],
-    *,
-    density: bool,
-    reverse: bool = False,
-) -> NDArray[np.float64]:
-    """Accumulate histogram values using matplotlib-compatible semantics."""
-    if density:
-        source_values = hist_values * np.diff(bin_edges)
-    else:
-        source_values = hist_values
-
-    if reverse:
-        return np.cumsum(source_values[::-1])[::-1]
-    return np.cumsum(source_values)
+        return histogram_results[-1]
 
 
 def histogram(
@@ -125,15 +107,20 @@ def histogram(
     """
     arr = np.asarray(a, dtype=np.float64).flatten()
 
+    if max_bins is not None and max_bins <= 0:
+        raise ValueError("max_bins must be a positive integer or None.")
+
     # Filter values by range if specified
     if range is not None:
         min_val, max_val = range
         arr = arr[(arr >= min_val) & (arr <= max_val)]
 
-    results = compute_histogram(arr)
-    result = _select_histogram(results, max_bins=max_bins)
+    histogram_results = compute_histograms(arr)
+    histogram_result = _select_histogram(histogram_results, max_bins=max_bins)
 
     if density:
-        return result.density.copy(), result.bin_edges.copy()
+        return histogram_result.densities.copy(), histogram_result.bin_edges.copy()
     else:
-        return result.frequency.astype(np.float64), result.bin_edges.copy()
+        return histogram_result.frequencies.astype(
+            np.float64
+        ), histogram_result.bin_edges.copy()

src/khisto/core/__init__.py

@@ -2,6 +2,6 @@
 # This software is distributed under the BSD 3-Clause-clear License, the text of which is available
 # at https://spdx.org/licenses/BSD-3-Clause-Clear.html or see the "LICENSE" file for more details.
 
-from .cli_adapter import compute_histogram, HistogramResult
+from .backend import compute_histograms, HistogramResult
 
-__all__ = ["compute_histogram", "HistogramResult"]
+__all__ = ["compute_histograms", "HistogramResult"]