aptapy 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

aptapy/_version.py

@@ -1 +1 @@
-__version__ = "0.2.0"
+__version__ = "0.3.0"

aptapy/hist.py

@@ -34,13 +34,13 @@ class AbstractHistogram(ABC):
     edges : n-dimensional sequence of arrays
         the bin edges on the different axes.
 
-    labels : sequence of strings
-        the text labels for the different axes.
+    axis_labels : sequence of strings
+        the text labels for the different histogram axes.
     """
 
     DEFAULT_PLOT_OPTIONS = {}
 
-    def __init__(self, edges: Sequence[np.ndarray], labels: List[str]) -> None:
+    def __init__(self, edges: Sequence[np.ndarray], label: str, axis_labels: List[str]) -> None:
         """Constructor.
         """
         # Edges are fixed once and forever, so we create a copy. Also, no matter
@@ -56,14 +56,15 @@ class AbstractHistogram(ABC):
                 raise ValueError(f"Bin edges {item} have less than 2 entries.")
             if np.any(np.diff(item) <= 0):
                 raise ValueError(f"Bin edges {item} not strictly increasing.")
-        if labels is not None and len(labels) > self._num_axes + 1:
-            raise ValueError(f"Too many labels {labels} for {self._num_axes} axes.")
+        if axis_labels is not None and len(axis_labels) > self._num_axes + 1:
+            raise ValueError(f"Too many axis labels {axis_labels} for {self._num_axes} axes.")
 
         # Go ahead and create all the necessary data structures.
         self._shape = tuple(item.size - 1 for item in self._edges)
         self._sumw = np.zeros(self._shape, dtype=float)
         self._sumw2 = np.zeros(self._shape, dtype=float)
-        self._labels = labels
+        self.label = label
+        self.axis_labels = axis_labels
 
     @property
     def content(self) -> np.ndarray:
@@ -115,7 +116,7 @@ class AbstractHistogram(ABC):
         # Note we really need the * in the constructor, here, as the abstract
         # base class is never instantiated, and the arguments are unpacked in the
         # constructors of all the derived classes.
-        histogram = self.__class__(*self._edges, *self._labels)
+        histogram = self.__class__(*self._edges, self.label, *self.axis_labels)
         histogram._sumw = self._sumw.copy()
         histogram._sumw2 = self._sumw2.copy()
         return histogram
@@ -185,33 +186,86 @@ class AbstractHistogram(ABC):
 class Histogram1d(AbstractHistogram):
 
     """One-dimensional histogram.
+
+    Arguments
+    ---------
+    edges : 1-dimensional array
+        the bin edges.
+
+    label : str
+        overall label for the histogram (if defined, this will be used in the
+        legend by default).
+
+    xlabel : str
+        the text label for the x axis.
+
+    ylabel : str
+        the text label for the y axis (default: "Entries/bin").
     """
 
     DEFAULT_PLOT_OPTIONS = dict(linewidth=1.25, alpha=0.4, histtype="stepfilled")
 
-    def __init__(self, xedges: np.ndarray, xlabel: str = "", ylabel: str = "Entries/bin") -> None:
+    def __init__(self, xedges: np.ndarray, label: str = None, xlabel: str = None,
+                 ylabel: str = "Entries/bin") -> None:
         """Constructor.
         """
-        super().__init__((xedges, ), [xlabel, ylabel])
+        super().__init__((xedges, ), label, [xlabel, ylabel])
+
+    def area(self) -> float:
+        """Return the total area under the histogram.
+
+        This is potentially useful when fitting a model to the histogram, e.g.,
+        to freeze the prefactor of a gaussian to the histogram normalization.
+
+        Returns
+        -------
+        area : float
+            The total area under the histogram.
+        """
+        return (self.content * self.bin_widths()).sum()
 
     def _do_plot(self, axes: matplotlib.axes._axes.Axes, **kwargs) -> None:
         """Overloaded make_plot() method.
         """
+        # 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)
         axes.hist(self.bin_centers(0), self._edges[0], weights=self.content, **kwargs)
-        setup_axes(axes, xlabel=self._labels[0], ylabel=self._labels[1])
+        setup_axes(axes, xlabel=self.axis_labels[0], ylabel=self.axis_labels[1])
 
 
 class Histogram2d(AbstractHistogram):
 
     """Two-dimensional histogram.
