aptapy 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

aptapy/_version.py

@@ -1 +1 @@
-__version__ = "0.3.1"
+__version__ = "0.4.0"

aptapy/hist.py

@@ -17,13 +17,17 @@
 """
 
 from abc import ABC, abstractmethod
-from typing import List, Sequence
+from typing import List, Sequence, Tuple
 
 import numpy as np
 
 from .plotting import matplotlib, plt, setup_axes
 from .typing_ import ArrayLike
 
+__all__ = [
+    "Histogram1d",
+    "Histogram2d",
+]
 
 class AbstractHistogram(ABC):
 
@@ -93,6 +97,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 +270,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 +308,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 +321,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/modeling.py

@@ -23,17 +23,31 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from itertools import chain
 from numbers import Number
-from typing import Callable, Iterator, Sequence, Tuple
+from typing import Callable, Dict, Iterator, Sequence, Tuple
 
 import matplotlib.pyplot as plt
 import numpy as np
 import uncertainties
+from scipy.integrate import quad
 from scipy.optimize import curve_fit
+from scipy.special import erf
 from scipy.stats import chi2
 
 from .hist import Histogram1d
 from .typing_ import ArrayLike
 
+__all__ = [
+    "Constant",
+    "Line",
+    "Quadratic",
+    "PowerLaw",
+    "Exponential",
+    "Gaussian",
+    "Erf",
+    "ErfInverse",
+]
+
+# pylint: disable=too-many-lines
 
 class Format(str, enum.Enum):
 
@@ -277,6 +291,17 @@ class FitStatus:
         self.pvalue = None
         self.fit_range = None
 
+    def valid(self) -> bool:
+        """Return True if the fit status is valid, i.e., if the chisquare,
+        dof, and pvalue are all set.
+
+        Returns
+        -------
+        valid : bool
+            True if the fit status is valid.
+        """
+        return self.chisquare is not None and self.dof is not None and self.pvalue is not None
+
     def update(self, chisquare: float, dof: int = None) -> None:
         """Update the fit status, i.e., set the chisquare and calculate the
         corresponding p-value.
@@ -316,10 +341,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.
@@ -776,7 +801,7 @@ class AbstractFitModelBase(ABC):
             The formatted string.
         """
         text = f"{self.name()}\n"
-        if self.status is not None:
+        if self.status.valid():
             text = f"{text}{format(self.status, spec)}\n"
         for parameter in self:
             text = f"{text}{format(parameter, spec)}\n"
@@ -807,13 +832,47 @@ class AbstractFitModel(AbstractFitModelBase):
         """
         super().__init__()
         self._parameters = []
