Releasing

Releases are automated and go through a reviewed pull request. To cut a release, a maintainer runs the Prepare release GitHub Action (Actions tab, workflow_dispatch) and selects the bump (patch / minor / major). This opens a small Release vX.Y.Z pull request that bumps [project].version in pyproject.toml on a release/bump-* branch off main. A reviewer checks that it changes only that line and squash-merges it into main; the merge triggers the Release workflow, which tests, builds, publishes to PyPI (Trusted Publishing), and then tags the version and creates the GitHub release. The build reads the version from pyproject.toml, which remains the single source of truth.

Promotion of features from dev to main is independent of releases and must not change [project].version – a Version guard CI check flags any pull request outside the release flow that edits it (the check is advisory, so reviewers must not merge a flagged pull request). The version line is owned solely by the release automation on main; this is what keeps dev -> main merges free of version conflicts under the squash-merge policy (a version edited on both branches would otherwise conflict every release cycle).

The Prepare release action requires the repository/organization setting Allow GitHub Actions to create and approve pull requests to be enabled, so it can open the bump pull request. See RELEASING.md and the family guide https://github.com/bnelair/brainmaze-sphinx/blob/main/RELEASING.md (including what to do if a release fails part-way).

New functions need to be implemented with Sphinx compatible docstrings. The documentation is automatically generated from the docstrings using Sphinx.

Building Documentation

To build the documentation locally:

1. Install documentation dependencies:

pip install -e ".[docs]"

Alternatively, you can install from the requirements file:

pip install -r docs_src/requirements.txt

2. Build the documentation:

sphinx-build -b html docs_src/source docs

The generated HTML documentation will be in the docs/ directory. Note that the docs/ directory is excluded from version control via .gitignore and should not be committed to the repository.

Sleep classification and feature extraction

F. Mivalt et V. Kremen et al., “Electrical brain stimulation and continuous behavioral state tracking in ambulatory humans,” J. Neural Eng., vol. 19, no. 1, p. 016019, Feb. 2022, doi: 10.1088/1741-2552/ac4bfd.

F. Mivalt et V. Sladky et al., “Automated sleep classification with chronic neural implants in freely behaving canines,” J. Neural Eng., vol. 20, no. 4, p. 046025, Aug. 2023, doi: 10.1088/1741-2552/aced21.

The work was based on the following references:

Gerla, V., Kremen, V., Macas, M., Dudysova, D., Mladek, A., Sos, P., & Lhotska, L. (2019). Iterative expert-in-the-loop classification of sleep PSG recordings using a hierarchical clustering. Journal of Neuroscience Methods, 317(February), 61–70. https://doi.org/10.1016/j.jneumeth.2019.01.013

Kremen, V., Brinkmann, B. H., Van Gompel, J. J., Stead, S. (Matt) M., St Louis, E. K., & Worrell, G. A. (2018). Automated Unsupervised Behavioral State Classification using Intracranial Electrophysiology. Journal of Neural Engineering. https://doi.org/10.1088/1741-2552/aae5ab

Kremen, V., Duque, J. J., Brinkmann, B. H., Berry, B. M., Kucewicz, M. T., Khadjevand, F., G.A. Worrell, G. A. (2017). Behavioral state classification in epileptic brain using intracranial electrophysiology. Journal of Neural Engineering, 14(2), 026001. https://doi.org/10.1088/1741-2552/aa5688

Evoked Response Potential Analysis

K. J. Miller et al., “Canonical Response Parameterization: Quantifying the structure of responses to single-pulse intracranial electrical brain stimulation,” PLOS Comput. Biol., vol. 19, no. 5, p. e1011105, May 2023, doi: 10.1371/journal.pcbi.1011105.

EEG Slow Wave Detection and Analysis

Carvalho DZ, Kremen V, Mivalt F, St Louis EK, McCarter SJ, Bukartyk J, Przybelski SA, Kamykowski MG, Spychalla AJ, Machulda MM, Boeve BF, Petersen RC, Jack CR Jr, Lowe VJ, Graff-Radford J, Worrell GA, Somers VK, Varga AW, Vemuri P. Non-rapid eye movement sleep slow-wave activity features are associated with amyloid accumulation in older adults with obstructive sleep apnoea. Brain Commun. 2024 Oct 7;6(5):fcae354. doi: 10.1093/braincomms/fcae354. PMID: 39429245; PMCID: PMC11487750.

The slow-wave detection project is documented on the EEG Slow Wave Detection and Analysis page; the runnable example is demo/eeg_wave_detection. The original project readme from the BEST toolbox: projects/slow_wave_detection/readme.rst.