+
+    Arguments
+    ---------
+    xedges : 1-dimensional array
+        the bin edges on the x axis.
+
+    yedges : 1-dimensional array
+        the bin edges on the y axis.
+
+    label : str
+        overall label for the histogram
+
+    xlabel : str
+        the text label for the x axis.
+
+    ylabel : str
+        the text label for the y axis.
+
+    zlabel : str
+        the text label for the z axis (default: "Entries/bin").
     """
 
     DEFAULT_PLOT_OPTIONS = dict(cmap=plt.get_cmap('hot'))
 
-    def __init__(self, xedges, yedges, xlabel='', ylabel='', zlabel='Entries/bin') -> None:
+    def __init__(self, xedges, yedges, label: str = None, xlabel: str = None,
+                 ylabel: str = None, zlabel: str = 'Entries/bin') -> None:
         """Constructor.
         """
-        super().__init__((xedges, yedges), [xlabel, ylabel, zlabel])
+        super().__init__((xedges, yedges), label, [xlabel, ylabel, zlabel])
 
     def _do_plot(self, axes: matplotlib.axes._axes.Axes, logz: bool = False, **kwargs) -> None:
         """Overloaded make_plot() method.
@@ -222,5 +276,5 @@ class Histogram2d(AbstractHistogram):
             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._labels[2])
-        setup_axes(axes, xlabel=self._labels[0], ylabel=self._labels[1])
+        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

@@ -21,15 +21,18 @@ import functools
 import inspect
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
+from itertools import chain
 from numbers import Number
-from typing import Iterator, Tuple
+from typing import Callable, Iterator, Sequence, Tuple
 
 import matplotlib.pyplot as plt
 import numpy as np
 import uncertainties
 from scipy.optimize import curve_fit
+from scipy.stats import chi2
 
-from aptapy.typing_ import ArrayLike
+from .hist import Histogram1d
+from .typing_ import ArrayLike
 
 
 class Format(str, enum.Enum):
@@ -63,6 +66,11 @@ class FitParameter:
 
         We are wrapping this into a property because, arguably, the parameter name is
         the only thing we never, ever want to change after the fact.
+
+        Returns
+        -------
+        name : str
+            The parameter name.
         """
         return self._name
 
@@ -72,11 +80,21 @@ class FitParameter:
 
         We are wrapping this into a property because we interact with this member
         via the freeze() and thaw() methods.
+
+        Returns
+        -------
+        frozen : bool
+            True if the parameter is frozen.
         """
         return self._frozen
 
     def is_bound(self) -> bool:
         """Return True if the parameter is bounded.
+
+        Returns
+        -------
+        bounded : bool
+            True if the parameter is bounded.
         """
         return not np.isinf(self.minimum) or not np.isinf(self.maximum)
 
@@ -94,7 +112,12 @@ class FitParameter:
         Arguments
         ---------
         name : str
-            The name for the new FitParameter object.
+            The name for the new :class:`FitParameter` object.
+
+        Returns
+        -------
+        parameter : FitParameter
+            The new :class:`FitParameter` object.
         """
         return self.__class__(self.value, name, minimum=self.minimum, maximum=self.maximum)
 
@@ -132,11 +155,70 @@ class FitParameter:
 
     def ufloat(self) -> uncertainties.ufloat:
         """Return the parameter value and error as a ufloat object.
+
+        Returns
+        -------
+        ufloat : uncertainties.ufloat
+            The parameter value and error as a ufloat object.
         """
         return uncertainties.ufloat(self.value, self.error)
 
+    def pull(self, expected: float) -> float:
+        """Calculate the pull of the parameter with respect to a given expected value.
+
+        Arguments
+        ---------
+        expected : float
+            The expected value for the parameter.
+
+        Returns
+        -------
+        pull : float
+            The pull of the parameter with respect to the expected value, defined as
+            (value - expected) / error.
+
+        Raises
+        ------
+        RuntimeError
+            If the parameter has no error associated to it.
+        """
+        if self.error is None or self.error <= 0.:
+            raise RuntimeError(f"Cannot calculate pull for parameter {self.name} "
+                               "with no error")
+        return (self.value - expected) / self.error
+
+    def compatible_with(self, expected: float, num_sigma: float = 3.) -> bool:
+        """Check if the parameter is compatible with an expected value within
+        n_sigma.
+
+        Arguments
+        ---------
+        expected : float
+            The expected value for the parameter.
+
+        num_sigma : float, optional
+            The number of sigmas to use for the compatibility check (default 3).
+
+        Returns
+        -------
+        compatible : bool
+            True if the parameter is compatible with the expected value within
+            num_sigma.
+        """
+        return abs(self.pull(expected)) <= num_sigma
+
     def __format__(self, spec: str) -> str:
         """String formatting.
