aptapy 0.2.0__tar.gz → 0.3.0__tar.gz

{aptapy-0.2.0 → aptapy-0.3.0}/.gitignore

@@ -1,3 +1,7 @@
+# Custom files.
+docs/sg_execution_times.rst
+docs/auto_examples
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]
@@ -182,9 +186,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 

{aptapy-0.2.0 → aptapy-0.3.0}/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,10 @@
+<img src="docs/_static/logo.png" alt="logo" width="175"/>
+
+![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.2.0 → aptapy-0.3.0}/docs/conf.py

@@ -28,6 +28,7 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "sphinx_gallery.gen_gallery",
 ]
 autodoc_default_options = {
     "members": True,
@@ -37,6 +38,20 @@ autodoc_default_options = {
 }
 todo_include_todos = True
 
+
+sphinx_gallery_conf = {
+    "examples_dirs": ["examples"],      # source example scripts (relative to conf.py)
+    "gallery_dirs": ["auto_examples"],  # generated output (reST + images)
+    "filename_pattern": r".*",          # build all files in examples/
+    # Optional niceties:
+    "download_all_examples": False,
+    #"remove_config_comments": True,
+    # "backreferences_dir": "gen_modules/backreferences",
+    # "doc_module": ("yourpkg",),       # populate backrefs for your package API
+    # "thumbnail_size": (320, 240),
+    "reset_modules": ("matplotlib", "aptapy.plotting.configure"),
+}
+
 # Options for syntax highlighting.
 pygments_style = "default"
 pygments_dark_style = "default"

aptapy-0.3.0/docs/examples/GALLERY_HEADER.rst

@@ -0,0 +1,4 @@
+:orphan:
+
+Example gallery
+===============

aptapy-0.3.0/docs/examples/composite_fit.py

@@ -0,0 +1,28 @@
+"""
+Composite fit example
+=====================
+
+Composite fit with a Gaussian plus a straight line.
+"""
+
+# %%
+
+import numpy as np
+
+from aptapy.hist import Histogram1d
+from aptapy.modeling import Gaussian, Line
+from aptapy.plotting import plt
+
+hist = Histogram1d(np.linspace(-5., 5., 100), label="Random data", xlabel="z")
+# Fill with the sum of a gaussian...
+hist.fill(np.random.default_rng().normal(size=100000))
+# ... and a triangular distribution (this is done via the inverse transform method).
+hist.fill(5. - 10. * np.sqrt(1 - np.random.default_rng().random(100000)))
+hist.plot()
+
+model = Gaussian() + Line()
+model.fit_histogram(hist)
+print(model)
+model.plot()
+
+plt.legend()

aptapy-0.3.0/docs/examples/constrained_fit.py

@@ -0,0 +1,29 @@
+"""
+Constrained fit example
+=======================
+
+Gaussian fit to histogram data where the prefactor is frozen based on the
+histogram normalization.
+"""
+
+# %%
+
+import numpy as np
+
+from aptapy.hist import Histogram1d
+from aptapy.modeling import Gaussian
+from aptapy.plotting import plt
+
+hist = Histogram1d(np.linspace(-5., 5., 100), label="Random data", xlabel="z")
+hist.fill(np.random.default_rng().normal(size=100000))
+hist.plot()
+
+model = Gaussian()
+# Fix the prefactor to the histogram area---note this only works because the
+# Gaussian model is normalized to 1 over the full range when the prefactor is 1.
+model.prefactor.freeze(hist.area())
+model.fit_histogram(hist)
+print(model)
+model.plot()
+
+plt.legend()

aptapy-0.3.0/docs/examples/simple_fit.py

@@ -0,0 +1,25 @@
+"""
+Simple fit example
+==================
+
+Simple gaussian fit to histogram data.
+"""
+
+# %%
+
+import numpy as np
+
+from aptapy.hist import Histogram1d
+from aptapy.modeling import Gaussian
+from aptapy.plotting import plt
+
+hist = Histogram1d(np.linspace(-5., 5., 100), label="Random data", xlabel="z")
+hist.fill(np.random.default_rng().normal(size=100000))
+hist.plot()
+
+model = Gaussian()
+model.fit_histogram(hist)
+print(model)
+model.plot()
+
+plt.legend()

aptapy-0.3.0/docs/examples/simple_hist1d.py

@@ -0,0 +1,20 @@
+"""
+Simple 1-D histogram
+====================
+
+Simple one-dimensional histogram filled with random numbers from a normal
+distribution.
+"""
+
+# %%
+
+import numpy as np
+
+from aptapy.hist import Histogram1d
+from aptapy.plotting import plt
+
+hist = Histogram1d(np.linspace(-5., 5., 100), label="Random data", xlabel="z")
+hist.fill(np.random.default_rng().normal(size=100000))
+hist.plot()
+
+plt.legend()

aptapy-0.3.0/docs/examples/weighted_hist1d.py

@@ -0,0 +1,25 @@
+"""
+Weighted 1-D histogram
+======================
+
+Weighted one-dimensional histogram to emulate a triangular distribution.
+"""
+
+# %%
+
+import numpy as np
+
+from aptapy.hist import Histogram1d
+from aptapy.plotting import plt
+
+hist = Histogram1d(np.linspace(0., 1., 100), label="Random data", xlabel="u")
+# Histogram sample: extract n random numbers uniformly distributed in [0, 1)
+# and assign weights w = 1 - u (that is, w = 1 for u = 0 and 0 for u = 1).
+# The result should be equivalent to sampling a triangular distribution.
+n = 100000
+sample = np.random.default_rng().random(size=n)
+weights = 1. - sample
+hist.fill(sample, weights=weights)
+hist.plot()
+
+plt.legend()

aptapy-0.3.0/docs/index.rst

@@ -0,0 +1,36 @@
+.. aptapy documentation master file, created by
+   sphinx-quickstart on Sun Aug 24 11:47:57 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+aptapy documentation
+====================
+
+.. image:: _static/logo.png
+   :alt: Project logo
+   :width: 200px
+   :align: left
+
+This is a small, pure-Python library providing statistical tools for online monitoring
+and analysis of experimental data, with a focus on histogramming, time series, and
+fitting. It is designed to be lightweight and easy to use, making it suitable for
+integration into existing data processing pipelines.
+
+The :doc:`examples Gallery <auto_examples/index>` is probably the best place to start.
+Have fun!
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   auto_examples/index
+   release_notes
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API:
+
+   hist
+   modeling
+   strip

aptapy-0.3.0/docs/modeling.rst

@@ -0,0 +1,185 @@
+.. _modeling:
+
+:mod:`~aptapy.modeling` --- Fitting models
+==========================================
+
+The modeling module provides tools for fitting models to data, including parameter
+estimation and uncertainty quantification.
+
+Readily available simple models include
+
+* :class:`~aptapy.modeling.Constant`: a constant value;
+* :class:`~aptapy.modeling.Line`: a straight line;
+* :class:`~aptapy.modeling.PowerLaw`: a power law;
+* :class:`~aptapy.modeling.Gaussian`: a Gaussian function.
+
+More complex models can be built by summing simple ones, e.g.,
+
+>>> from aptapy.modeling import Line, Gaussian
+>>>
+>>> model = Line() + Gaussian()
+
+The main fitting engine supports bounded fits and/or fits with fixed parameters.
+
+
+Parameters
+----------
+
+The first central concept in the modeling module is that of a fit parameter,
+represented by the :class:`~aptapy.modeling.FitParameter` class. A fit parameter
+is a named mutable object that holds a value, an optional uncertainty, and optional
+bounds, along with a flag that indicate whether they should be varied or not in a fit.
+
+:class:`~aptapy.modeling.FitParameter` objects provide all the facilities for
+pretty-printing their value and uncertainty. The following example shows the basic
+semantics of the class:
+
+>>> from aptapy.modeling import FitParameter
+>>>
+>>> param = FitParameter(1.0, "amplitude", error=0.1)
+>>> print(param)
+Amplitude: 1.0 ± 0.1
+
+
+Fit status
+----------
+
+:class:`~aptapy.modeling.FitStatus` is a small bookkeeping class that holds all the
+information about the status of a fit, such as the chisquare, the number of degrees of
+freedom and the fit range.
+
+.. warning::
+
+   At this point the implementation of the class is fairly minimal, and it is very
+   likely that we will be adding stuff along the way.
+
+
+Simple models
+-------------
+
+Chances are you will not have to interact with :class:`~aptapy.modeling.FitParameter`
+and :class:`~aptapy.modeling.FitStatus` objects a lot, but they are central to defining
+and using simple fit models, and heavily used internally.
+
+The easiest way to see how you would go about defining an actual fit model is to
+look at the source code for a simple one.
+
+.. literalinclude:: ../src/aptapy/modeling.py
+   :language: python
+   :pyobject: Line
+   :linenos:
+
+All we really have to do is to subclass :class:`~aptapy.modeling.AbstractFitModel`,
+listing all the fit parameters as class attributes (assigning them sensible default
+values), and implement the :meth:`~aptapy.modeling.AbstractFitModel.evaluate` method,
+which takes as first argument the independent variable and then the values of all the
+fit parameters.
+
+.. note::
+
+   It goes without saying that the order of the fit parameters in the argument
+   list of the :meth:`~aptapy.modeling.AbstractFitModel.evaluate` method must
+   match the order in which they are defined as class attributes.
+
+In this particular case we are sayng that the ``Line`` model has two fit parameters,
+``intercept`` and ``slope``, and, well, the model itself evaluates as a straight line
+as we would expect.
+
+When we create an instance of a fitting model
+
+>>> model = Line()
+
+a few things happen under the hood:
+
+* the class instance gets its own `copy` of each fit parameter, so that we can
+  change their values and settings without affecting the class definition, nor other
+  class instances;
+* the class instance registers the fit parameters as attributes of the instance,
+  so that we can access them as, e.g., ``model.intercept``, ``model.slope``.
+
+That it's pretty much it. The next thing that you proabably want to do is to fit
+the model to a series of data points, which you do in pretty much the same fashion
+as you would do with ``scipy.optimize.curve_fit`` using the
+:meth:`~aptapy.modeling.AbstractFitModel.fit` method. This will return a
+:meth:`~aptapy.modeling.FitStatus` object containing information about the fit.
+
+
+Fitting primer
+~~~~~~~~~~~~~~
+
+Assuming that you have a set of data points ``xdata``, ``ydata``, the latter with
+associated uncertainties ``yerrors``, the simplest fit goes like
+
+>>> from aptapy.modeling import Line
+>>>
+>>> model = Line()
+>>> status = model.fit(xdata, ydata, sigma=yerrors)
+
+You can fit within a subrange of the input data by specifying the ``min`` and/or
+the ``max`` keyword arguments:
+
+>>> from aptapy.modeling import Line
+>>>
+>>> model = Line()
+>>> status = model.fit(xdata, ydata, sigma=yerrors, xmin=0., xmax=10.)
+
+You can set bounds on the fit parameters, e.g., force the slope to be positive
+by doing
+
+>>> from aptapy.modeling import Line
+>>>
+>>> model = Line()
+>>> model.slope.minimum = 0.
+>>> status = model.fit(xdata, ydata, sigma=yerrors)
+
+and you can freeze any of the parameters to a fixed value during the fit
+
+>>> from aptapy.modeling import Line
+>>>
+>>> model = Line()
+>>> model.intercept.freeze(0.)
+>>> status = model.fit(xdata, ydata, sigma=yerrors)
+
+Or, really, any linear combination of the above. The fit status is able to
+pretty-print itself, and the fitted model can be plotted by just doing
+
+>>> model.plot()
+>>> plt.legend()
+
+(The legend bit is put there on purpose, as by default the fitting model will
+add a nice entry in the legend with all the relevant information.)
+
+Fitting models interact nicely with one-dimensional histograms from the
+:mod:`~aptapy.hist`, module so you can do
+
+>>> import numpy as np
+>>> from aptapy.hist import Histogram1D
+>>> from aptapy.modeling import Line
+>>>
+>>> hist = Histogram1D(np.linspace(0., 1., 100))
+>>> hist.fill(np.random.rand(1000))
+>>> model = Line()
+>>> status = model.fit_histogram(hist)
+
+
+Composite models
+----------------
+
+The modeling module also provides a way to build composite models by summing
+simple ones. This is achieved by means of the :class:`~aptapy.modeling.FitModelSum`,
+which is design to hold a list of components and interoperate with the rest
+of the world in exactly the same fashion as simple models.
+
+Chances are you will never have to instantiate a :class:`~aptapy.modeling.FitModelSum`
+object directly, as the ``+`` operator will do the trick in most of the cases, e.g.,
+
+>>> from aptapy.modeling import Line, Gaussian
+>>> model = Line() + Gaussian()
+>>> status = model.fit(xdata, ydata, sigma=yerrors)
+
+
+
+Module documentation
+--------------------
+
+.. automodule:: aptapy.modeling

aptapy-0.3.0/docs/release_notes.rst

@@ -0,0 +1,41 @@
+.. _release_notes:
+
+Release notes
+=============
+
+
+Version 0.3.0 (2025-10-08)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* New strip-chart facilities added.
+* Introduction of model summation capability through operator overloading
+* Refactored class hierarchy with new abstract base classes
+* Enhanced parameter compatibility checking methods
+* Improved histogram integration for fitting
+* Adds sphinx-gallery integration with 5 example scripts demonstrating histogram
+  and fitting functionality
+* Improves statistical analysis by adding p-value calculations and fixing degrees
+  of freedom calculations
+* Updates test assertions to include p-value validation
+
+* Pull requests merged:
+
+  - https://github.com/lucabaldini/aptapy/pull/3
+  - https://github.com/lucabaldini/aptapy/pull/4
+  - https://github.com/lucabaldini/aptapy/pull/5
+
+
+Version 0.2.0 (2025-10-06)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* New histogram facilities added.
+
+* Pull requests merged:
+
+  - https://github.com/lucabaldini/aptapy/pull/2
+
+
+Version 0.1.1 (2025-10-03)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Initial release on PyPI.

aptapy-0.3.0/docs/strip.rst

@@ -0,0 +1,44 @@
+.. _strip:
+
+:mod:`~aptapy.strip` --- Strip charts
+=====================================
+
+This module provides a  :class:`~aptapy.strip.StripChart` class representing 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.
+This is mainly meant to represent the time history of a signal over a reasonable
+span---a long-term acquisition might go on for weeks, and it would not make sense
+to try and plot on the screen millions of points, but the last segment of the
+acquisition is the most important part when we want to monitor what is happening.
+
+Internally the class uses two distinct :class:`collections.deque` objects to store
+the data points, and the public interface is modeled after that of deques: you add
+a single point with :meth:`~aptapy.strip.StripChart.append()`, and multiple points
+with :meth:`~aptapy.strip.StripChart.extend()`.
+
+.. code-block:: python
+
+    from aptapy.strip import StripChart
+
+    chart = StripChart(max_length=1000, label='Signal')
+
+    # add a single point
+    chart.append(0., 0.)
+
+    # add multiple points
+    chart.extend([1., 2., 3.], [4., 5., 6.])
+
+    # plot the current contents of the strip chart
+    chart.plot()
+
+Strip chart objects can operate in two fundamentally different modes: if the
+``datetime`` flag is ``False``, the x-axis is treated as a simple numeric value
+(e.g., time in seconds since the start of the acquisition, or a simple numeric
+index), while if it is ``True``, the x-axis is treated as a series of
+POSIX timestamps that are converted to datetime objects for plotting purposes.
+
+
+Module documentation
+--------------------
+
+.. automodule:: aptapy.strip

{aptapy-0.2.0 → aptapy-0.3.0}/noxfile.py

@@ -43,8 +43,9 @@ def cleanup(session: nox.Session) -> None:
         if _path.exists():
             shutil.rmtree(_path)
     # Cleanup the docs.
-    _path = _DOCS_DIR / "_build"
-    if _path.exists():
+    for folder_name in ("_build", "auto_examples"):
+        _path = _DOCS_DIR / folder_name
+        if _path.exists():
             shutil.rmtree(_path)
 
 

{aptapy-0.2.0 → aptapy-0.3.0}/pyproject.toml

@@ -35,6 +35,7 @@ dev = [
 docs = [
     "sphinx",
     "sphinxawesome-theme",
+    "sphinx-gallery",
   ]
 
 [project.urls]

aptapy-0.3.0/src/aptapy/_version.py

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