aptapy 0.3.1__tar.gz → 0.3.2__tar.gz

{aptapy-0.3.1 → aptapy-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aptapy
-Version: 0.3.1
+Version: 0.3.2
 Summary: Statistical tools for online monitoring and analysis
 Project-URL: Homepage, https://github.com/lucabaldini/aptapy
 Project-URL: Issues, https://github.com/lucabaldini/aptapy/issues

{aptapy-0.3.1 → aptapy-0.3.2}/docs/release_notes.rst

@@ -4,9 +4,24 @@ Release notes
 =============
 
 
+Version 0.3.2 (2025-10-09)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Adding binned_statistics method in AbstractHistogram base class to calculate
+  statistics from histogram bins
+* Adds extensive test coverage in both 1D and 2D histogram test functions with
+  statistical validation
+
+* Pull requests merged:
+
+  - https://github.com/lucabaldini/aptapy/pull/6
+
+
 Version 0.3.1 (2025-10-09)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+* Minor changes.
+
 
 Version 0.3.0 (2025-10-08)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

aptapy-0.3.2/src/aptapy/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.2"

{aptapy-0.3.1 → aptapy-0.3.2}/src/aptapy/hist.py

@@ -17,7 +17,7 @@
 """
 
 from abc import ABC, abstractmethod
-from typing import List, Sequence
+from typing import List, Sequence, Tuple
 
 import numpy as np
 
@@ -93,6 +93,43 @@ class AbstractHistogram(ABC):
         """
         return np.diff(self._edges[axis])
 
+    def binned_statistics(self, axis: int = 0) -> Tuple[float, float]:
+        """Return the mean and standard deviation along a specific axis, based
+        on the binned data.
+
+        .. note::
+
+           This is a crude estimate of the underlying statistics that might be
+           useful for monitoring purposes, but should not be relied upon for
+           quantitative analysis.
+
+           This is not the same as computing the mean and standard deviation of
+           the unbinned data that filled the histogram, as some information is
+           lost in the binning process.
+
+           In addition, note that we are not applying any bias correction to
+           the standard deviation, as we are assuming that the histogram is
+           filled with a sufficiently large number of entries. (In most circumstances
+           the effect should be smaller than that of the binning itself.)
+
+        Arguments
+        ---------
+        axis : int
+            the axis along which to compute the statistics.
+
+        Returns
+        -------
+        mean : float
+            the mean value along the specified axis.
+        stddev : float
+            the standard deviation along the specified axis.
+        """
+        values = self.bin_centers(axis)
+        weights = self.content.sum(axis=tuple(i for i in range(self.content.ndim) if i != axis))
+        mean = np.average(values, weights=weights)
+        variance = np.average((values - mean)**2, weights=weights)
+        return float(mean), float(np.sqrt(variance))
+
     def fill(self, *values: ArrayLike, weights: ArrayLike = None) -> "AbstractHistogram":
         """Fill the histogram from unbinned data.
 
@@ -229,10 +266,18 @@ class Histogram1d(AbstractHistogram):
         """
         # If we are not explicitly providing a label at plotting time, use
         # the one attached to the histogram, if any.
-        kwargs.setdefault('label', self.label)
+        kwargs.setdefault("label", f"{self}")
         axes.hist(self.bin_centers(0), self._edges[0], weights=self.content, **kwargs)
         setup_axes(axes, xlabel=self.axis_labels[0], ylabel=self.axis_labels[1])
 
+    def __str__(self) -> str:
+        """String formatting.
+        """
+        mean, rms = self.binned_statistics()
+        text = self.label or self.__class__.__name__
+        text = f"{text}\nMean: {mean:g}\nRMS: {rms:g}"
+        return text
+
 
 class Histogram2d(AbstractHistogram):
 
@@ -259,10 +304,10 @@ class Histogram2d(AbstractHistogram):
         the text label for the z axis (default: "Entries/bin").
     """
 
-    DEFAULT_PLOT_OPTIONS = dict(cmap=plt.get_cmap('hot'))
+    DEFAULT_PLOT_OPTIONS = dict(cmap=plt.get_cmap("hot"))
 
     def __init__(self, xedges, yedges, label: str = None, xlabel: str = None,
-                 ylabel: str = None, zlabel: str = 'Entries/bin') -> None:
+                 ylabel: str = None, zlabel: str = "Entries/bin") -> None:
         """Constructor.
         """
         super().__init__((xedges, yedges), label, [xlabel, ylabel, zlabel])
@@ -272,9 +317,9 @@ class Histogram2d(AbstractHistogram):
         """
         # pylint: disable=arguments-differ
         if logz:
-            vmin = kwargs.pop('vmin', None)
-            vmax = kwargs.pop('vmax', None)
-            kwargs.setdefault('norm', matplotlib.colors.LogNorm(vmin, vmax))
+            vmin = kwargs.pop("vmin", None)
+            vmax = kwargs.pop("vmax", None)
+            kwargs.setdefault("norm", matplotlib.colors.LogNorm(vmin, vmax))
         mappable = axes.pcolormesh(*self._edges, self.content.T, **kwargs)
         plt.colorbar(mappable, ax=axes, label=self.axis_labels[2])
         setup_axes(axes, xlabel=self.axis_labels[0], ylabel=self.axis_labels[1])

{aptapy-0.3.1 → aptapy-0.3.2}/src/aptapy/modeling.py

@@ -316,10 +316,10 @@ class FitStatus:
         if self.chisquare is None:
             return "N/A"
         if spec.endswith(Format.LATEX):
-            return f"$\\chi^2$ = {self.chisquare:.2f} / {self.dof} dof"
+            return f"$\\chi^2$: {self.chisquare:.2f} / {self.dof} dof"
         if spec.endswith(Format.PRETTY):
-            return f"χ² = {self.chisquare:.2f} / {self.dof} dof"
-        return f"chisquare = {self.chisquare:.2f} / {self.dof} dof"
+            return f"χ²: {self.chisquare:.2f} / {self.dof} dof"
+        return f"chisquare: {self.chisquare:.2f} / {self.dof} dof"
 
     def __str__(self) -> str:
         """String formatting.

{aptapy-0.3.1 → aptapy-0.3.2}/tests/test_hist.py

@@ -101,22 +101,43 @@ def test_plotting1d(size: int = 100000):
     plt.figure(inspect.currentframe().f_code.co_name)
     # Create the first histogram. This has no label attached, so we will have to
     # provide one at plotting time, if we want to have a corresponding legend entry.
+    mean = 0.
+    sigma = 1.
     hist1 = Histogram1d(np.linspace(-5., 5., 100), xlabel='x')
-    hist1.fill(_RNG.normal(size=size))
+    hist1.fill(_RNG.normal(size=size, loc=mean, scale=sigma))
     hist1.plot(label='Standard histogram')
+    m, s = hist1.binned_statistics()
+    # Rough checks on the binned statistics---we want the mean to be within 10
+    # sigma/sqrt(N) and the stddev to be within 2% of the true value.
+    # (Note the binning has an effect on the actual values, so we cannot
+    # expect perfect agreement.)
+    assert abs((m - mean) / sigma * np.sqrt(size)) < 10.
+    assert abs(s / sigma - 1.) < 0.02
+
     # Create a second histogram, this time with a label---this should have a
     # proper entry in the legend automatically.
+    mean = 1.
+    sigma = 1.5
     hist2 = Histogram1d(np.linspace(-5., 5., 100), label='Offset histogram')
-    hist2.fill(_RNG.normal(size=size, loc=1.))
+    hist2.fill(_RNG.normal(size=size, loc=mean, scale=sigma))
     hist2.plot()
+    m, s = hist2.binned_statistics()
+    assert abs((m - mean) / sigma * np.sqrt(size)) < 10.
+    assert abs(s / sigma - 1.) < 0.02
+
     # And this one should end up with no legend entry, as it has no label
+    mean = -1.
+    sigma = 0.5
     hist3 = Histogram1d(np.linspace(-5., 5., 100))
-    hist3.fill(_RNG.normal(size=size // 2, loc=-1.))
+    hist3.fill(_RNG.normal(size=size, loc=mean, scale=sigma))
     hist3.plot()
+    m, s = hist3.binned_statistics()
+    assert abs((m - mean) / sigma * np.sqrt(size)) < 10.
+    assert abs(s / sigma - 1.) < 0.02
     plt.legend()
 
 
-def test_plotting2d(size: int = 100000):
+def test_plotting2d(size: int = 100000, x0: float = 1., y0: float = -1.):
     """Test plotting.
     """
     plt.figure(inspect.currentframe().f_code.co_name)
@@ -124,8 +145,14 @@ def test_plotting2d(size: int = 100000):
     hist = Histogram2d(edges, edges, 'x', 'y')
     # Note we are adding different offsets to x and y so that we can see
     # the effect on the plot.
-    hist.fill(_RNG.normal(size=size) + 1., _RNG.normal(size=size) - 1.)
+    hist.fill(_RNG.normal(size=size, loc=x0), _RNG.normal(size=size, loc=y0))
     hist.plot()
+    mx, sx = hist.binned_statistics(0)
+    my, sy = hist.binned_statistics(1)
+    assert abs((mx - x0) * np.sqrt(size)) < 10.
+    assert abs((my - y0) * np.sqrt(size)) < 10.
+    assert abs(sx - 1.) < 0.02
+    assert abs(sy - 1.) < 0.02
     plt.gca().set_aspect('equal')
 
 

{aptapy-0.3.1 → aptapy-0.3.2}/tests/test_modeling.py

@@ -26,7 +26,7 @@ from aptapy.plotting import plt
 
 _RNG = np.random.default_rng(313)
 
-TEST_HISTOGRAM = Histogram1d(np.linspace(-5., 5., 100), label="Test data")
+TEST_HISTOGRAM = Histogram1d(np.linspace(-5., 5., 100), label="Random data")
 TEST_HISTOGRAM.fill(_RNG.normal(size=100000))
 NUM_SIGMA = 4.
 

aptapy-0.3.1/src/aptapy/_version.py

@@ -1 +0,0 @@
-__version__ = "0.3.1"