Skip to content

Commit

Permalink
Merge remote-tracking branch 'upstream/main'
Browse files Browse the repository at this point in the history
  • Loading branch information
tsbinns committed Sep 13, 2024
2 parents a0f68ba + ea80d34 commit 1d07e96
Showing 28 changed files with 269 additions and 268 deletions.
4 changes: 2 additions & 2 deletions .github/workflows/unit_tests.yml
Original file line number Diff line number Diff line change
@@ -59,7 +59,7 @@ jobs:
- run: pip install -e .
- run: python -c "import pybispectra; import mne; print(f'PyBispectra {pybispectra.__version__}\n'); mne.sys_info()"
- name: Run pytest
run: python -m coverage run --source=pybispectra -m pytest -v tests && coverage report -m
run: python -m coverage run && coverage report

test_conda:
timeout-minutes: 90
@@ -89,4 +89,4 @@ jobs:
- name: Display versions and environment information
run: python -c "import pybispectra; import mne; print(f'PyBispectra {pybispectra.__version__}\n'); mne.sys_info()"
- name: Run pytest
run: python -m coverage run --source=pybispectra -m pytest -v tests && coverage report -m
run: python -m coverage run && coverage report
3 changes: 2 additions & 1 deletion changelog.md
Original file line number Diff line number Diff line change
@@ -3,13 +3,14 @@
## [Version 1.2.0dev](https://pybispectra.readthedocs.io/en/main/)

##### Enhancements
- Added general classes for computing the bispectrum and threenorm with flexible kmn channel combinations.
- Added general `Bispectrum` and `Threenorm` classes for computing with flexible kmn channel combinations.

##### Bug Fixes
- Fixed error where the number of subplots exceeding the number of nodes would cause plotting to fail.

##### API
- Changed the default value of `min_ratio` in `SpatioSpectralFilter.get_transformed_data()` from `1.0` to `-inf`.
- Added the option to control whether a copy is returned from the `get_results()` method of all `Results...` classes and from `SpatioSpectralFilter.get_transformed_data()` (default behaviour returns a copy, like in previous versions).

##### Documentation
- Added a new example for computing the bispectrum and threenorm using the general classes.
10 changes: 10 additions & 0 deletions docs/make.bat
Original file line number Diff line number Diff line change
@@ -8,6 +8,8 @@ if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set AUTOEXDIR=%SOURCEDIR%\auto_examples
set GENDIR=%SOURCEDIR%\generated
set BUILDDIR=build

%SPHINXBUILD% >NUL 2>NUL
@@ -24,12 +26,20 @@ if errorlevel 9009 (
)

if "%1" == "" goto help
if "%1" == "clean" goto clean

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:clean
echo Removing everything under '%AUTOEXDIR%' and '%GENDIR%'...
del /S /Q %AUTOEXDIR%\* >nul 2>&1
del /S /Q %GENDIR%\* >nul 2>&1
%SPHINXBUILD% -M clean %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd
7 changes: 0 additions & 7 deletions docs/source/_static/requirements.txt

This file was deleted.

2 changes: 2 additions & 0 deletions docs/source/api.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
API
===

Here are the API references for the classes and functions of PyBispectra.

.. container:: d-none

:py:mod:`pybispectra`:
1 change: 1 addition & 0 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -32,6 +32,7 @@
"numpydoc",
"sphinxcontrib.bibtex",
"sphinx_gallery.gen_gallery",
"sphinx_copybutton",
]

source_suffix = [".rst", ".md"]
65 changes: 33 additions & 32 deletions docs/source/development.rst
Original file line number Diff line number Diff line change
@@ -10,52 +10,53 @@ View the changelog for each PyBispectra version here: `version changelog
Installing PyBispectra in editable mode
---------------------------------------

If you want to make changes to PyBispectra, you may wish to install it in
editable mode. To do so, first clone the `GitHub repository
<https://github.com/braindatalab/PyBispectra/tree/main>`_ to your desired
location. Once cloned, navigate to this location and install the package
alongside its development requirements using pip:
If you want to make changes to PyBispectra, you may wish to install it in editable mode.
To do so, first clone the `GitHub repository
<https://github.com/braindatalab/PyBispectra/tree/main>`_ to your desired location. Once
cloned, navigate to this location and install the package alongside its development
requirements using pip:

.. code-block:: console
.. code-block::
$ pip install -e .
$ pip install pybispectra[dev]
pip install -e .
pip install .[dev]
Contributing to PyBispectra
---------------------------

If you encounter any issues with the package or wish to suggest improvements,
please submit a report on the `issues page
If you encounter any issues with the package or wish to suggest improvements, please
submit a report on the `issues page
<https://github.com/braindatalab/PyBispectra/issues>`_.

