Refactor: histogram function and related tests for improved density handling

- Updated the  parameter in the  function to be optional, defaulting to None for backward compatibility.
- Enhanced documentation for the  function to clarify behavior of the  parameter.
- Modified the  function in the matplotlib interface to default to density=True, aligning with the new histogram behavior.
- Removed unsupported cumulative histogram functionality from the  function.
- Updated tests for the histogram to reflect changes in density handling and removed tests for cumulative histograms.

Author: ElouenGinat

docs/API.md

@@ -23,22 +23,20 @@ khisto.histogram(
     a: ArrayLike,
     range: Optional[tuple[float, float]] = None,
     max_bins: Optional[int] = None,
-    density: bool = False,
+    density: Optional[bool] = None,
 ) -> tuple[NDArray[np.floating], NDArray[np.floating]]
 ```
 
 Compute an optimal histogram using the Khiops binning algorithm.
 
-Drop-in replacement for [`numpy.histogram`](https://numpy.org/doc/stable/reference/generated/numpy.histogram.html), using optimal binning instead of fixed-width bins.
-
 #### Parameters
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `a` | `ArrayLike` | required | Input data. The histogram is computed over the flattened array. |
 | `range` | `tuple[float, float]` | `None` | Lower and upper range of the bins. Values outside are ignored. |
 | `max_bins` | `int` | `None` | Maximum number of bins. If not provided, the optimal number is determined automatically. |
-| `density` | `bool` | `False` | If `True`, return probability density values; otherwise return counts. |
+| `density` | `bool` | `None` | If `False` or `None`, return counts; if `True`, return probability density values. |
 
 #### Returns
 
@@ -49,7 +47,7 @@ Drop-in replacement for [`numpy.histogram`](https://numpy.org/doc/stable/referen
 
 #### See Also
 
-- [`numpy.histogram`](https://numpy.org/doc/stable/reference/generated/numpy.histogram.html) — NumPy's standard histogram function.
+- [`numpy.histogram`](https://numpy.org/doc/stable/reference/generated/numpy.histogram.html) — NumPy's histogram function (`bins` and `weights` parameters are not supported).
 
 #### Examples
 
@@ -206,37 +204,34 @@ khisto.matplotlib.hist(
     x: ArrayLike,
     range: Optional[tuple[float, float]] = None,
     max_bins: Optional[int] = None,
-    density: bool = False,
+    density: bool = True,
     ax: Optional[Axes] = None,
     **kwargs,
 ) -> tuple[NDArray[np.floating], NDArray[np.floating], Any]
 ```
 
 Compute and plot an optimal histogram.
 
-Drop-in replacement for [`matplotlib.pyplot.hist`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.hist.html) using Khisto's optimal binning algorithm.
-
 #### Parameters
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `x` | `ArrayLike` | required | Input data. |
-| `range` | `tuple[float, float]` | `None` | Lower and upper range of the bins. Values outside are ignored. |
+| `x` | `ArrayLike` | required | Input data. The histogram is computed over the flattened array. |
 | `max_bins` | `int` | `None` | Maximum number of bins. If `None`, uses optimal binning. |
-| `ax` | `Axes` | `None` | Axes to plot on. If `None`, uses current axes. |
-| `**kwargs` | | | Other parameters passed to matplotlib. See [`matplotlib.pyplot.hist`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.hist.html). |
+
+Other parameters are passed to matplotlib. See [`matplotlib.pyplot.hist`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.hist.html) for styling options.
 
 #### Returns
 
 | Return | Type | Description |
 |--------|------|-------------|
-| `n` | `NDArray[np.floating]` | The values of the histogram bins. |
+| `n` | `NDArray[np.floating]` | The values of the histogram bins (probability density by default). |
 | `bins` | `NDArray[np.floating]` | The bin edges. |
 | `patches` | `Any` | Container of individual artists (bars or StepPatch). |
 
 #### See Also
 