+
+        Arguments
+        ---------
+        spec : str
+            The format specification.
+
+        Returns
+        -------
+        text : str
+            The formatted string.
         """
         # Keep in mind Python passes an empty string explicitly when you call
         # f"{parameter}", so we can't really assign a default value to spec.
@@ -145,8 +227,10 @@ class FitParameter:
             if spec.endswith(Format.LATEX):
                 param = f"${param}$"
         else:
-            spec = spec.rstrip(Format.PRETTY).rstrip(Format.LATEX)
-            param = format(self.value, spec)
+            # Note in this case we are not passing the format spec to format(), as
+            # the only thing we can do in absence of an error is to use the
+            # Python default formatting.
+            param = format(self.value, "g")
         text = f"{self._name.title()}: {param}"
         info = []
         if self._frozen:
@@ -165,6 +249,11 @@ class FitParameter:
         This is meant to provide a more human-readable version of the parameter formatting
         than the default ``__repr__`` implementation from the dataclass decorator, and it
         is what is used in the actual printout of the fit parameters from a fit.
+
+        Returns
+        -------
+        text : str
+            The formatted string.
         """
         return format(self, Format.PRETTY)
 
@@ -177,7 +266,7 @@ class FitStatus:
 
     chisquare: float = None
     dof: int = None
-    # pvalue: float = None
+    pvalue: float = None
     fit_range: Tuple[float, float] = None
 
     def reset(self) -> None:
@@ -185,10 +274,44 @@ class FitStatus:
         """
         self.chisquare = None
         self.dof = None
+        self.pvalue = None
         self.fit_range = 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.
+
+        Arguments
+        ---------
+        chisquare : float
+            The chisquare of the fit.
+
+        dof : int, optional
+            The number of degrees of freedom of the fit.
+        """
+        self.chisquare = chisquare
+        if dof is not None:
+            self.dof = dof
+        self.pvalue = chi2.sf(self.chisquare, self.dof)
+        # chi2.sf() returns the survival function, i.e., 1 - cdf. If the survival
+        # function is > 0.5, we flip it around, so that we always report the smallest
+        # tail, and the pvalue is the probability of obtaining a chisquare value more
+        # `extreme` of the one we got.
+        if self.pvalue > 0.5:
+            self.pvalue = 1. - self.pvalue
+
     def __format__(self, spec: str) -> str:
         """String formatting.
+
+        Arguments
+        ---------
+        spec : str
+            The format specification.
+
+        Returns
+        -------
+        text : str
+            The formatted string.
         """
         if self.chisquare is None:
             return "N/A"
@@ -200,119 +323,227 @@ class FitStatus:
 
     def __str__(self) -> str:
         """String formatting.
+
+        Returns
+        -------
+        text : str
+            The formatted string.
         """
         return format(self, Format.PRETTY)
 
 
-class AbstractFitModel(ABC):
+class AbstractFitModelBase(ABC):
 
-    """Abstract base class for a fit model.
+    """Abstract base class for all the fit classes.
+
+    This is a acting a base class for both simple fit models and for composite models
+    (e.g., sums of simple ones).
     """
 
     def __init__(self) -> None:
         """Constructor.
-
-        Here we loop over the FitParameter objects defined at the class level, and
-        create copies that are attached to the instance, so that the latter has its
-        own state.
         """
-        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)
-        # Fit status object holding all the additional information from the fit.
         self.status = FitStatus()
 
-    def name(self) -> str:
-        """Return the model name.
-        """
-        return self.__class__.__name__
-
+    @abstractmethod
     def __len__(self) -> int:
-        """Overloaded method.
-        """
-        return len(self._parameters)
+        """Delegated to concrete classes: this should return the `total` number of
+        fit parameters (not only the free ones) in the model.
 
-    def __iter__(self) -> Iterator[FitParameter]:
-        """Iteration protocol.
-        """
-        return iter(self._parameters)
+        .. note::
 
-    def parameter_values(self) -> Tuple[float]:
-        """Return the current parameter values.
-        """
-        return tuple(parameter.value for parameter in self)
+           I still have mixed feelings about this method, as it is not clear whether
+           we are returning the number of parameters, or the number of free parameters,
+           but I think it is fine, as long as we document it. Also note that, while
+           the number of parameters is fixed once and for all for simple models,
+           it can change at runtime for composite models.
 
-    def free_parameters(self) -> Tuple[FitParameter]:
-        """Return the list of free parameters.
+        Returns
+        -------
+        n : int
+            The total number of fit parameters in the model.
         """
-        return tuple(parameter for parameter in self if not parameter.frozen)
 