-        for name, value in self.__class__.__dict__.items():
-            if isinstance(value, FitParameter):
-                parameter = value.copy(name)
-                # Note we also set one instance attribute for each parameter so
-                # that we can use the notation model.parameter
-                setattr(self, name, parameter)
-                self._parameters.append(parameter)
+        # Note we cannot loop over self.__dict__.items() here, as that would
+        # only return the members defined in the actual class, and not the
+        # inherited ones.
+        for name, value in self.__class__._parameter_dict().items():
+            parameter = value.copy(name)
+            # Note we also set one instance attribute for each parameter so
+            # that we can use the notation model.parameter
+            setattr(self, name, parameter)
+            self._parameters.append(parameter)
+
+    @classmethod
+    def _parameter_dict(cls) -> Dict[str, FitParameter]:
+        """Return a dictionary of all the FitParameter objects defined in the class
+        and its base classes.
+
+        This is a subtle one, as what we really want, here, is all members of a class
+        (including inherited ones) that are of a specific type (FitParameter), in the
+        order they were defined. All of these thing are instrumental to make the
+        fit model work, so we need to be careful.
+
+        Also note the we are looping over the MRO in reverse order, so that we
+        preserve the order of definition of the parameters, even when they are
+        inherited from base classes. If a parameter is re-defined in a derived class,
+        the derived class definition takes precedence, as we are using a dictionary
+        to collect the parameters.
+
+        Arguments
+        ---------
+        cls : type
+            The class to inspect.
+
+        Returns
+        -------
+        param_dict : dict
+            A dictionary mapping parameter names to their FitParameter objects.
+        """
+        param_dict = {}
+        for base in reversed(cls.__mro__):
+            param_dict.update({name: value for name, value in base.__dict__.items() if
+                               isinstance(value, FitParameter)})
+        return param_dict
 
     def __len__(self) -> int:
         """Return the `total` number of fit parameters in the model.
@@ -832,6 +891,46 @@ class AbstractFitModel(AbstractFitModelBase):
             raise TypeError(f"{other} is not a fit model")
         return FitModelSum(self, other)
 
+    def quadrature(self, xmin: float, xmax: float) -> float:
+        """Calculate the integral of the model between xmin and xmax using
+        numerical integration.
+
+        Arguments
+        ---------
+        xmin : float
+            The minimum value of the independent variable to integrate over.
+
+        xmax : float
+            The maximum value of the independent variable to integrate over.
+
+        Returns
+        -------
+        integral : float
+            The integral of the model between xmin and xmax.
+        """
+        value, _ = quad(self, xmin, xmax)
+        return value
+
+    def integral(self, xmin: float, xmax: float) -> float:
+        """Default implementation of the integral of the model between xmin and xmax.
+        Subclasses can (and are encouraged to) overload this method with an
+        analytical implementation, when available.
+
+        Arguments
+        ---------
+        xmin : float
+            The minimum value of the independent variable to integrate over.
+
+        xmax : float
+            The maximum value of the independent variable to integrate over.
+
+        Returns
+        -------
+        integral : float
+            The integral of the model between xmin and xmax.
+        """
+        return self.quadrature(xmin, xmax)
+
 
 class FitModelSum(AbstractFitModelBase):
 
@@ -878,6 +977,26 @@ class FitModelSum(AbstractFitModelBase):
             cursor += len(component)
         return value
 
+    def integral(self, xmin: float, xmax: float) -> float:
+        """Calculate the integral of the model between xmin and xmax.
+
+        This is implemented as the sum of the integrals of the components.
+
+        Arguments
+        ---------
+        xmin : float
+            The minimum value of the independent variable to integrate over.
+
+        xmax : float
+            The maximum value of the independent variable to integrate over.
+
+        Returns
+        -------
+        integral : float
+            The integral of the model between xmin and xmax.
+        """
+        return sum(component.integral(xmin, xmax) for component in self._components)
+
     def plot(self, xmin: float = None, xmax: float = None, num_points: int = 200) -> None:
         """Overloaded method for plotting the model.
         """
@@ -931,8 +1050,13 @@ class Constant(AbstractFitModel):
     @staticmethod
     def evaluate(x: ArrayLike, value: float) -> ArrayLike:
         # pylint: disable=arguments-differ
+        if isinstance(x, Number):
+            return value
         return np.full(x.shape, value)
 
+    def integral(self, xmin: float, xmax: float) -> float:
+        return self.value.value * (xmax - xmin)
+
 
 class Line(AbstractFitModel):
 
@@ -947,6 +1071,29 @@ class Line(AbstractFitModel):
         # pylint: disable=arguments-differ
         return slope * x + intercept
 
+    def integral(self, xmin: float, xmax: float) -> float:
+        slope, intercept = self.parameter_values()
+        return 0.5 * slope * (xmax**2 - xmin**2) + intercept * (xmax - xmin)
+
+
+class Quadratic(AbstractFitModel):
+
+    """Quadratic model.
+    """
+
+    a = FitParameter(1.)
+    b = FitParameter(1.)
+    c = FitParameter(0.)
+
+    @staticmethod
+    def evaluate(x: ArrayLike, a: float, b: float, c: float) -> ArrayLike:
+        # pylint: disable=arguments-differ
+        return a * x**2 + b * x + c
+
+    def integral(self, xmin: float, xmax: float) -> float:
+        a, b, c = self.parameter_values()
+        return a * (xmax**3 - xmin**3) / 3. + b * (xmax**2 - xmin**2) / 2. + c * (xmax - xmin)
+
 
 class PowerLaw(AbstractFitModel):
 
@@ -954,33 +1101,88 @@ class PowerLaw(AbstractFitModel):
     """
 
     prefactor = FitParameter(1.)
-    index = FitParameter(-1.)
+    index = FitParameter(-2.)
 
     @staticmethod
     def evaluate(x: ArrayLike, prefactor: float, index: float) -> ArrayLike:
         # pylint: disable=arguments-differ
         return prefactor * x**index
 
+    def integral(self, xmin: float, xmax: float) -> float:
+        prefactor, index = self.parameter_values()
+        if index == -1.:
+            return prefactor * np.log(xmax / xmin)
+        return prefactor / (index + 1.) * (xmax**(index + 1.) - xmin**(index + 1.))
 
