Skip to main content

Cycle-by-cycle analyses of neural oscillations.

Project description

ProjectStatus Version BuildStatus Coverage License PythonVersions Publication

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.

This documentation includes:

  • Tutorials: with a step-by-step guide through the approach and how to apply it

  • Examples: demonstrating an example analysis and use case

  • API list: which lists and describes all the code and functionality available in the module

  • Glossary: 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:

There are also optional dependencies, that offer extra functionality:

  • tqdm is needed to print progress bars

  • 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 for notes on updating to the new version.

Stable Version

To install the latest stable release, you can use pip:

$ pip install bycycle

ByCycle can also be installed with conda, from the conda-forge channel:

$ conda install -c conda-forge bycycle

Development Version

To get the latest, development version, you can get the code using git:

$ git clone https://github.com/bycycle-tools/bycycle

To install this cloned copy, move into the directory you just cloned, and run:

$ pip install .

Editable Version

To install an editable, development version, move into the directory you cloned and install with:

$ 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.

To see and get involved in discussions about the module, check out:

  • the issues board for topics relating to code updates, bugs, and fixes

  • the development page for discussion of potential major updates to the module

When interacting with this project, please use the contribution guidelines and follow the code of conduct.

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:

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.

The following example introduces some potential parameter changes:

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 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)

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.

https://github.com/bycycle-tools/bycycle/raw/main/doc/img/cycledf_1.png

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 and the data example. For example, we may be interested in the distribution of rise-decay symmetry values in a resting state recording, shown below.

Burst Detection Results

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.nih.gov/sites/all/themes/nih/images/nih-logo-color.png

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bycycle-1.2.0.tar.gz (55.1 kB view details)

Uploaded Source

Built Distribution

bycycle-1.2.0-py3-none-any.whl (73.6 kB view details)

Uploaded Python 3

File details

Details for the file bycycle-1.2.0.tar.gz.

File metadata

  • Download URL: bycycle-1.2.0.tar.gz
  • Upload date:
  • Size: 55.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for bycycle-1.2.0.tar.gz
Algorithm Hash digest
SHA256 a025ac7f1e04afb0e9364a1ddb6c780d4f23ae11db344b3291a0f18805b4b86b
MD5 389d8561de6d5c1d45aa0828e24e1660
BLAKE2b-256 201866fdaaae2bd5b5277b5fce1c5277dde181818da9ac5936e13711fe0ad53a

See more details on using hashes here.

File details

Details for the file bycycle-1.2.0-py3-none-any.whl.

File metadata

  • Download URL: bycycle-1.2.0-py3-none-any.whl
  • Upload date:
  • Size: 73.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for bycycle-1.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c11f5cc6f27283d996a27d21cbd15af768431795609db7b5c8333ececceb9613
MD5 943b6aff03998b9fde223aab707e3bee
BLAKE2b-256 5ce93a559296b773b0779c18540fcf2f5e440b925600d400601246dee2b95bec

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page