-    def free_parameter_values(self) -> Tuple[float]:
-        """Return the current parameter values.
+    @abstractmethod
+    def __iter__(self) -> Iterator[FitParameter]:
+        """Delegated to concrete classes: this should return an iterator over `all`
+        the fit parameters in the model.
+
+        Returns
+        -------
+        iterator : Iterator[FitParameter]
+            An iterator over all the fit parameters in the model.
         """
-        return tuple(parameter.value for parameter in self.free_parameters())
 
     @staticmethod
     @abstractmethod
-    def evaluate(x: ArrayLike, *parameter_values: Tuple[float]) -> ArrayLike:
-        """Evaluate the model at a given value (or set of values) of the independent variable,
-        for a given set of model parameters.
+    def evaluate(x: ArrayLike, *parameter_values: Sequence[float]) -> ArrayLike:
+        """Evaluate the model at a given set of parameter values.
 
         Arguments
         ---------
         x : array_like
             The value(s) of the independent variable.
 
-        params : tuple of float
+        parameter_values : sequence of float
             The value of the model parameters.
+
+        Returns
+        -------
+        y : array_like
+            The value(s) of the model at the given value(s) of the independent variable
+            for a given set of parameter values.
         """
 
+    def name(self) -> str:
+        """Return the model name, e.g., for legends.
+
+        Note this can be reimplemented in concrete subclasses, but it should provide
+        a sensible default value in most circumstances.
+
+        Returns
+        -------
+        name : str
+            The model name.
+        """
+        return self.__class__.__name__
+
     def __call__(self, x: ArrayLike) -> ArrayLike:
         """Evaluate the model at the current value of the parameters.
+
+        Arguments
+        ---------
+        x : array_like
+            The value(s) of the independent variable.
+
+        Returns
+        -------
+        y : array_like
+            The value(s) of the model at the given value(s) of the independent variable
+            for the current set of parameter values.
         """
         return self.evaluate(x, *self.parameter_values())
 
-    def set_parameters(self, *values: float) -> None:
-        """Set the values for all the parameters.
-        """
-        for parameter, value in zip(self, values):
-            parameter.value = value
+    def init_parameters(self, xdata: ArrayLike, ydata: ArrayLike, sigma: ArrayLike) -> None:
+        """Optional hook to change the current parameter values of the model, prior
+        to a fit, based on the input data.
+
+        Arguments
+        ---------
+        xdata : array_like
+            The input values of the independent variable.
+
+        ydata : array_like
+            The input values of the dependent variable.
 
-    def init_parameters(self, x: ArrayLike, y: ArrayLike, sigma: ArrayLike) -> None:
-        """Optional: override in subclasses if needed.
+        sigma : array_like
+            The input uncertainties on the dependent variable.
         """
         # pylint: disable=unused-argument
         return
 
-    def _update_parameters(self, popt: np.ndarray, pcov: np.ndarray) -> None:
-        """Update the model parameters based on the output of the ``curve_fit()`` call.
+    def parameter_values(self) -> Tuple[float]:
+        """Return the current parameter values.
+
+        Note this only relies on the __iter__() method, so it works both for simple
+        and composite models.
+
+        Returns
+        -------
+        values : tuple of float
+            The current parameter values.
         """
-        for parameter, value, error in zip(self.free_parameters(), popt, np.sqrt(pcov.diagonal())):
-            parameter.value = value
-            parameter.error = error
+        return tuple(parameter.value for parameter in self)
+
+    def free_parameters(self) -> Tuple[FitParameter]:
+        """Return the list of free parameters.
+
+        Note this only relies on the __iter__() method, so it works both for simple
+        and composite models.
+
+        Returns
+        -------
+        parameters : tuple of FitParameter
+            The list of free parameters.
+        """
+        return tuple(parameter for parameter in self if not parameter.frozen)
+
+    def free_parameter_values(self) -> Tuple[float]:
+        """Return the current parameter values.
+
+        Returns
+        -------
+        values : tuple of float
+            The current parameter values.
+        """
+        return tuple(parameter.value for parameter in self.free_parameters())
 
     def bounds(self) -> Tuple[ArrayLike, ArrayLike]:
         """Return the bounds on the fit parameters in a form that can be use by the
         fitting method.
+
+        Returns
+        -------
+        bounds : 2-tuple of array_like
+            The lower and upper bounds on the (free) fit parameters.
         """
         free_parameters = self.free_parameters()
         return (tuple(parameter.minimum for parameter in free_parameters),
                 tuple(parameter.maximum for parameter in free_parameters))
 