-class Gaussian(AbstractFitModel):
+    def default_plotting_range(self) -> Tuple[float, float]:
+        return (0.1, 10.)
 
-    """Gaussian model.
+    def plot(self, xmin: float = None, xmax: float = None, num_points: int = 200) -> None:
+        super().plot(xmin, xmax, num_points)
+        plt.xscale("log")
+        plt.yscale("log")
+
+
+class Exponential(AbstractFitModel):
+
+    """Exponential model.
+    """
+
+    prefactor = FitParameter(1.)
+    scale = FitParameter(1.)
+
+    @staticmethod
+    def evaluate(x: ArrayLike, prefactor: float, scale: float) -> ArrayLike:
+        # pylint: disable=arguments-differ
+        return prefactor * np.exp(-x / scale)
+
+    def integral(self, xmin: float, xmax: float) -> float:
+        prefactor, scale = self.parameter_values()
+        return prefactor * scale * (np.exp(-xmin / scale) - np.exp(-xmax / scale))
+
+    def default_plotting_range(self, scale_factor: int = 5) -> Tuple[float, float]:
+        return (0., scale_factor * self.scale.value)
+
+
+class _GaussianBase(AbstractFitModel):
+
+    """Common base class for Gaussian-like models.
+
+    This provides a couple of convenience methods that are useful for all the
+    models derived from a gaussian (e.g., the gaussian itself, the error function,
+    and its inverse). Note that, for the right method to be picked up,
+    subclasses should derive from this class *before* deriving from
+    AbstractFitModel, so that the method resolution order (MRO) works as expected.
+
+    Note the evaluate() method is not implemented here, which means that the class
+    cannot be instantiated directly.
     """
 
     prefactor = FitParameter(1.)
     mean = FitParameter(0.)
     sigma = FitParameter(1., minimum=0.)
 
+    # A few useful constants.
+    _SQRT2 = np.sqrt(2.)
     _NORM_CONSTANT = 1. / np.sqrt(2. * np.pi)
     _SIGMA_TO_FWHM = 2. * np.sqrt(2. * np.log(2.))
 
-    @staticmethod
-    def evaluate(x: ArrayLike, prefactor: float, mean: float, sigma: float) -> ArrayLike:
-        # pylint: disable=arguments-differ
-        z = (x - mean) / sigma
-        return prefactor * Gaussian._NORM_CONSTANT / sigma * np.exp(-0.5 * z**2.)
-
     def default_plotting_range(self, num_sigma: int = 5) -> Tuple[float, float]:
+        """Convenience function to return a default plotting range for all the
+        models derived from a gaussian (e.g., the gaussian itself, the error
+        function, and its inverse).
+
+        Arguments
+        ---------
+        num_sigma : int, optional
+            The number of sigmas to use for the plotting range (default 5).
+
+        Returns
+        -------
+        Tuple[float, float]
+            The default plotting range for the model.
+        """
+        # pylint: disable=no-member
         mean, half_width = self.mean.value, num_sigma * self.sigma.value
         return (mean - half_width, mean + half_width)
 
@@ -992,4 +1194,46 @@ class Gaussian(AbstractFitModel):
         fwhm : uncertainties.ufloat
             The FWHM of the gaussian.
         """
+        # pylint: disable=no-member
         return self.sigma.ufloat() * self._SIGMA_TO_FWHM
+
+
+class Gaussian(_GaussianBase):
+
+    """Gaussian model.
+    """
+
+    @staticmethod
+    def evaluate(x: ArrayLike, prefactor: float, mean: float, sigma: float) -> ArrayLike:
+        # pylint: disable=arguments-differ
+        z = (x - mean) / sigma
+        return prefactor * _GaussianBase._NORM_CONSTANT / sigma * np.exp(-0.5 * z**2.)
+
+    def integral(self, xmin: float, xmax: float) -> float:
+        prefactor, mean, sigma = self.parameter_values()
+        zmin = (xmin - mean) / (sigma * self._SQRT2)
+        zmax = (xmax - mean) / (sigma * self._SQRT2)
+        return prefactor * 0.5 * (erf(zmax) - erf(zmin))
+
+
+class Erf(_GaussianBase):
+
+    """Error function model.
+    """
+
+    @staticmethod
+    def evaluate(x: ArrayLike, prefactor: float, mean: float, sigma: float) -> ArrayLike:
+        # pylint: disable=arguments-differ
+        z = (x - mean) / sigma
+        return prefactor * 0.5 * (1. + erf(z / _GaussianBase._SQRT2))
+
+
+class ErfInverse(_GaussianBase):
+
+    """Inverse error function model.
+    """
+
+    @staticmethod
+    def evaluate(x: ArrayLike, prefactor: float, mean: float, sigma: float) -> ArrayLike:
+        # pylint: disable=arguments-differ
+        return prefactor - Erf.evaluate(x, prefactor, mean, sigma)