If you have made any changes which you would like to see officially added to
the package, consider submitting a `pull request
<https://github.com/braindatalab/PyBispectra/pulls>`_. When submitting a pull
request, please check that the existing test suite passes, and if you add new
features, please make sure that these are covered in the unit tests. The tests
can be run by calling `coverage <https://coverage.readthedocs.io/en/>`_ with
`pytest <https://docs.pytest.org/en/>`_ in the base directory:
If you have made any changes which you would like to see officially added to the
package, consider submitting a `pull request
<https://github.com/braindatalab/PyBispectra/pulls>`_. A unit test suite is included.
Tests must be added for any new features, and adaptations to the existing tests must be
made where necessary. Checks for these tests are run when a pull request is submitted,
however these tests can also be run locally by calling `coverage
<https://coverage.readthedocs.io/en/>`_ with `pytest <https://docs.pytest.org/en/>`_ in
the base directory:

.. code-block:: console
.. code-block::
$ coverage run --source=pybispectra -m pytest -v tests && coverage report -m
coverage run && coverage report
Please also check that the documentation can be built following any changes,
which can be done using `Sphinx <https://www.sphinx-doc.org/en/master/>`_ in
the ``/docs`` directory:
Please also check that the documentation can be built following any changes. The
documentation is built when a pull request is submitted, however the documentation can
also be built locally using `Sphinx <https://www.sphinx-doc.org/en/master/>`_ in the
``/docs`` directory (outputs are in the ``/docs/build/html`` directory):

.. code-block:: console
.. code-block::
$ make html
make html
Finally, features of the code such as compliance with established styles and
spelling errors in the documentation are also checked. Please ensure that the
code is formatted using `Black <https://black.readthedocs.io/en/stable/>`_, and
check that there are no egregious errors from the following commands:
Finally, features of the code such as compliance with established styles and spelling
errors in the documentation are also checked. These checks are run when a pull request
is submitted, however they can also be run locally using `pre-commit
<https://pre-commit.com/>`_. To have these checks run automatically whenever you commit
changes, install ``pre-commit`` with the following command in the base directory:

.. code-block:: console
.. code-block::
$ flake8
$ pydocstyle
$ codespell
pre-commit install
2 changes: 1 addition & 1 deletion docs/source/examples.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Examples
========

Find out how to get started with the package using the provided examples:
Find out how to get started with PyBispectra using the provided examples.

.. toctree::
:maxdepth: 1
18 changes: 9 additions & 9 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
@@ -11,20 +11,20 @@
:alt: PyBispectra

|br|
A Python signal processing package for computing spectral- and time-domain
interactions using the bispectrum.
A Python signal processing package for computing spectral- and time-domain interactions
using the bispectrum.

This package provides the tools for computing phase-amplitude coupling, time
delay estimation, and waveshape features using the bispectrum and bicoherence.
Additional tools for computing amplitude-amplitude coupling, phase-phase
coupling, and spatio-spectral filters are also provided.
This package provides the tools for computing phase-amplitude coupling, time delay
estimation, and waveshape features using the bispectrum and bicoherence. Additional
tools for computing amplitude-amplitude coupling, phase-phase coupling, and
spatio-spectral filters are also provided.

Parallel processing and `Numba <https://numba.pydata.org/>`_ optimisation are
implemented to reduce computation times. There is a minor reliance on the
`MNE <https://mne.tools/stable/index.html>`_ signal processing toolbox.
implemented to reduce computation times.

If you use this toolbox in your work, please include the following citation:|br|
Binns, T. S., Pellegrini, F., Jurhar, T., & Haufe, S. (2023). PyBispectra. DOI: `10.5281/zenodo.8377820 <https://doi.org/10.5281/zenodo.8377820>`_
Binns, T. S., Pellegrini, F., Jurhar, T., & Haufe, S. (2023). PyBispectra. DOI:
`10.5281/zenodo.8377820 <https://doi.org/10.5281/zenodo.8377820>`_

.. toctree::
:maxdepth: 2
26 changes: 13 additions & 13 deletions docs/source/installation.rst
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
Installation
============

To install PyBispectra, activate the desired environment in which you want the
package, then install it using pip:
To install PyBispectra, activate the desired environment in which you want the package,
then install it using pip:

.. code-block:: console
.. code-block::
$ pip install pybispectra
pip install pybispectra
PyBispectra requires Python >= 3.10. Other requirements are listed
`here <_static/requirements.txt>`_.
PyBispectra requires Python >= 3.10.

If you need to create an environment in which to install PyBispectra, you can
do so using `conda <https://docs.conda.io/en/latest/>`_, after which you can
install the package:
If you need to create an environment in which to install PyBispectra, you can do so
using `conda <https://docs.conda.io/en/latest/>`_, after which you can install the
package:

