py4tsa 3.2.0__tar.gz

py4tsa-3.2.0/.github/prompts/review-library.prompt.md

@@ -0,0 +1,15 @@
+---
+mode: ask
+description: Review changes in the p4TSA C++/pybind11 library for correctness, build impact, test coverage, and API stability.
+---
+
+Review the current change set in this repository as if you were preparing a code review for p4TSA.
+
+Focus on:
+- correctness and numerical stability in the C++ core
+- pybind11 binding changes and Python compatibility
+- build and packaging impact, including native dependencies and CMake changes
+- regressions in wavelet, WDF, or persistence-related logic
+- missing or weak tests and any risky assumptions
+
+Provide a concise review with findings, severity, and suggested next actions.

py4tsa-3.2.0/.github/workflows/ci.yml

@@ -0,0 +1,101 @@
+name: CI
+
+# Every pull request into master must pass this before it can be merged. The
+# branch-protection rule that enforces it names the jobs below as required
+# status checks -- see CONTRIBUTING.md.
+#
+# Replaces the old .travis.yml (2026-08-03): Travis CI's free tier for open
+# source was retired years ago, and that config no longer matched this
+# repo's actual build (it predated the scikit-build-core/CMake packaging
+# build -- see CMakeLists.txt's own header comment). GitHub Actions runs on
+# every push/PR for free on a public repo, no separate service to configure.
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  workflow_dispatch:
+
+jobs:
+  build-and-test:
+    name: Build + test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v5
+
+      # Same dependency set as conda-recipe/meta.yaml's host/build
+      # requirements -- keep the two in sync if either changes.
+      - name: Set up build environment
+        uses: mamba-org/setup-micromamba@v3
+        with:
+          micromamba-version: latest
+          environment-name: p4tsa-ci
+          init-shell: bash
+          create-args: >-
+            -c conda-forge
+            python=${{ matrix.python-version }}
+            pip
+            cxx-compiler
+            cmake>=3.28
+            make
+            scikit-build-core>=0.10
+            pybind11>=2.12
+            numpy
+            scipy
+            gsl
+            fftw
+            framel
+            libboost-headers
+            cereal
+            pytest
+
+      - name: Build and install p4TSA (editable, no build isolation)
+        shell: bash -el {0}
+        run: pip install -e . --no-build-isolation -v
+
+      - name: Import smoke test
+        shell: bash -el {0}
+        run: python -c "import py4tsa; print('py4tsa OK:', py4tsa.__file__)"
+
+      - name: Run tests
+        shell: bash -el {0}
+        run: pytest python-wrapper/tests/ -v
+
+  docs:
+    name: Docs build check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up build environment
+        uses: mamba-org/setup-micromamba@v3
+        with:
+          micromamba-version: latest
+          environment-name: p4tsa-docs-ci
+          init-shell: bash
+          create-args: >-
+            -c conda-forge
+            python=3.11
+            doxygen
+
+      - name: Install docs Python requirements
+        shell: bash -el {0}
+        run: pip install -r docs/requirements.txt
+
+      # docs/conf.py runs Doxygen itself on every build, which is why doxygen
+      # is in the environment above.
+      #
+      # Not -W: every `doxygenfile` page re-emits the declarations its header
+      # shares with the others, so Breathe warns once per page about a
+      # duplicate C++ declaration. That is the price of documenting headers
+      # that carry free functions and typedefs rather than a class, and it is
+      # not something a contributor can fix. Real breakage -- a ConfigError, a
+      # bad directive, a missing Doxygen -- still fails the build outright.
+      - name: Build Sphinx docs (Doxygen + Breathe)
+        shell: bash -el {0}
+        run: sphinx-build -b html docs docs/_build/html

py4tsa-3.2.0/.github/workflows/wheels.yml