-    def calculate_chisqure(self, xdata: np.ndarray, ydata: np.ndarray, sigma) -> float:
+    def update_parameters(self, popt: np.ndarray, pcov: np.ndarray) -> None:
+        """Update the model parameters based on the output of the ``curve_fit()`` call.
+
+        Arguments
+        ---------
+        popt : array_like
+            The optimal values for the fit parameters.
+
+        pcov : array_like
+            The covariance matrix for the fit parameters.
+        """
+        for parameter, value, error in zip(self.free_parameters(), popt, np.sqrt(pcov.diagonal())):
+            parameter.value = value
+            parameter.error = error
+
+    def calculate_chisquare(self, xdata: np.ndarray, ydata: np.ndarray, sigma) -> float:
         """Calculate the chisquare of the fit to some input data with the current
         model parameters.
+
+        Arguments
+        ---------
+        xdata : array_like
+            The input values of the independent variable.
+
+        ydata : array_like
+            The input values of the dependent variable.
+
+        sigma : array_like
+            The input uncertainties on the dependent variable.
+
+        Returns
+        -------
+        chisquare : float
+            The chisquare of the fit.
         """
         return float((((ydata - self(xdata)) / sigma)**2.).sum())
 
     @staticmethod
-    def freeze(model_function, **constraints):
+    def freeze(model_function, **constraints) -> Callable:
         """Freeze a subset of the model parameters.
+
+        Arguments
+        ---------
+        model_function : callable
+            The model function to freeze parameters for.
+
+        constraints : dict
+            The parameters to freeze, as keyword arguments.
+
+        Returns
+        -------
+        wrapper : callable
+            A wrapper around the model function with the given parameters frozen.
         """
         if not constraints:
             return model_function
@@ -363,8 +594,36 @@ class AbstractFitModel(ABC):
 
     def fit(self, xdata: ArrayLike, ydata: ArrayLike, p0: ArrayLike = None,
             sigma: ArrayLike = 1., absolute_sigma: bool = False, xmin: float = -np.inf,
-            xmax: float = np.inf, **kwargs) -> None:
+            xmax: float = np.inf, **kwargs) -> FitStatus:
         """Fit a series of points.
+
+        Arguments
+        ---------
+        xdata : array_like
+            The input values of the independent variable.
+
+        ydata : array_like
+            The input values of the dependent variable.
+
+        p0 : array_like, optional
+            The initial values for the fit parameters.
+
+        sigma : array_like
+            The input uncertainties on the dependent variable.
+
+        absolute_sigma : bool, optional (default False)
+            See the `curve_fit()` documentation for details.
+
+        xmin : float, optional (default -inf)
+            The minimum value of the independent variable to fit.
+
+        xmax : float, optional (default inf)
+            The maximum value of the independent variable to fit.
+
+        Returns
+        -------
+        status : FitStatus
+            The status of the fit.
         """
         # Reset the fit status.
         self.status.reset()
@@ -374,16 +633,21 @@ class AbstractFitModel(ABC):
         # the broadcast facilities.
         xdata = np.asarray(xdata)
         ydata = np.asarray(ydata)
+        if isinstance(sigma, Number):
+            sigma = np.full(ydata.shape, sigma)
+        sigma = np.asarray(sigma)
         # If we are fitting over a subrange, filter the input data.
         mask = np.logical_and(xdata >= xmin, xdata <= xmax)
+        # Also, filter out any points with non-positive uncertainties.
+        mask = np.logical_and(mask, sigma > 0.)
         # (And, since we are at it, make sure we have enough degrees of freedom.)
-        self.status.dof = int(mask.sum() - len(self))
+        self.status.dof = int(mask.sum() - len(self.free_parameters()))
         if self.status.dof < 0:
             raise RuntimeError(f"{self.name()} has no degrees of freedom")
         xdata = xdata[mask]
         ydata = ydata[mask]
-        if not isinstance(sigma, Number):
-            sigma = np.asarray(sigma)[mask]
+        sigma = sigma[mask]
+
         # Cache the fit range for later use.
         self.status.fit_range = (xdata.min(), xdata.max())
 
@@ -399,16 +663,38 @@ class AbstractFitModel(ABC):
         model = self.freeze(self.evaluate, **constraints)
         args = model, xdata, ydata, p0, sigma, absolute_sigma, True, self.bounds()
         popt, pcov = curve_fit(*args, **kwargs)
-        self._update_parameters(popt, pcov)
-        self.status.chisquare = self.calculate_chisqure(xdata, ydata, sigma)
+        self.update_parameters(popt, pcov)
+        self.status.update(self.calculate_chisquare(xdata, ydata, sigma))
         return self.status
 