.. code-block:: console
.. code-block::
$ conda create -n pybispectra_env
$ conda activate pybispectra_env
$ pip install pybispectra
conda create -n pybispectra_env
conda activate pybispectra_env
conda install -c conda-forge pip
pip install pybispectra
16 changes: 9 additions & 7 deletions examples/plot_compute_general.py
Original file line number Diff line number Diff line change
@@ -81,7 +81,7 @@
data=fft_coeffs, freqs=freqs, sampling_freq=sampling_freq, verbose=False
) # initialise object
pac.compute(indices=((0,), (1,))) # compute PAC
pac_results = pac.results.get_results() # extract results array
pac_results = pac.results.get_results(copy=False) # extract results array
pac.results.plot(f1s=(5, 15), f2s=(55, 65)) # plot PAC

########################################################################################
@@ -125,15 +125,15 @@
f2s=bs.results.f2s,
name="PAC | Bispectrum (manual)",
)
bs_pac_results = bs_pac.get_results()
bs_pac_results = bs_pac.get_results(copy=False)

# compare general and dedicated class results
if np.all(
bs_pac_results[~np.isnan(bs_pac_results)] == pac_results[~np.isnan(pac_results)]
):
print("Results are identical!")
else:
print("Results are not identical!")
raise ValueError("Results are not identical!")

pac.results.plot(f1s=(5, 15), f2s=(55, 65)) # dedicated class
bs_pac.plot(f1s=(5, 15), f2s=(55, 65)) # general class
@@ -170,7 +170,9 @@
norm.compute(indices=((0,), (1,), (1,))) # kmn = xyy

# normalise the bispectrum
bicoh = np.abs(bs.results.get_results() / norm.results.get_results())
bicoh = np.abs(
bs.results.get_results(copy=False) / norm.results.get_results(copy=False)
)

# package bicoherence results
bicoh_pac = ResultsCFC(
@@ -180,7 +182,7 @@
f2s=bs.results.f2s,
name="PAC | Bicoherence (manual)",
)
bicoh_pac_results = bicoh_pac.get_results()
bicoh_pac_results = bicoh_pac.get_results(copy=False)

########################################################################################
# Comparing these bicoherence values with those obtained from the dedicated
@@ -194,7 +196,7 @@
data=fft_coeffs, freqs=freqs, sampling_freq=sampling_freq, verbose=False
) # initialise object
pac_norm.compute(indices=((0,), (1,)), norm=True) # compute PAC
pac_norm_results = pac_norm.results.get_results() # extract results array
pac_norm_results = pac_norm.results.get_results(copy=False) # extract results array

# compare general and dedicated class results
if np.all(
@@ -203,7 +205,7 @@
):
print("Results are identical!")
else:
print("Results are not identical!")
raise ValueError("Results are not identical!")

pac_norm.results.plot(f1s=(5, 15), f2s=(55, 65)) # dedicated class
bicoh_pac.plot(f1s=(5, 15), f2s=(55, 65)) # general class
12 changes: 5 additions & 7 deletions examples/plot_compute_pac.py
Original file line number Diff line number Diff line change
@@ -116,7 +116,7 @@
) # initialise object
pac.compute(indices=((0,), (1,))) # compute PAC

pac_results = pac.results.get_results() # return results as array
pac_results = pac.results.get_results(copy=False) # return results as array

print(
f"PAC results: [{pac_results.shape[0]} connection x {pac_results.shape[1]} f1s x "
@@ -179,12 +179,10 @@
)
pac_standard, pac_antisym = pac.results

vmin = np.min(
(np.nanmin(pac_standard.get_results()), np.nanmin(pac_antisym.get_results()))
)
vmax = np.max(
(np.nanmax(pac_standard.get_results()), np.nanmax(pac_antisym.get_results()))
)
pac_standard_array = pac_standard.get_results(copy=False)
pac_antisym_array = pac_antisym.get_results(copy=False)
vmin = np.min((np.nanmin(pac_standard_array), np.nanmin(pac_antisym_array)))
vmax = np.max((np.nanmax(pac_standard_array), np.nanmax(pac_antisym_array)))

# plot unsymmetrised PAC within & between signals
fig_standard, axes_standard = pac_standard.plot(
2 changes: 1 addition & 1 deletion examples/plot_compute_tde.py
Original file line number Diff line number Diff line change
@@ -159,7 +159,7 @@
tde.compute(indices=((0, 1), (1, 0)), method=1) # compute TDE
tde_times = tde.results.times

tde_results = tde.results.get_results() # return results as array
tde_results = tde.results.get_results(copy=False) # return results as array

print(
f"TDE results: [{tde_results.shape[0]} connections x {tde_results.shape[1]} "
2 changes: 1 addition & 1 deletion examples/plot_compute_waveshape.py
Original file line number Diff line number Diff line change
@@ -171,7 +171,7 @@
waveshape_peaks_troughs.compute(f1s=(5, 35), f2s=(5, 35)) # compute waveshape

# return results as an array
waveshape_results = waveshape_sawtooths.results.get_results()
waveshape_results = waveshape_sawtooths.results.get_results(copy=False)

print(
f"Waveshape results: [{waveshape_results.shape[0]} channels x "
Loading

0 comments on commit 1d07e96

Please sign in to comment.