PTSA

For documentation and tutorials, please see https://pennmem.github.io/ptsa/

Install via conda

Available for Linux (linux-64) and macOS (osx-64 / osx-arm64):

conda install -c pennmem -c conda-forge ptsa

Note

There is no native Windows (win-64) package. On Windows, run PTSA under WSL: install a Linux distribution, then a Linux conda/miniforge inside it, and use the linux-64 package above. The compiled extensions and the full test suite are validated on Linux in CI.

Report bug or feature request

To report a bug or a feature request please use https://github.com/pennmem/ptsa/issues.

Build from source

Install dependencies:

conda install -y -c conda-forge numpy scipy xarray pandas h5py netcdf4 traits six

You will also need to install FFTW. To install FFTW with conda on Linux or Mac:

conda install -y -c pennmem fftw

Alternatively, it can be installed with the system package manager on Linux (Debian-based command shown below):

sudo apt-get install libfftw3-dev

or on Mac using homebrew:

brew install fftw

To read EDF files, you will also need to install pybind11:

conda install -y -c conda-forge pybind11

System prerequisites

The following must already be available on the system before you build PTSA from source — pip cannot install them (they are not Python packages):

• A C++ compiler. The morlet, circular_stat, and edf extensions are C++ (pybind11). On Linux use gcc/g++ (or conda's gxx_linux-64); on macOS the Xcode command-line tools (xcode-select --install); on Windows, MSVC.
• FFTW3 development headers and shared library (e.g. conda install -c conda-forge fftw or sudo apt-get install libfftw3-dev). The morlet extension links against libfftw3.

(numpy and pybind11 are also build-time requirements, but pip installs them automatically into its build environment from pyproject.toml — you do not need to install them yourself.)

Install PTSA

PTSA ships a pyproject.toml declaring its build-time requirements (setuptools, wheel, numpy, pybind11), so a standard pip install builds the C++ extensions cleanly:

pip install .

Development (editable) install — your source edits take effect without reinstalling, the recommended setup for developing PTSA (and a way to run a locally-built PTSA when the conda channel is unavailable).

pip compiles the C++ extensions from source, so a C++ compiler and FFTW must be in the environment first — pip cannot install those (FFTW is a native library, not a Python package). pip does provide everything else automatically (numpy/pybind11 for the build, and the runtime deps scipy/xarray/traits/h5py/… on install). A complete setup from scratch with conda:

# 1. env with the native build prerequisites pip can't provide:
#    FFTW + a C++ compiler.
conda create -y -n ptsa-dev -c conda-forge python=3.11 pip fftw gxx_linux-64
conda activate ptsa-dev

# 2. editable install: pip builds the extensions against the FFTW
#    above and pulls the Python runtime deps from PyPI.
pip install -e .

On macOS, use the system clang instead of gxx_linux-64 (drop it from step 1 and run xcode-select --install once). FFTW can alternatively come from the system package manager instead of conda (sudo apt-get install libfftw3-dev on Debian/Ubuntu, brew install fftw on macOS) — see System prerequisites below.

If you would rather build against the numpy/pybind11 already in your environment (skipping pip's isolated build env), pass --no-build-isolation:

pip install --no-build-isolation -e .

Legacy fallback (works but setup.py install is deprecated by setuptools):

python setup.py install

If you encounter problems installing, some environment variables may need to be set, particularly if you installed FFTW with conda. If your anaconda distribution is installed in $HOME/anaconda3 and the environment name is ptsa, set the CPATH and the LD_LIBRARY_PATH as follows:

export CPATH=$HOME/anaconda3/envs/ptsa/include
export LD_LIBRARY_PATH=$HOME/anaconda3/envs/ptsa/lib

Running Tests

Install PTSA in editable mode first (see Install PTSA above), then add the test tooling:

conda install -y -c conda-forge pytest pytest-cov sybil

Both extras are required to run the suite as configured:

• sybil — the top-level conftest.py uses it to execute every .. code-block:: python example in docs/*.rst as a test, so pytest will not even start collecting without it.
• pytest-cov — satisfies the coverage options declared in setup.cfg (--cov). (Alternatively, disable them for a run with pytest -o addopts="".)

By default a plain ``pytest`` run includes the rhino-only tests — about 30 tests that read lab data from the rhino filesystem (the ptsa.data.readers layer against real EEG / event / tal files). On rhino they run normally; anywhere else (a laptop, CI) they error with OSError: Rhino root not found!, because the data isn't present.

To run only the portable tests, set the NO_RHINO environment variable, which skips the rhino-only ones:

NO_RHINO=1 pytest

Either way the run covers the unit tests in tests/ and the documentation examples in docs/*.rst. The run_tests shell script wraps the NO_RHINO=1 invocation, and CI always runs with NO_RHINO=1 set.

Building the documentation

The Sphinx site lives under docs/; the rendered HTML committed to docs/html/ is the artifact published to GitHub Pages. To rebuild it, use the same dev env you tested with (PTSA must be importable for autodoc) plus pandoc (needed by nbsphinx to render the example notebooks). With conda:

conda install -y -c conda-forge sphinx sphinx_rtd_theme nbsphinx pandoc

Then from the repo root:

PYTHONPATH=$PWD PTSA_DOCS_BUILD_NOTEBOOKS=1 python maint/build_docs.py

maint/build_docs.py removes the old docs/html/ and runs make html (which writes back into docs/html/ since docs/Makefile sets BUILDDIR = .). PYTHONPATH=$PWD ensures docs/conf.py's from ptsa import __version__ resolves when sphinx-build runs from the docs/ cwd. Set PTSA_DOCS_BUILD_NOTEBOOKS=1 to include the example notebooks (needs pandoc); omit it for a faster docs-only build.

Open docs/html/index.html in a browser to preview before committing.

Building conda packages

See separte HOW_TO_RELEASE.md document! Alternatively, this repository is now set up to deploy automatically on tagged commits.

Continuous integration

Every push to master and every pull request runs the GitHub Actions workflow in .github/workflows/build.yml across a cross-platform build matrix:

• Operating systems: ubuntu-latest and macos-latest. (Windows is not built — see the WSL note under Install via conda.)
• Python: 3.10, 3.11, 3.12, 3.13
• NumPy: 1.24 and 2.x (NumPy 1.24 wheels only ship for Python <=3.11, so the 3.12 / 3.13 cells are exercised only against NumPy 2)

Each cell does a full conda-build of conda.recipe/, which both compiles the C++ extensions (Morlet wavelet, circular statistics, EDF) against the requested NumPy ABI and runs the entire pytest suite inside conda-build's stripped-down test environment. A separate smoke step then installs the resulting .conda artifact into a brand-new environment to verify it lays down and imports outside the build tree.

When a tag matching v* is pushed, a follow-up deploy job gathers every matrix artifact and uploads them to anaconda.org/pennmem via the ANACONDA_TOKEN repository secret.

This workflow replaces the legacy TravisCI configuration; TravisCI shut down most open-source builds in 2021 and the old .travis.yml no longer ran.

License

PTSA is licensed under the GNU GPL version 3.

This repository also includes:

• FFTW (GPL license)
• EDFLib (BSD license)