+    def fit_histogram(self, histogram: Histogram1d, p0: ArrayLike = None, **kwargs) -> None:
+        """Convenience function for fitting a 1-dimensional histogram.
+
+        Arguments
+        ---------
+        histogram : Histogram1d
+            The histogram to fit.
+
+        p0 : array_like, optional
+            The initial values for the fit parameters.
+
+        kwargs : dict, optional
+            Additional keyword arguments passed to `fit()`.
+        """
+        args = histogram.bin_centers(), histogram.content, p0, histogram.errors
+        return self.fit(*args, **kwargs)
+
     def default_plotting_range(self) -> Tuple[float, float]:
         """Return the default plotting range for the model.
 
-        This can be reimplemnted in concrete models, and can be parameter-dependent
+        This can be reimplemented in concrete models, and can be parameter-dependent
         (e.g., for a gaussian we might want to plot within 5 sigma from the mean by
-        dafeault).
+        default).
+
+        Returns
+        -------
+        Tuple[float, float]
+            The default plotting range for the model.
         """
         return (0., 1.)
 
@@ -416,6 +702,22 @@ class AbstractFitModel(ABC):
                         fit_padding: float = 0.) -> Tuple[float, float]:
         """Convenience function trying to come up with the most sensible plot range
         for the model.
+
+        Arguments
+        ---------
+        xmin : float, optional
+            The minimum value of the independent variable to plot.
+
+        xmax : float, optional
+            The maximum value of the independent variable to plot.
+
+        fit_padding : float, optional
+            The amount of padding to add to the fit range.
+
+        Returns
+        -------
+        Tuple[float, float]
+            The plotting range for the model.
         """
         # If we have fitted the model to some data, we take the fit range and pad it
         # a little bit.
@@ -434,27 +736,191 @@ class AbstractFitModel(ABC):
             _xmax = xmax
         return (_xmin, _xmax)
 
-    def plot(self, xmin: float = None, xmax: float = None, num_points: int = 200) -> None:
+    def plot(self, xmin: float = None, xmax: float = None, num_points: int = 200) -> np.ndarray:
         """Plot the model.
+
+        Arguments
+        ---------
+        xmin : float, optional
+            The minimum value of the independent variable to plot.
+
+        xmax : float, optional
+            The maximum value of the independent variable to plot.
+
+        num_points : int, optional
+            The number of points to use for the plot.
+
+        Returns
+        -------
+        x : np.ndarray
+            The x values used for the plot, that can be used downstream to add
+            artists on the plot itself (e.g., composite models can use the same
+            grid to draw the components).
         """
         x = np.linspace(*self._plotting_range(xmin, xmax), num_points)
         y = self(x)
         plt.plot(x, y, label=format(self, Format.LATEX))
+        return x
 
     def __format__(self, spec: str) -> str:
         """String formatting.
-        """
-        text = f"{self.__class__.__name__} ({format(self.status, spec)})\n"
-        for parameter in self._parameters:
+
+        Arguments
+        ---------
+        spec : str
+            The format specification.
+
+        Returns
+        -------
+        text : str
+            The formatted string.
+        """
+        text = f"{self.name()}\n"
+        if self.status is not None:
+            text = f"{text}{format(self.status, spec)}\n"
+        for parameter in self:
             text = f"{text}{format(parameter, spec)}\n"
         return text.strip("\n")
 
     def __str__(self):
         """String formatting.