-- [`matplotlib.pyplot.hist`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.hist.html) — Full documentation of supported parameters.
+- [`matplotlib.pyplot.hist`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.hist.html) — Matplotlib's histogram function (`bins`, `weights`, `cumulative`, and stacked/multiple dataset features are not supported).
 - [`khisto.histogram`](#histogram) — Underlying histogram computation.
 
 #### Examples
@@ -250,19 +245,20 @@ from khisto.matplotlib import hist
 
 data = np.random.normal(0, 1, 1000)
 
+# Default is density=True
 n, bins, patches = hist(data)
 plt.xlabel('Value')
-plt.ylabel('Count')
+plt.ylabel('Density')
 plt.title('Optimal Histogram')
 plt.show()
 ```
 
-Density plot:
+Frequency plot:
 
 ```python
-n, bins, patches = hist(data, density=True)
+n, bins, patches = hist(data, density=False)
 plt.xlabel('Value')
-plt.ylabel('Density')
+plt.ylabel('Count')
 plt.show()
 ```
 

sandbox/khisto_demo.ipynb

@@ -55,58 +55,43 @@ def histogram(
     a: ArrayLike,
     range: Optional[tuple[float, float]] = None,
     max_bins: Optional[int] = None,
-    density: bool = False,
+    density: Optional[bool] = None,
 ) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
     """Compute an optimal histogram using the Khiops binning algorithm.
 
-    This function is a drop-in replacement for numpy.histogram, but uses
-    optimal binning instead of equal-width bins.
-
     Parameters
     ----------
     a : array_like
         Input data. The histogram is computed over the flattened array.
     range : tuple of (float, float), optional
         The lower and upper range of the bins. Values outside the range are
-        ignored. The first element of the range must be less than or equal
-        to the second. If not provided, the range is simply
-        ``(a.min(), a.max())``.
+        ignored. If not provided, the range is ``(a.min(), a.max())``.
     max_bins : int, optional
         Maximum number of bins. If not provided, the algorithm selects
         the optimal number of bins automatically.
-    density : bool, default False
-        If True, return probability density values; otherwise return counts.
+    density : bool, optional
+        If False, the result will contain the number of samples in each bin.
+        If True, the result is the value of the probability density function
+        at the bin, normalized such that the integral over the range is 1.
+        Default is None, which behaves as False for backwards compatibility.
 
     Returns
     -------
     hist : ndarray
-        The values of the histogram. If density is True, these are
-        probability density values; otherwise, they are counts.
+        The values of the histogram.
     bin_edges : ndarray
         The bin edges (length(hist) + 1).
 
     See Also
     --------
-    numpy.histogram : NumPy's standard histogram function.
+    numpy.histogram : NumPy's histogram function (``bins`` and ``weights``
+        parameters are not supported).
 
     Notes
     -----
     Unlike numpy.histogram, this function uses optimal binning which may
     produce bins of unequal width. The bins are determined by the Khiops
     algorithm to best represent the underlying data distribution.
-
-    Examples
-    --------
-    >>> import numpy as np
-    >>> from khisto.array import histogram
-    >>> data = np.random.normal(0, 1, 1000)
-    >>> hist, bin_edges = histogram(data)
-    >>> # Density histogram
-    >>> density_hist, edges = histogram(data, density=True)
-    >>> # Constrained number of bins
-    >>> hist, edges = histogram(data, max_bins=10)
-    >>> # Filter to a specific range (values outside are ignored)
-    >>> hist, edges = histogram(data, range=(-2, 2))
     """
     # Convert to numpy array and flatten
     arr = np.asarray(a, dtype=np.float64).ravel()
@@ -119,6 +104,7 @@ def histogram(
     results = compute_histogram(arr)
     result = _select_histogram(results, max_bins=max_bins)
 
+    # Treat None as False for backwards compatibility (like NumPy)
     if density:
         return result.density.copy(), result.bin_edges.copy()
     else:

src/khisto/array/histogram/api.py

@@ -19,8 +19,7 @@ def hist(
     x: ArrayLike,
     range: Optional[tuple[float, float]] = None,
     max_bins: Optional[int] = None,
-    density: bool = False,
-    cumulative: bool = False,
+    density: bool = True,
     histtype: str = "bar",
     orientation: Literal["vertical", "horizontal"] = "vertical",
     log: bool = False,
@@ -35,45 +34,30 @@ def hist(
 ) -> tuple[np.ndarray, np.ndarray, Any]:
     """Compute and plot an optimal histogram.
 
-    Drop-in replacement for `matplotlib.pyplot.hist` using Khisto's optimal
-    binning algorithm. Most parameters match matplotlib's hist function.
-
     Parameters
     ----------
     x : array_like
-        Input data.
-    range : tuple of (float, float), optional
-        The lower and upper range of the bins. Values outside the range are
-        ignored. If not provided, the range is ``(x.min(), x.max())``.
+        Input data. The histogram is computed over the flattened array.
     max_bins : int, optional
-        Maximum number of bins. If None, uses optimal binning.
-    ax : Axes, optional
-        Axes to plot on. If None, uses current axes.
-    **kwargs
-        Other parameters are passed to matplotlib. See `matplotlib.pyplot.hist`.
+        Maximum number of bins. If not provided, the algorithm selects
+        the optimal number of bins automatically.
 
     Returns
     -------
     n : ndarray
-        Histogram values.
+        Histogram values (probability density by default).
     bins : ndarray
         Bin edges.
     patches
         Container with the bar patches.
 
     See Also
     --------
-    matplotlib.pyplot.hist : Full documentation of supported parameters.
-    khisto.histogram : Underlying histogram computation.
-
-    Examples
-    --------
-    >>> from khisto.matplotlib import hist
-    >>> hist(data)
-    >>> hist(data, density=True, max_bins=10)
+    matplotlib.pyplot.hist : Matplotlib's histogram function. The ``bins``,
+        ``weights``, ``cumulative``, and stacked/multiple dataset features
+        are not supported.
+    khisto.array.histogram : Underlying histogram computation.
     """
-    if cumulative:
-        raise NotImplementedError("Cumulative histograms are not yet supported")
 
     # Get axes
     if ax is None:

src/khisto/matplotlib/hist.py

@@ -119,7 +119,7 @@ def test_histogram_with_max_bins(self, normal_data):
 
     def test_histogram_density_parameter(self, normal_data):
         """Test density parameter behavior."""
-        # Without density (counts)
+        # Without density (counts) - explicit False same as None default
         hist_counts, edges1 = histogram(normal_data, density=False)
 
         # With density

tests/array/test_histogram.py

@@ -42,9 +42,9 @@ def test_without_ax(self, normal_data):
         plt.close()
 
     def test_density_histogram(self, normal_data):
-        """Test density histogram."""
+        """Test density histogram (default behavior)."""
         fig, ax = plt.subplots()
-        n, bins, patches = hist(normal_data, density=True, ax=ax)
+        n, bins, patches = hist(normal_data, ax=ax)
 
         # Density should integrate to 1
         bin_widths = np.diff(bins)
@@ -53,7 +53,7 @@ def test_density_histogram(self, normal_data):
         plt.close(fig)
 
     def test_frequency_histogram(self, normal_data):
-        """Test frequency histogram."""
+        """Test frequency histogram (explicit density=False)."""
         fig, ax = plt.subplots()
         n, bins, patches = hist(normal_data, density=False, ax=ax)
 
@@ -119,11 +119,6 @@ def test_stepfilled_histtype(self, normal_data):
         assert isinstance(n, np.ndarray)
         plt.close(fig)
 
-    def test_cumulative_not_supported(self, normal_data):
-        """Test that cumulative raises NotImplementedError."""
-        with pytest.raises(NotImplementedError):
-            hist(normal_data, cumulative=True)
-
 
 class TestHistReturnValues:
     """Test return values match matplotlib.pyplot.hist interface."""