========================================================
bycycle - cycle-by-cycle analysis of neural oscillations
========================================================
|ProjectStatus|_ |Version|_ |BuildStatus|_ |Coverage|_ |License|_ |PythonVersions|_ |Publication|_
.. |ProjectStatus| image:: https://www.repostatus.org/badges/latest/active.svg
.. _ProjectStatus: https://www.repostatus.org/#active
.. |Version| image:: https://img.shields.io/pypi/v/bycycle.svg
.. _Version: https://pypi.python.org/pypi/bycycle/
.. |BuildStatus| image:: https://github.com/bycycle-tools/bycycle/actions/workflows/build.yml/badge.svg
.. _BuildStatus: https://github.com/bycycle-tools/bycycle/actions/workflows/build.yml
.. |Coverage| image:: https://codecov.io/gh/bycycle-tools/bycycle/branch/main/graph/badge.svg
.. _Coverage: https://codecov.io/gh/bycycle-tools/bycycle
.. |License| image:: https://img.shields.io/pypi/l/bycycle.svg
.. _License: https://opensource.org/licenses/Apache-2.0
.. |PythonVersions| image:: https://img.shields.io/pypi/pyversions/bycycle.svg
.. _PythonVersions: https://pypi.python.org/pypi/bycycle/
.. |Publication| image:: https://img.shields.io/badge/publication-10.1152%2Fjn.00273.2019-blue
.. _Publication: https://journals.physiology.org/doi/abs/10.1152/jn.00273.2019
ByCycle is a module for analyzing neural oscillations in a cycle-by-cycle approach.
Overview
--------
``bycycle`` is a tool for quantifying features of neural oscillations in the time domain, as opposed to the
frequency domain, using a cycle-by-cycle approach. Rather than applying narrowband filters and other methods
that use a sinusoidal basis, this approach segments a recording into individual cycles and directly measures
each of their properties including amplitude, period, and symmetry.
This is most advantageous for analyzing the waveform shape properties of neural oscillations.
It may also provide advantages for studying traditional amplitude and frequency effects, as well.
Using cycle properties can also be used for burst detection.
A full description of the method and approach is available in the paper below.
Documentation
-------------
Documentation for ``bycycle`` is available on the
`documentation site <https://bycycle-tools.github.io/bycycle/index.html>`_.
This documentation includes:
- `Tutorials <https://bycycle-tools.github.io/bycycle/auto_tutorials/index.html>`_:
with a step-by-step guide through the approach and how to apply it
- `Examples <https://bycycle-tools.github.io/bycycle/auto_examples/index.html>`_:
demonstrating an example analysis and use case
- `API list <https://bycycle-tools.github.io/bycycle/api.html>`_:
which lists and describes all the code and functionality available in the module
- `Glossary <https://bycycle-tools.github.io/bycycle/glossary.html>`_:
which defines key terms used in the module
Dependencies
------------
``bycycle`` is written in Python, and requires >= Python 3.6 to run.
It has the following dependencies:
- `neurodsp <https://github.com/neurodsp-tools/neurodsp>`_ >= 2.1.0
- `numpy <https://github.com/numpy/numpy>`_ >= 1.18.5
- `scipy <https://github.com/scipy/scipy>`_ >= 1.4.1
- `pandas <https://github.com/pandas-dev/pandas>`_ >= 0.25.3
- `matplotlib <https://github.com/matplotlib/matplotlib>`_ >= 3.0.3
There are also optional dependencies, that offer extra functionality:
- `tqdm <https://github.com/tqdm/tqdm>`_ is needed to print progress bars
- `pytest <https://github.com/pytest-dev/pytest>`_ is needed to run tests locally
Install
-------
The current major release is the 1.X.X series, which is a breaking change from the prior 0.X.X series.
Check the `changelog <https://bycycle-tools.github.io/bycycle/changelog.html>`_ for notes on updating to the new version.
**Stable Version**
To install the latest stable release, you can use pip:
.. code-block:: shell
$ pip install bycycle
ByCycle can also be installed with conda, from the conda-forge channel:
.. code-block:: shell
$ conda install -c conda-forge bycycle
**Development Version**
To get the latest, development version, you can get the code using git:
.. code-block:: shell
$ git clone https://github.com/bycycle-tools/bycycle
To install this cloned copy, move into the directory you just cloned, and run:
.. code-block:: shell
$ pip install .
**Editable Version**
To install an editable, development version, move into the directory you cloned and install with:
.. code-block:: shell
$ pip install -e .
Reference
---------
If you use this code in your project, please cite:
::
Cole SR & Voytek B (2019) Cycle-by-cycle analysis of neural oscillations. Journal of neurophysiology
122(2), 849-861. DOI: 10.1152/jn.00273.2019
Direct Link: https://doi.org/10.1152/jn.00273.2019
Contribute
----------
This project welcomes and encourages contributions from the community!
To file bug reports and/or ask questions about this project, please use the
`Github issue tracker <https://github.com/bycycle-tools/bycycle/issues>`_.
To see and get involved in discussions about the module, check out:
- the `issues board <https://github.com/bycycle-tools/bycycle/issues>`_ for topics relating to code updates, bugs, and fixes
- the `development page <https://github.com/bycycle-tools/Development>`_ for discussion of potential major updates to the module
When interacting with this project, please use the
`contribution guidelines <https://github.com/bycycle-tools/bycycle/blob/main/CONTRIBUTING.md>`_
and follow the
`code of conduct <https://github.com/bycycle-tools/bycycle/blob/main/CODE_OF_CONDUCT.md>`_.
Quickstart
----------
The classes in ``bycycle`` are ``Bycycle``, which takes a time series and some
parameters as inputs, and returns a table of features for each cycle. ``BycycleGroup``
may be used when working with 2d and 3d signals.
For example, consider having a 1-dimensional numpy array, ``sig``, which is a neural signal time series
sampled at 1000 Hz (``fs``) with an alpha (8-12 Hz, ``f_range``) oscillation. We can compute the table
of cycle features with the following:
.. code-block:: python
from neurodsp.sim import sim_bursty_oscillation
from bycycle import Bycycle
# Simulate
fs = 1000
f_range = (8, 12)
sig = sim_bursty_oscillation(10, fs, freq=10)
# Fit
bm = Bycycle()
bm.fit(sig, fs, f_range)
bm.df_features
The above example used default parameters to localize extrema and detect
bursts of oscillations. However, it is important to knowledgeably select these parameters, as described in the
`algorithm tutorial <https://bycycle-tools.github.io/bycycle/auto_tutorials/plot_2_bycycle_algorithm.html>`_.
The following example introduces some potential parameter changes:
.. code-block:: python
thresholds = {
'amp_fraction_threshold': .2,
'amp_consistency_threshold': .5,
'period_consistency_threshold': .5,
'monotonicity_threshold': .8,
'min_n_cycles': 3
}
narrowband_kwargs = {'n_seconds': .5}
bm = Bycycle(
center_extrema='trough',
burst_method='cycles',
thresholds=thresholds,
find_extrema_kwargs={'filter_kwargs': narrowband_kwargs}
)
bm.fit(sig, fs, f_range)
- **center_extrema** determines how the cycles are segmented. 'T' indicates the center extrema is \
a trough, so cycles are segmented peak-to-peak.
- **burst_method** selects which method to use for burst detection. The 'cycles' option \
uses features of adjacent cycles in order to detect bursts (e.g. period consistency, see next \
item). The 'amp' option uses an amplitude threshold to determine the cycles that are part of an \
oscillatory burst.
- **thresholds** sets the keyword arguments for the burst detection functions. For the \
``cycles`` method, there are 5 keyword arguments (see the end of the \
`algorithm tutorial <https://bycycle-tools.github.io/bycycle/auto_tutorials/plot_2_bycycle_algorithm.html>`_ \
for advice on choosing these parameters).
- **find_extrema_kwargs** sets the keyword arguments for the function used to localize peaks and \
troughs. Most notably, you can change the duration of the bandpass filter (``n_seconds``) used \
during extrema localization (see section 1 of the \
`algorithm tutorial <https://bycycle-tools.github.io/bycycle/auto_tutorials/plot_2_bycycle_algorithm.html>`_)
DataFrame Output
~~~~~~~~~~~~~~~~
The output of ``bycycle`` is a ``pandas.DataFrame``, which is a table, as shown below.
There are many columns, so the table is split into two images here.
Each row of this table corresponds to an individual segment of the signal, or a putative cycle of
the rhythm of interest.
.. image:: https://github.com/bycycle-tools/bycycle/raw/main/doc/img/cycledf_1.png
|
.. image:: https://github.com/bycycle-tools/bycycle/raw/main/doc/img/cycledf_2.png
Columns include:
- **sample_peak**: the sample of the signal at which the peak of this cycle occurs
- **period**: period of the cycle
- **time_peak**: duration of the peak period
- **volt_amp**: amplitude of this cycle, average of the rise and decay voltage
- **time_rdsym**: rise-decay symmetry, the fraction of the cycle in the rise period (0.5 is symmetric)
- **time_ptsym**: peak-trough symmetry, the fraction of the cycle in the peak period (0.5 is symmetric)
- **period_consistency**: consistency between the periods of the adjacent cycles, used in burst detection
- **is_burst**: indicator if the cycle is part of an oscillatory burst
The features in this table can be further analyzed, as demonstrated in the
`resting state data tutorial <https://bycycle-tools.github.io/bycycle/auto_tutorials/plot_2_bycycle_algorithm.html>`_
and the `data example <https://bycycle-tools.github.io/bycycle/auto_examples/plot_1_theta_feature_distributions.html>`_.
For example, we may be interested in the distribution of rise-decay symmetry values in a resting state recording, shown below.
Burst Detection Results
~~~~~~~~~~~~~~~~~~~~~~~
.. image:: https://github.com/bycycle-tools/bycycle/raw/main/doc/img/bursts_detected.png
Funding
-------
Supported by NIH award R01 GM134363 from the
`NIGMS <https://www.nigms.nih.gov/>`_.
.. image:: https://www.nih.gov/sites/all/themes/nih/images/nih-logo-color.png
:width: 400
|
Raw data
{
"_id": null,
"home_page": "https://github.com/bycycle-tools/bycycle",
"name": "bycycle",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "neuroscience,neural oscillations,waveform,shape,electrophysiology",
"author": "The Voytek Lab",
"author_email": "voyteklab@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/34/f9/934fbca04a9f3f996fc7e654cbbb17ba1f534abbb5a8dc87d0da69999c9e/bycycle-1.1.0.tar.gz",
"platform": "any",
"description": "========================================================\nbycycle - cycle-by-cycle analysis of neural oscillations\n========================================================\n\n|ProjectStatus|_ |Version|_ |BuildStatus|_ |Coverage|_ |License|_ |PythonVersions|_ |Publication|_\n\n.. |ProjectStatus| image:: https://www.repostatus.org/badges/latest/active.svg\n.. _ProjectStatus: https://www.repostatus.org/#active\n\n.. |Version| image:: https://img.shields.io/pypi/v/bycycle.svg\n.. _Version: https://pypi.python.org/pypi/bycycle/\n\n.. |BuildStatus| image:: https://github.com/bycycle-tools/bycycle/actions/workflows/build.yml/badge.svg\n.. _BuildStatus: https://github.com/bycycle-tools/bycycle/actions/workflows/build.yml\n\n.. |Coverage| image:: https://codecov.io/gh/bycycle-tools/bycycle/branch/main/graph/badge.svg\n.. _Coverage: https://codecov.io/gh/bycycle-tools/bycycle\n\n.. |License| image:: https://img.shields.io/pypi/l/bycycle.svg\n.. _License: https://opensource.org/licenses/Apache-2.0\n\n.. |PythonVersions| image:: https://img.shields.io/pypi/pyversions/bycycle.svg\n.. _PythonVersions: https://pypi.python.org/pypi/bycycle/\n\n.. |Publication| image:: https://img.shields.io/badge/publication-10.1152%2Fjn.00273.2019-blue\n.. _Publication: https://journals.physiology.org/doi/abs/10.1152/jn.00273.2019\n\nByCycle is a module for analyzing neural oscillations in a cycle-by-cycle approach.\n\nOverview\n--------\n\n``bycycle`` is a tool for quantifying features of neural oscillations in the time domain, as opposed to the\nfrequency domain, using a cycle-by-cycle approach. Rather than applying narrowband filters and other methods\nthat use a sinusoidal basis, this approach segments a recording into individual cycles and directly measures\neach of their properties including amplitude, period, and symmetry.\n\nThis is most advantageous for analyzing the waveform shape properties of neural oscillations.\nIt may also provide advantages for studying traditional amplitude and frequency effects, as well.\nUsing cycle properties can also be used for burst detection.\n\nA full description of the method and approach is available in the paper below.\n\nDocumentation\n-------------\n\nDocumentation for ``bycycle`` is available on the\n`documentation site <https://bycycle-tools.github.io/bycycle/index.html>`_.\n\nThis documentation includes:\n\n- `Tutorials <https://bycycle-tools.github.io/bycycle/auto_tutorials/index.html>`_:\n with a step-by-step guide through the approach and how to apply it\n- `Examples <https://bycycle-tools.github.io/bycycle/auto_examples/index.html>`_:\n demonstrating an example analysis and use case\n- `API list <https://bycycle-tools.github.io/bycycle/api.html>`_:\n which lists and describes all the code and functionality available in the module\n- `Glossary <https://bycycle-tools.github.io/bycycle/glossary.html>`_:\n which defines key terms used in the module\n\nDependencies\n------------\n\n``bycycle`` is written in Python, and requires >= Python 3.6 to run.\n\nIt has the following dependencies:\n\n- `neurodsp <https://github.com/neurodsp-tools/neurodsp>`_ >= 2.1.0\n- `numpy <https://github.com/numpy/numpy>`_ >= 1.18.5\n- `scipy <https://github.com/scipy/scipy>`_ >= 1.4.1\n- `pandas <https://github.com/pandas-dev/pandas>`_ >= 0.25.3\n- `matplotlib <https://github.com/matplotlib/matplotlib>`_ >= 3.0.3\n\nThere are also optional dependencies, that offer extra functionality:\n\n- `tqdm <https://github.com/tqdm/tqdm>`_ is needed to print progress bars\n- `pytest <https://github.com/pytest-dev/pytest>`_ is needed to run tests locally\n\nInstall\n-------\n\nThe current major release is the 1.X.X series, which is a breaking change from the prior 0.X.X series.\n\nCheck the `changelog <https://bycycle-tools.github.io/bycycle/changelog.html>`_ for notes on updating to the new version.\n\n**Stable Version**\n\nTo install the latest stable release, you can use pip:\n\n.. code-block:: shell\n\n $ pip install bycycle\n\nByCycle can also be installed with conda, from the conda-forge channel:\n\n.. code-block:: shell\n\n $ conda install -c conda-forge bycycle\n\n**Development Version**\n\nTo get the latest, development version, you can get the code using git:\n\n.. code-block:: shell\n\n $ git clone https://github.com/bycycle-tools/bycycle\n\nTo install this cloned copy, move into the directory you just cloned, and run:\n\n.. code-block:: shell\n\n $ pip install .\n\n**Editable Version**\n\nTo install an editable, development version, move into the directory you cloned and install with:\n\n.. code-block:: shell\n\n $ pip install -e .\n\nReference\n---------\n\nIf you use this code in your project, please cite:\n\n::\n\n Cole SR & Voytek B (2019) Cycle-by-cycle analysis of neural oscillations. Journal of neurophysiology\n 122(2), 849-861. DOI: 10.1152/jn.00273.2019\n\nDirect Link: https://doi.org/10.1152/jn.00273.2019\n\nContribute\n----------\n\nThis project welcomes and encourages contributions from the community!\n\nTo file bug reports and/or ask questions about this project, please use the\n`Github issue tracker <https://github.com/bycycle-tools/bycycle/issues>`_.\n\nTo see and get involved in discussions about the module, check out:\n\n- the `issues board <https://github.com/bycycle-tools/bycycle/issues>`_ for topics relating to code updates, bugs, and fixes\n- the `development page <https://github.com/bycycle-tools/Development>`_ for discussion of potential major updates to the module\n\nWhen interacting with this project, please use the\n`contribution guidelines <https://github.com/bycycle-tools/bycycle/blob/main/CONTRIBUTING.md>`_\nand follow the\n`code of conduct <https://github.com/bycycle-tools/bycycle/blob/main/CODE_OF_CONDUCT.md>`_.\n\nQuickstart\n----------\n\nThe classes in ``bycycle`` are ``Bycycle``, which takes a time series and some\nparameters as inputs, and returns a table of features for each cycle. ``BycycleGroup``\nmay be used when working with 2d and 3d signals.\n\nFor example, consider having a 1-dimensional numpy array, ``sig``, which is a neural signal time series\nsampled at 1000 Hz (``fs``) with an alpha (8-12 Hz, ``f_range``) oscillation. We can compute the table\nof cycle features with the following:\n\n.. code-block:: python\n\n from neurodsp.sim import sim_bursty_oscillation\n from bycycle import Bycycle\n\n # Simulate\n fs = 1000\n\n f_range = (8, 12)\n\n sig = sim_bursty_oscillation(10, fs, freq=10)\n\n # Fit\n bm = Bycycle()\n\n bm.fit(sig, fs, f_range)\n\n bm.df_features\n\n\nThe above example used default parameters to localize extrema and detect\nbursts of oscillations. However, it is important to knowledgeably select these parameters, as described in the\n`algorithm tutorial <https://bycycle-tools.github.io/bycycle/auto_tutorials/plot_2_bycycle_algorithm.html>`_.\n\nThe following example introduces some potential parameter changes:\n\n.. code-block:: python\n\n thresholds = {\n 'amp_fraction_threshold': .2,\n 'amp_consistency_threshold': .5,\n 'period_consistency_threshold': .5,\n 'monotonicity_threshold': .8,\n 'min_n_cycles': 3\n }\n\n narrowband_kwargs = {'n_seconds': .5}\n\n bm = Bycycle(\n center_extrema='trough',\n burst_method='cycles',\n thresholds=thresholds,\n find_extrema_kwargs={'filter_kwargs': narrowband_kwargs}\n )\n\n bm.fit(sig, fs, f_range)\n\n\n- **center_extrema** determines how the cycles are segmented. 'T' indicates the center extrema is \\\n a trough, so cycles are segmented peak-to-peak.\n- **burst_method** selects which method to use for burst detection. The 'cycles' option \\\n uses features of adjacent cycles in order to detect bursts (e.g. period consistency, see next \\\n item). The 'amp' option uses an amplitude threshold to determine the cycles that are part of an \\\n oscillatory burst.\n- **thresholds** sets the keyword arguments for the burst detection functions. For the \\\n ``cycles`` method, there are 5 keyword arguments (see the end of the \\\n `algorithm tutorial <https://bycycle-tools.github.io/bycycle/auto_tutorials/plot_2_bycycle_algorithm.html>`_ \\\n for advice on choosing these parameters).\n- **find_extrema_kwargs** sets the keyword arguments for the function used to localize peaks and \\\n troughs. Most notably, you can change the duration of the bandpass filter (``n_seconds``) used \\\n during extrema localization (see section 1 of the \\\n `algorithm tutorial <https://bycycle-tools.github.io/bycycle/auto_tutorials/plot_2_bycycle_algorithm.html>`_)\n\nDataFrame Output\n~~~~~~~~~~~~~~~~\n\nThe output of ``bycycle`` is a ``pandas.DataFrame``, which is a table, as shown below.\nThere are many columns, so the table is split into two images here.\n\nEach row of this table corresponds to an individual segment of the signal, or a putative cycle of\nthe rhythm of interest.\n\n.. image:: https://github.com/bycycle-tools/bycycle/raw/main/doc/img/cycledf_1.png\n\n|\n\n.. image:: https://github.com/bycycle-tools/bycycle/raw/main/doc/img/cycledf_2.png\n\nColumns include:\n\n- **sample_peak**: the sample of the signal at which the peak of this cycle occurs\n- **period**: period of the cycle\n- **time_peak**: duration of the peak period\n- **volt_amp**: amplitude of this cycle, average of the rise and decay voltage\n- **time_rdsym**: rise-decay symmetry, the fraction of the cycle in the rise period (0.5 is symmetric)\n- **time_ptsym**: peak-trough symmetry, the fraction of the cycle in the peak period (0.5 is symmetric)\n- **period_consistency**: consistency between the periods of the adjacent cycles, used in burst detection\n- **is_burst**: indicator if the cycle is part of an oscillatory burst\n\nThe features in this table can be further analyzed, as demonstrated in the\n`resting state data tutorial <https://bycycle-tools.github.io/bycycle/auto_tutorials/plot_2_bycycle_algorithm.html>`_\nand the `data example <https://bycycle-tools.github.io/bycycle/auto_examples/plot_1_theta_feature_distributions.html>`_.\nFor example, we may be interested in the distribution of rise-decay symmetry values in a resting state recording, shown below.\n\nBurst Detection Results\n~~~~~~~~~~~~~~~~~~~~~~~\n\n.. image:: https://github.com/bycycle-tools/bycycle/raw/main/doc/img/bursts_detected.png\n\nFunding\n-------\n\nSupported by NIH award R01 GM134363 from the\n`NIGMS <https://www.nigms.nih.gov/>`_.\n\n.. image:: https://www.nih.gov/sites/all/themes/nih/images/nih-logo-color.png\n :width: 400\n\n|\n",
"bugtrack_url": null,
"license": "Apache License, 2.0",
"summary": "Cycle-by-cycle analyses of neural oscillations.",
"version": "1.1.0",
"split_keywords": [
"neuroscience",
"neural oscillations",
"waveform",
"shape",
"electrophysiology"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7f3a8e905ee9e9bca6c11205fa3b9e5cdb0985dc661c8ed0237e4d81baa082c0",
"md5": "af3c51bdbdceede2e1641615d1dd85e1",
"sha256": "e5c4430fd25070d912adfb5eea9247b17ee958ccc31091f1bb5e09d894b2d95a"
},
"downloads": -1,
"filename": "bycycle-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af3c51bdbdceede2e1641615d1dd85e1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 69688,
"upload_time": "2023-04-13T22:18:14",
"upload_time_iso_8601": "2023-04-13T22:18:14.477559Z",
"url": "https://files.pythonhosted.org/packages/7f/3a/8e905ee9e9bca6c11205fa3b9e5cdb0985dc661c8ed0237e4d81baa082c0/bycycle-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "34f9934fbca04a9f3f996fc7e654cbbb17ba1f534abbb5a8dc87d0da69999c9e",
"md5": "73859078d525a96e0f00d7d44826a0e0",
"sha256": "086ae9f8f8f976ae9dc2f9180af384a70d8fe06b60035283754b5b7d7e23c33f"
},
"downloads": -1,
"filename": "bycycle-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "73859078d525a96e0f00d7d44826a0e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 51801,
"upload_time": "2023-04-13T22:18:16",
"upload_time_iso_8601": "2023-04-13T22:18:16.970012Z",
"url": "https://files.pythonhosted.org/packages/34/f9/934fbca04a9f3f996fc7e654cbbb17ba1f534abbb5a8dc87d0da69999c9e/bycycle-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-13 22:18:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "bycycle-tools",
"github_project": "bycycle",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "bycycle"
}
JSON