+
+        Returns
+        -------
+        text : str
+            The formatted string.
         """
         return format(self, Format.PRETTY)
 
 
+class AbstractFitModel(AbstractFitModelBase):
+
+    """Abstract base class for a fit model.
+    """
+
+    def __init__(self) -> None:
+        """Constructor.
+
+        Here we loop over the FitParameter objects defined at the class level, and
+        create copies that are attached to the instance, so that the latter has its
+        own state.
+        """
+        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)
+
+    def __len__(self) -> int:
+        """Return the `total` number of fit parameters in the model.
+        """
+        return len(self._parameters)
+
+    def __iter__(self) -> Iterator[FitParameter]:
+        """Iterate over `all` the model parameters.
+        """
+        return iter(self._parameters)
+
+    def __add__(self, other):
+        """Model sum.
+        """
+        if not isinstance(other, AbstractFitModel):
+            raise TypeError(f"{other} is not a fit model")
+        return FitModelSum(self, other)
+
+
+class FitModelSum(AbstractFitModelBase):
+
+    """Composite model representing the sum of an arbitrary number of simple models.
+
+    Arguments
+    ---------
+    components : sequence of AbstractFitModel
+        The components of the composite model.
+    """
+
+    def __init__(self, *components: AbstractFitModel) -> None:
+        """Constructor.
+        """
+        super().__init__()
+        self._components = components
+
+    def name(self) -> str:
+        """Return the model name.
+        """
+        return " + ".join(component.name() for component in self._components)
+
+    def __len__(self) -> int:
+        """Return the sum of `all` the fit parameters in the underlying models.
+        """
+        return sum(len(component) for component in self._components)
+
+    def __iter__(self) -> Iterator[FitParameter]:
+        """Iterate over `all` the parameters of the underlying components.
+        """
+        return chain(*self._components)
+
+    def evaluate(self, x: ArrayLike, *parameter_values) -> ArrayLike:
+        """Overloaded method for evaluating the model.
+
+        Note this is not a static method, as we need to access the list of components
+        to sum over.
+        """
+        # pylint: disable=arguments-differ
+        cursor = 0
+        value = np.zeros(x.shape)
+        for component in self._components:
+            value += component.evaluate(x, *parameter_values[cursor:cursor + len(component)])
+            cursor += len(component)
+        return value
+
+    def plot(self, xmin: float = None, xmax: float = None, num_points: int = 200) -> None:
+        """Overloaded method for plotting the model.
+        """
+        x = super().plot(xmin, xmax, num_points)
+        color = plt.gca().lines[-1].get_color()
+        for component in self._components:
+            y = component(x)
+            plt.plot(x, y, label=None, ls="--", color=color)
+
+    def __format__(self, spec: str) -> str:
+        """String formatting.
+
+        Arguments
+        ---------
+        spec : str
+            The format specification.
+
+        Returns
+        -------
+        text : str
+            The formatted string.
+        """
+        text = f"{self.name()}\n"
+        if self.status is not None:
+            text = f"{text}{format(self.status, spec)}\n"
+        for component in self._components:
+            text = f"{text}[{component.name()}]\n"
+            for parameter in component:
+                text = f"{text}{format(parameter, spec)}\n"
+        return text.strip("\n")
+
+    def __add__(self, other: AbstractFitModel) -> "FitModelSum":
+        """Implementation of the model sum (i.e., using the `+` operator).
+
+        Note that, in the spirit of keeping the interfaces as simple as possible,
+        we are not implementing in-place addition (i.e., `+=`), and we only
+        allow ``AbstractFitModel`` objects (not ``FitModelSum``) on the right
+        hand side, which is all is needed to support the sum of an arbitrary
+        number of models.
+        """
+        return self.__class__(*self._components, other)
+
+
 class Constant(AbstractFitModel):
 
     """Constant model.
@@ -465,7 +931,7 @@ class Constant(AbstractFitModel):
     @staticmethod
     def evaluate(x: ArrayLike, value: float) -> ArrayLike:
         # pylint: disable=arguments-differ
-        return np.full(value, x.shape)
+        return np.full(x.shape, value)
 
 
 class Line(AbstractFitModel):
@@ -503,13 +969,27 @@ class Gaussian(AbstractFitModel):
 
     prefactor = FitParameter(1.)
     mean = FitParameter(0.)
-    sigma = FitParameter(1.)
+    sigma = FitParameter(1., minimum=0.)
+
+    _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
-        return prefactor * np.exp(-0.5 * ((x - mean) / sigma) ** 2.)
+        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]:
         mean, half_width = self.mean.value, num_sigma * self.sigma.value
         return (mean - half_width, mean + half_width)
+
+    def fwhm(self) -> uncertainties.ufloat:
+        """Return the full-width at half-maximum (FWHM) of the gaussian.
+
+        Returns
+        -------
+        fwhm : uncertainties.ufloat
+            The FWHM of the gaussian.
+        """
+        return self.sigma.ufloat() * self._SIGMA_TO_FWHM

aptapy/plotting.py

@@ -84,11 +84,18 @@ def _set(key: str, value: Any):
         logger.warning(f"{exception}, skipping...")
 
 
-def configure() -> None:
+def configure(*args) -> None:
     """See https://matplotlib.org/stable/users/explain/customizing.html for more
     information.
+
+    .. note::
+
+       Note that this function can be used as a hook by Sphinx Gallery to
+       configure the plotting environment for each example, so that the matplotlib
+       configuration is consistent across all examples and is not reset each time.
+       This is the reason why the function signature includes unused arguments.
     """
-    # pylint:disable=too-many-statements
+    # pylint:disable=too-many-statements, unused-argument
 
     # Backends
     _set("interactive", False)

aptapy/strip.py