{aptapy-0.3.1.dist-info → aptapy-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aptapy
-Version: 0.3.1
+Version: 0.4.0
 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
@@ -713,7 +713,6 @@ Description-Content-Type: text/markdown
 ![License](https://img.shields.io/github/license/lucabaldini/aptapy.svg)
 [![CI](https://github.com/lucabaldini/aptapy/actions/workflows/ci.yml/badge.svg)](https://github.com/lucabaldini/aptapy/actions/workflows/ci.yml)
 [![Docs](https://github.com/lucabaldini/aptapy/actions/workflows/docs.yml/badge.svg)](https://github.com/lucabaldini/aptapy/actions/workflows/docs.yml)
-[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://lucabaldini.github.io/aptapy/)
 ![GitHub last commit](https://img.shields.io/github/last-commit/lucabaldini/aptapy)
 
 [![Ceasefire Now](https://badge.techforpalestine.org/default)](https://techforpalestine.org/learn-more)

aptapy-0.4.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+aptapy/__init__.py,sha256=a7Au1ukdeJbjiIZ-UL-qZE1xk-d2WnKKkoqjg_0SzqA,1707
+aptapy/_version.py,sha256=42STGor_9nKYXumfeV5tiyD_M8VdcddX7CEexmibPBk,22
+aptapy/hist.py,sha256=pUiXtBGKrFo38ZgoiZ1WQSZSSatQb62RJw83mI9i05k,11586
+aptapy/modeling.py,sha256=-6t9H3nNsxiEQwW40_yXFVj8oGlsdN6DsEkJa19Rtus,40717
+aptapy/plotting.py,sha256=p9YNdrcFcTimRCtoXcV3zORaEd4EfMtsDd4ETxGKKHM,27483
+aptapy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aptapy/strip.py,sha256=qGsVXWp-Dz-lz7KQxktMifUTNkSxh8ZQwYme8_bealQ,3026
+aptapy/typing_.py,sha256=JIbEqKI8kn_fd90yDt0JmI1AojjmLhAEB_1RfMFxLx4,807
+aptapy-0.4.0.dist-info/METADATA,sha256=eHypCTZ4_IBaHkepwTUOgNhVMrJP5Rj_MNsQ1ibGtnM,42696
+aptapy-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+aptapy-0.4.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+aptapy-0.4.0.dist-info/RECORD,,

aptapy-0.3.1.dist-info/RECORD

@@ -1,12 +0,0 @@
-aptapy/__init__.py,sha256=a7Au1ukdeJbjiIZ-UL-qZE1xk-d2WnKKkoqjg_0SzqA,1707
-aptapy/_version.py,sha256=r4xAFihOf72W9TD-lpMi6ntWSTKTP2SlzKP1ytkjRbI,22
-aptapy/hist.py,sha256=jvHULR2lW_gyoemNaRI-vpqhFqmLLCB319CaKjwU69E,9752
-aptapy/modeling.py,sha256=mHHHFMYmMuXTRQD2yR1XLM6E4KaBk8md7Z7dDp5ReD8,32566
-aptapy/plotting.py,sha256=p9YNdrcFcTimRCtoXcV3zORaEd4EfMtsDd4ETxGKKHM,27483
-aptapy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-aptapy/strip.py,sha256=qGsVXWp-Dz-lz7KQxktMifUTNkSxh8ZQwYme8_bealQ,3026
-aptapy/typing_.py,sha256=JIbEqKI8kn_fd90yDt0JmI1AojjmLhAEB_1RfMFxLx4,807
-aptapy-0.3.1.dist-info/METADATA,sha256=KZP-aljwTsIKUi-1nE-X9ZfIxc44ijFhKCkoyK0EXjY,42796
-aptapy-0.3.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-aptapy-0.3.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-aptapy-0.3.1.dist-info/RECORD,,