@@ -0,0 +1,91 @@
+name: wheels
+
+# Builds the manylinux wheels for PyPI. What to build and how to test it is in
+# pyproject.toml, [tool.cibuildwheel], so a local `cibuildwheel` run does the
+# same thing. Not on every push: it compiles the C++ core once per Python.
+
+on:
+  push:
+    tags: ["v*"]
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "Publish to PyPI when the wheels pass"
+        type: boolean
+        default: false
+
+jobs:
+  build:
+    name: Build wheels (manylinux x86_64)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: pypa/cibuildwheel@v4.2.1
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels
+          path: wheelhouse/*.whl
+
+  sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - run: pipx run build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  # The wheel installed where it will be used: a plain runner, with none of
+  # the libraries it needs present on the system.
+  verify:
+    name: Install the wheel on a plain runner
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@v4
+        with:
+          name: wheels
+          path: wheelhouse
+
+      # --no-index: the wheel just built, never one already on PyPI.
+      - name: Install it
+        run: |
+          pip install pytest numpy scipy
+          pip install --no-index --find-links wheelhouse py4tsa
+
+      - name: Show what it links against
+        run: |
+          so=$(python -c "import py4tsa; print(py4tsa.__file__)")
+          echo "$so"
+          ldd "$so"
+          ! ldd "$so" | grep -q "not found"
+
+      # From outside the checkout, so only the installed wheel is importable.
+      - name: Run the tests against it
+        working-directory: /tmp
+        run: pytest "$GITHUB_WORKSPACE/python-wrapper/tests" -q
+
+  # An upload cannot be taken back, so the `pypi` environment holds the run
+  # for a human whatever triggered it.
+  publish:
+    name: Publish to PyPI
+    needs: [build, sdist, verify]
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.publish)
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write          # trusted publishing; no token is stored here
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

py4tsa-3.2.0/.gitignore

@@ -0,0 +1,23 @@
+generate_rst.py
+
+# Build artifacts (CMake / scikit-build-core)
+build/
+python-wrapper/build/
+python-wrapper/tmp/
+*.so
+*.pyd
+*.o
+
+# Python
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+
+# Docs (generated -- Doxyfile is templated from Doxyfile.in, _build is Sphinx output)
+docs/Doxyfile
+docs/_build/
+
+# Editors / OS
+.DS_Store
+*.swp

py4tsa-3.2.0/.readthedocs.yaml

@@ -0,0 +1,33 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  # docs/conf.py runs doxygen and feeds its XML to breathe; without it every
+  # C++ API page renders empty.
+  apt_packages:
+    - doxygen
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt

py4tsa-3.2.0/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS instructions for p4TSA
+
+## Project snapshot
+- p4TSA is a C++ time-series analysis library with a Python interface exposed as the py4tsa module through pybind11.
+- The core implementation lives in the C++ headers under [include](include) and the corresponding sources under [src](src).
+- The Python-facing binding entry point is [python-wrapper/py4tsa.cpp](python-wrapper/py4tsa.cpp), and regression tests live under [python-wrapper/tests](python-wrapper/tests).
+- The packaging/build flow is defined by [CMakeLists.txt](CMakeLists.txt), [pyproject.toml](pyproject.toml), and the installation guidance in [README.md](README.md).
+
+## Working conventions
+- Keep changes compatible with the repository’s existing C++14 style and the current pybind11 binding patterns.
+- Prefer small, focused changes and preserve the current API shape unless the task explicitly requires a breaking change.
+- For numerical and wavelet-related code, be conservative: these components are sensitive to regression and should be tested rather than “fixed” by intuition alone.
+- When adding or changing behavior, update or add tests under [python-wrapper/tests](python-wrapper/tests) when practical.
+
+## Build and test commands
+- Configure and build the native extension:
+  - `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX"`
+  - `cmake --build build -j"$(nproc)"`
+  - `cmake --install build`
+- Run the Python regression tests:
+  - `pytest python-wrapper/tests/ -v`
+- Smoke-test the installed module:
+  - `python -c "import py4tsa; print(py4tsa.__file__)"`
+
+## Review priorities
+- For review-oriented work, focus on correctness, build impact, test coverage, and API stability rather than style-only changes.
+- Pay special attention to the C++/Python boundary, memory ownership, and any change touching wavelet transforms, WDF classification/reconstruction, or persistence logic.
+- Call out missing tests, risky assumptions, and any changes that would be hard to validate without native-library availability.
+
+## References
+- Start with [README.md](README.md) for installation and dependency notes.
+- Use [CMakeLists.txt](CMakeLists.txt) and [pyproject.toml](pyproject.toml) when evaluating packaging or build changes.
+- Use [python-wrapper/tests](python-wrapper/tests) as the baseline for expected behavior.

py4tsa-3.2.0/CHANGELOG.md

@@ -0,0 +1,171 @@
+# Changelog
+
+## 3.2.0
+
+### Added
+
+- **`pip install py4tsa`.** Wheels for CPython 3.10 to 3.13,
+  `manylinux_2_28_x86_64`, with GSL, FFTW3 and FrameL inside them, so nothing
+  has to be installed first. The build takes FrameL from the system when it is
+  there, and otherwise compiles it from its own source
+  (git.ligo.org/virgo/virgoapp/Fr, 8.50.2).
+- `test_04_frame_io.py`, which reads a frame through `FrameIChannel` and
+  checks the samples against an 8 kB fixture.
+
+### Changed
+
+- CMake 3.28 is now the minimum, for `FetchContent`'s `EXCLUDE_FROM_ALL`.
+- Wheels are built and tested by a separate workflow, on tags and releases and
+  by hand, rather than on every push. Publishing waits for a person.
+- Metadata for the index: classifiers, `Source`, `Issues` and `Changelog`
+  links, and `requires-python >= 3.10`, the range the wheels are built for.
+
+## 3.1.0
+
+### Changed
+
+- **BREAKING: the Python module is now `py4tsa`, not `pytsa`.** Every
+  `import pytsa` / `from pytsa.tsa import ...` becomes `import py4tsa` /
+  `from py4tsa.tsa import ...`. The old name on PyPI belongs to an unrelated
+  project, which would shadow this extension for anyone holding both. The C++
+  library keeps the name p4TSA; the Python module and the distribution name
+  change.
+- **The block rule is the default of `WDF2Classify`.** A classifier built
+  without a thresholding rule used `cuoco`, the universal threshold with the
+  sigma given from outside; it now uses `block`. Callers that pass the rule
+  explicitly are unaffected.
+
+### Added
+
+- **A block rule for the wavelet coefficients of a window.**
+  `WaveletThreshold::block` judges contiguous coefficients of one level
+  together (Cai 1999): a block of L is kept whole when its energy exceeds
+  lambda L sigma^2, and zeroed whole otherwise, with sigma read from the
+  window's median as for the universal threshold. A signal spread over
+  neighbouring coefficients, each below sqrt(2 ln N) sigma, survives as a
+  block where no single coefficient would; a lone noise excursion does not
+  carry its block over the line. `SetBlock(length, lambda)` sets the two
+  parameters, defaulting to ln N and 4.505. On the merger window of GW150914
+  in H1 the rule keeps 18 coefficients where the universal threshold keeps
+  five, twelve of them in 32-128 Hz, and fires on fewer windows of noise at
+  the same EnWDF threshold.
+
+## 3.0.1
+
+### Fixed
+
+- **The package declares the version it is tagged with.** `pyproject.toml`, the
+  conda recipe and the changelog heading still read 2.2.0 when 3.0.0 was tagged,
+  so an installed package reported a version its archive was not built from and
+  the changelog attributed the trigger-scale changes to a release that predates
+  them.
+
+- **`CITATION.cff` carries the author ORCID, the version and the release date.**
+  Zenodo builds the record for an archived release from that file; without those
+  fields the archived record names an author with no identifier behind it.
+
+## 3.0.0
+
+### Changed
+
+- **`WaveletThreshold` defaults to hard thresholding.** Both `operator()`
+  overloads took `ThresholdingMode m = soft`, so every caller that omitted the
+  argument -- including `WDF2Classify` -- shrank each surviving coefficient by
+  the threshold, biasing amplitudes low by an amount that grows with the number
+  of coefficients a signal is spread over. Soft thresholding minimises the mean
+  square error of a denoised reconstruction; a detection statistic and a
+  parameter estimate are read off the amplitude instead, so the survivors are
+  now left unchanged.
+
+- **`WDF2Classify`'s statistic is the coefficient norm on the noise scale.** The
+  division by the window length was removed, so `mSNR` is
+  `sqrt(sum c_i^2) / sigma`. The candidate bases are orthonormal, so that is the
+  matched-filter signal-to-noise ratio of the reconstructed transient, and a
+  configured threshold carries the units it appears to have. Previously the
+  statistic scaled as the inverse square root of the window length.
+
+- **`WDF2Classify` exports the noise scale that produced the statistic.**
+  `EventFullFeatured::mSigma` carries the winning basis's own per-window
+  estimate, so a downstream consumer can recompute the signal-to-noise ratio
+  under the convention that decided the trigger rather than a separately frozen
+  one.
+
+- **The candidate basis list goes from 19 bases to 10.** Plain and centered
+  Daubechies of the same order are the same filter taps up to a phase shift, so
+  keeping both spent roughly half the list's compute on no real diversity; the
+  plain family and every other centered order were dropped. Coiflet (orders 1
+  and 2) and Symlet (orders 4 and 8) were added in their place as genuinely
+  different shapes -- Symlet only begins to differ from Daubechies at order 4,
+  and Coiflet has vanishing moments for the scaling function as well as for the
+  wavelet. The biorthogonal B-spline family stays excluded: it is not
+  orthonormal, so Parseval does not hold for it and `mSNR` would not be the
+  signal-to-noise ratio of the reconstruction.
+
+- **New `ExtraWaveletFamilies.hpp`.** Coiflet and Symlet are plugged into GSL's
+  own extensible `gsl_wavelet_type` mechanism rather than by patching GSL or
+  taking on another wavelet library. Filter coefficients were cross-checked
+  against PyWavelets for orthonormality and for tap order, which the two
+  libraries store in opposite conventions.
+
+### Removed
+
+- **`eternity` is gone, replaced by Cereal.** The vendored 1999--2003 XML
+  persistence layer was a real compiled dependency, not dead code. All eight
+  persistable classes (`ArBurgEstimator`, `LatticeView`, `ARMAView`,
+  `DoubleWhitening`, `FifoBuffer`, `LatticeFilter`, `LSLfilter`, `LSLLearning`)
+  now use Cereal through the new `CerealPersistence.hpp`, whose
+  `DvectorProxy`/`DmatrixProxy`/`VDmatrixProxy` types exist to sidestep a real
+  ambiguity: `boost::numeric::ublas` vectors and matrices already carry an
+  inherited Boost.Serialization `serialize()` member, which clashes with any
+  free save/load pair added for the same type. Save/load round-trips are
+  verified byte-exact against freshly estimated filter state. Cereal is a new
+  header-only dependency (conda-forge). The legacy ENV_ROOT-era build files,
+  unused by the CMake packaging build, were removed at the same time.
+
+### Infrastructure
+
+- **CI moved from Travis to GitHub Actions.** Travis's free tier for open
+  source was retired years ago and its configuration predated the current build
+  system entirely.
+
+- **The Sphinx documentation build was broken and now works.** `conf.py` used
+  an `intersphinx_mapping` shorthand that modern Sphinx rejects outright;
+  `docs/requirements.txt` was missing Sphinx itself and the theme; the
+  list-form `source_suffix` silently parsed `index.md` as reStructuredText with
+  no Markdown parser registered; and `index.md` and `index.rst` both existed as
+  master-document candidates, with Sphinx picking the stale one.
+  `structure/installation.rst` still described the pre-packaging build.
+
+- **The C++ API reference was rendering empty and now has content.** Doxygen ran
+  only on Read the Docs, and `breathe_default_project` named a key that was
+  never added to `breathe_projects` anywhere else, so all 66 class pages came
+  out blank with one breathe warning each. Doxygen now runs on every build and
+  the project key is defined once; `.readthedocs.yaml` installs `doxygen`
+  through `apt_packages`, which it was never asked to do, so the published
+  pages had no Doxygen XML to render from either. Twelve pages asked
+  `doxygenclass` for a class their header does not declare (`tsaTypes`,
+  `WindowFactory`, `fparser`, ...) and now use `doxygenfile`; nine pages were
+  in no toctree; `armafit.rst` duplicated `ARMAfit.rst`. The build goes from 78
+  warnings to 9.
+
+- **Documentation points at `wdflow`, not the retired `wdf`.** `docs/index.rst`
+  linked the old project's repository and site, both being retired.
+  `README.rst`, an unreferenced duplicate of `README.md` predating the
+  PyPI-collision warning and the contact change, was removed.
+
+- **A `.gitignore` covering build artifacts, Python cache and generated docs**
+  replaces the previous one-line file.
+
+### Notes for downstream users
+
+Trigger values change. `mSNR` from a run before this release is not comparable
+with one after it: it is larger, having lost the window-length division, and no
+longer biased low by shrinkage. Thresholds tuned against the old scale must be
+re-tuned against a measured background. Triggers also no longer report a
+biorthogonal winning basis, and the set of names that can appear in `mWave` is
+the ten listed above.
+
+`pytsa` on PyPI is an unrelated package (a Python decorator library). p4TSA's
+own `pytsa` module is never published there and is only ever built from this
+repository's source; install it with `pip install .` from a checkout, which
+builds the extension through scikit-build-core and CMake.

py4tsa-3.2.0/CITATION.cff

@@ -0,0 +1,104 @@
+cff-version: 1.2.0
+title: "p4TSA: package for Time Series Analysis"
+message: >-
+  Use of this software in published work requires citation of the references
+  listed below: the method paper for the Wavelet Detection Filter, and the
+  papers describing the autoregressive time-domain whitening that the
+  conditioning stage implements.
+type: software
+authors:
+  - family-names: Cuoco
+    given-names: Elena
+    orcid: "https://orcid.org/0000-0002-6528-3449"
+    email: elena.cuoco@unibo.it
+    affiliation: "Alma Mater Studiorum -- Università di Bologna"
+license: GPL-3.0-or-later
+repository-code: "https://github.com/elenacuoco/p4TSA"
+version: "3.2.0"
+date-released: "2026-09-17"
+
+preferred-citation:
+  type: article
+  status: preprint
+  title: >-
+    The Wavelet Detection Filter: A Real Time Unmodeled Pipeline for
+    Gravitational Wave Transients, Ranking Coincidences with a Graph
+    Neural Network
+  authors:
+    - family-names: Cuoco
+      given-names: Elena
+      orcid: "https://orcid.org/0000-0002-6528-3449"
+  year: 2026
+  month: 9
+  doi: "10.48550/arXiv.2609.12797"
+  url: "https://arxiv.org/html/2609.12797v1"
+
+references:
+  - type: conference-paper
+    title: "Wavelet-based classification of transient signals for gravitational wave detectors"
+    authors:
+      - family-names: Cuoco
+        given-names: Elena
+      - family-names: Razzano
+        given-names: Massimiliano
+      - family-names: Utina
+        given-names: Andrei
+    collection-title: "2018 26th European Signal Processing Conference (EUSIPCO)"
+    publisher:
+      name: EURASIP
+    year: 2018
+    start: 2648
+    end: 2652
+    doi: "10.23919/EUSIPCO.2018.8553393"
+  - type: article
+    title: >-
+      On-line power spectra identification and whitening for the noise in
+      interferometric gravitational wave detectors
+    authors:
+      - family-names: Cuoco
+        given-names: Elena
+      - family-names: Calamai
+        given-names: G.
+      - family-names: Fabbroni
+        given-names: L.
+      - family-names: Losurdo
+        given-names: G.
+      - family-names: Mazzoni
+        given-names: M.
+      - family-names: Stanga
+        given-names: R.
+      - family-names: Vetrano
+        given-names: F.
+    journal: "Classical and Quantum Gravity"
+    volume: 18
+    start: 1727
+    end: 1751
+    year: 2001
+    doi: "10.1088/0264-9381/18/9/309"
+
+  - type: article
+    title: >-
+      Noise parametric identification and whitening for LIGO 40-m
+      interferometer data
+    authors:
+      - family-names: Cuoco
+        given-names: Elena
+      - family-names: Losurdo
+        given-names: G.
+      - family-names: Calamai
+        given-names: G.
+      - family-names: Fabbroni
+        given-names: L.
+      - family-names: Mazzoni
+        given-names: M.
+      - family-names: Stanga
+        given-names: R.
+      - family-names: Guidi
+        given-names: G.
+      - family-names: Vetrano
+        given-names: F.
+    journal: "Physical Review D"
+    volume: 64
+    start: 122002
+    year: 2001
+    doi: "10.1103/PhysRevD.64.122002"