@@ -0,0 +1,92 @@
+# Copyright (C) 2025 Luca Baldini (luca.baldini@pi.infn.it)
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Strip charts.
+"""
+
+import collections
+from typing import Sequence
+
+import numpy as np
+
+from .plotting import plt, setup_axes
+
+
+class StripChart:
+
+    """Class describing a sliding strip chart, that is, a scatter plot where the
+    number of points is limited to a maximum, so that the thing acts essentially
+    as a sliding window, typically in time.
+
+    Arguments
+    ---------
+    max_length : int, optional
+        the maximum number of points to keep in the strip chart. If None (the default),
+        the number of points is unlimited.
+
+    label : str, optional
+        a text label for the data series (default is None).
+
+    xlabel : str, optional
+        the label for the x axis.
+
+    ylabel : str, optional
+        the label for the y axis.
+
+    datetime : bool, optional
+        if True, the x values are treated as POSIX timestamps and converted to
+        datetime objects for plotting purposes (default is False).
+    """
+
+    def __init__(self, max_length: int = None, label: str = '', xlabel: str = None,
+                 ylabel: str = None, datetime: bool = False) -> None:
+        """Constructor.
+        """
+        self.label = label
+        self.xlabel = xlabel
+        self.ylabel = ylabel
+        self._datetime = datetime
+        self.x = collections.deque(maxlen=max_length)
+        self.y = collections.deque(maxlen=max_length)
+
+    def clear(self) -> None:
+        """Reset the strip chart.
+        """
+        self.x.clear()
+        self.y.clear()
+
+    def append(self, x: float, y: float) -> None:
+        """Append a data point to the strip chart.
+        """
+        self.x.append(x)
+        self.y.append(y)
+
+    def extend(self, x: Sequence[float], y: Sequence[float]) -> None:
+        """Append multiple data points to the strip chart.
+        """
+        if len(x) != len(y):
+            raise ValueError("x and y must have the same length")
+        self.x.extend(x)
+        self.y.extend(y)
+
+    def plot(self, axes=None, **kwargs) -> None:
+        """Plot the strip chart.
+        """
+        kwargs.setdefault("label", self.label)
+        if axes is None:
+            axes = plt.gca()
+        x = np.array(self.x).astype('datetime64[s]') if self._datetime else self.x
+        axes.plot(x, self.y, **kwargs)
+        setup_axes(axes, xlabel=self.xlabel, ylabel=self.ylabel, grids=True)

{aptapy-0.2.0.dist-info → aptapy-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aptapy
-Version: 0.2.0
+Version: 0.3.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
@@ -694,9 +694,17 @@ Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: sphinx-gallery; extra == 'docs'
 Requires-Dist: sphinxawesome-theme; extra == 'docs'
 Description-Content-Type: text/markdown
 
 <img src="docs/_static/logo.png" alt="logo" width="175"/>
 
-Statistical tools for online monitoring and analysis
+![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/)
+[![Ceasefire Now](https://badge.techforpalestine.org/default)](https://techforpalestine.org/learn-more)
+
+Statistical tools for online monitoring and analysis.
+[Read more](https://lucabaldini.github.io/aptapy/).

aptapy-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+aptapy/__init__.py,sha256=a7Au1ukdeJbjiIZ-UL-qZE1xk-d2WnKKkoqjg_0SzqA,1707
+aptapy/_version.py,sha256=VrXpHDu3erkzwl_WXrqINBm9xWkcyUy53IQOj042dOs,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.0.dist-info/METADATA,sha256=ae7Q-HEWZCiZW8QjbAMNqCwZQVTFv52oH2n4J5tMRfg,42131
+aptapy-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+aptapy-0.3.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+aptapy-0.3.0.dist-info/RECORD,,

aptapy-0.2.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-aptapy/__init__.py,sha256=a7Au1ukdeJbjiIZ-UL-qZE1xk-d2WnKKkoqjg_0SzqA,1707
-aptapy/_version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
-aptapy/hist.py,sha256=5fiaYEnSQ7b_jSsZdRvXrIGr2vTMlW_55jkFpE8L3Sw,8158
-aptapy/modeling.py,sha256=V8DVfmwFyUfy9-YZXd9Hz5rlyGEy12xoyn-oJ4ss3W0,18236
-aptapy/plotting.py,sha256=ZixAVF83qIuITjzQJBUvMNCK-REilzyAt0vxgcMbCOk,27125
-aptapy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-aptapy/typing_.py,sha256=JIbEqKI8kn_fd90yDt0JmI1AojjmLhAEB_1RfMFxLx4,807
-aptapy-0.2.0.dist-info/METADATA,sha256=yvpj0nK8DKrbXcccDPqKeiruxJYAGEK0FYaIKa4UpS0,41456
-aptapy-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-aptapy-0.2.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-aptapy-0.2.0.dist-info/RECORD,,