Skip to main content

The Python Toolbox for Neurophysiological Signal Processing.

Project description

https://raw.github.com/neuropsychology/NeuroKit/master/docs/img/banner.png https://img.shields.io/pypi/pyversions/neurokit2.svg?logo=python&logoColor=FFE873 https://img.shields.io/pypi/dm/neurokit2 https://img.shields.io/pypi/v/neurokit2.svg?logo=pypi&logoColor=FFE873 https://img.shields.io/travis/neuropsychology/neurokit/master?label=Travis%20CI&logo=travis https://codecov.io/gh/neuropsychology/NeuroKit/branch/master/graph/badge.svg Maintainability

The Python Toolbox for Neurophysiological Signal Processing

This package is the continuation of NeuroKit 1. It’s a user-friendly package providing easy access to advanced biosignal processing routines. Researchers and clinicians without extensive knowledge of programming or biomedical signal processing can analyze physiological data with only two lines of code.

Quick Example

import neurokit2 as nk

# Download example data
data = nk.data("bio_eventrelated_100hz")

# Preprocess the data (filter, find peaks, etc.)
processed_data, info = nk.bio_process(ecg=data["ECG"], rsp=data["RSP"], eda=data["EDA"], sampling_rate=100)

# Compute relevant features
results = nk.bio_analyze(processed_data, sampling_rate=100)

And boom 💥 your analysis is done 😎

Installation

You can install NeuroKit2 from PyPI

pip install neurokit2

or conda-forge

conda install -c conda-forge neurokit2

If you’re not sure what to do, read our installation guide.

Contributing

License GitHub CI Black code

NeuroKit2 is the most welcoming project with a large community of contributors with all levels of programming expertise. But the package is still far from being perfect! Thus, if you have some ideas for improvement, new features, or just want to learn Python and do something useful at the same time, do not hesitate and check out the following guides:

Citation

https://zenodo.org/badge/218212111.svg https://img.shields.io/badge/details-authors-purple.svg?colorB=9C27B0

The NeuroKit paper can be found here 🎉 Additionally, you can get the reference directly from Python by running:

nk.cite()
You can cite NeuroKit2 as follows:

- Makowski, D., Pham, T., Lau, Z. J., Brammer, J. C., Lespinasse, F., Pham, H.,
Schölzel, C., & Chen, S. A. (2021). NeuroKit2: A Python toolbox for neurophysiological signal processing.
Behavior Research Methods. https://doi.org/10.3758/s13428-020-01516-y

Full bibtex reference:

@article{Makowski2021neurokit,
    author={Makowski, Dominique and Pham, Tam and Lau, Zen J. and Brammer, Jan C. and Lespinasse, Fran{\c{c}}ois and Pham, Hung and Sch{\"o}lzel, Christopher and Chen, S. H. Annabel},
    title={NeuroKit2: A Python toolbox for neurophysiological signal processing},
    journal={Behavior Research Methods},
    year={2021},
    month={Feb},
    day={02},
    issn={1554-3528},
    doi={10.3758/s13428-020-01516-y},
    url={https://doi.org/10.3758/s13428-020-01516-y}
}

Let us know if you used NeuroKit in a publication! Open a new discussion (select the NK in publications category) and link the paper. The community would be happy to know about how you used it and learn about your research. We could also feature it once we have a section on the website for papers that used the software.

Physiological Data Preprocessing

Simulate physiological signals

import numpy as np
import pandas as pd
import neurokit2 as nk

# Generate synthetic signals
ecg = nk.ecg_simulate(duration=10, heart_rate=70)
ppg = nk.ppg_simulate(duration=10, heart_rate=70)
rsp = nk.rsp_simulate(duration=10, respiratory_rate=15)
eda = nk.eda_simulate(duration=10, scr_number=3)
emg = nk.emg_simulate(duration=10, burst_number=2)

# Visualise biosignals
data = pd.DataFrame({"ECG": ecg,
                     "PPG": ppg,
                     "RSP": rsp,
                     "EDA": eda,
                     "EMG": emg})
nk.signal_plot(data, subplots=True)
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_simulation.png

Electrodermal Activity (EDA/GSR)

# Generate 10 seconds of EDA signal (recorded at 250 samples / second) with 2 SCR peaks
eda = nk.eda_simulate(duration=10, sampling_rate=250, scr_number=2, drift=0.01)

# Process it
signals, info = nk.eda_process(eda, sampling_rate=250)

# Visualise the processing
nk.eda_plot(signals, sampling_rate=250)
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_eda.png

Cardiac activity (ECG)

# Generate 15 seconds of ECG signal (recorded at 250 samples / second)
ecg = nk.ecg_simulate(duration=15, sampling_rate=250, heart_rate=70)

# Process it
signals, info = nk.ecg_process(ecg, sampling_rate=250)

# Visualise the processing
nk.ecg_plot(signals, sampling_rate=250)
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_ecg.png

Respiration (RSP)

# Generate one minute of respiratory (RSP) signal (recorded at 250 samples / second)
rsp = nk.rsp_simulate(duration=60, sampling_rate=250, respiratory_rate=15)

# Process it
signals, info = nk.rsp_process(rsp, sampling_rate=250)

# Visualise the processing
nk.rsp_plot(signals, sampling_rate=250)
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_rsp.png

Electromyography (EMG)

# Generate 10 seconds of EMG signal (recorded at 250 samples / second)
emg = nk.emg_simulate(duration=10, sampling_rate=250, burst_number=3)

# Process it
signal, info = nk.emg_process(emg, sampling_rate=250)

# Visualise the processing
nk.emg_plot(signals, sampling_rate=250)
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_emg.png

Photoplethysmography (PPG/BVP)

# Generate 15 seconds of PPG signal (recorded at 250 samples / second)
ppg = nk.ppg_simulate(duration=15, sampling_rate=250, heart_rate=70)

# Process it
signals, info = nk.ppg_process(ppg, sampling_rate=250)

# Visualize the processing
nk.ppg_plot(signals, sampling_rate=250)
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_ppg.png

Electrooculography (EOG)

# Import EOG data
eog_signal = nk.data("eog_100hz")

# Process it
signals, info = nk.eog_process(eog_signal, sampling_rate=100)

# Plot
plot = nk.eog_plot(signals, sampling_rate=100)
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_eog.png

Electrogastrography (EGG)

Consider helping us develop it!

Physiological Data Analysis

The analysis of physiological data usually comes in two types, event-related or interval-related.

https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/features.png

Miscellaneous

Heart Rate Variability (HRV)

  • Compute HRV indices
    • Time domain: RMSSD, MeanNN, SDNN, SDSD, CVNN etc.
    • Frequency domain: Spectral power density in various frequency bands (Ultra low/ULF, Very low/VLF, Low/LF, High/HF, Very high/VHF), Ratio of LF to HF power, Normalized LF (LFn) and HF (HFn), Log transformed HF (LnHF).
    • Nonlinear domain: Spread of RR intervals (SD1, SD2, ratio between SD2 to SD1), Cardiac Sympathetic Index (CSI), Cardial Vagal Index (CVI), Modified CSI, Sample Entropy (SampEn).
# Download data
data = nk.data("bio_resting_8min_100hz")

# Find peaks
peaks, info = nk.ecg_peaks(data["ECG"], sampling_rate=100)

# Compute HRV indices
nk.hrv(peaks, sampling_rate=100, show=True)
>>>    HRV_RMSSD  HRV_MeanNN   HRV_SDNN  ...   HRV_CVI  HRV_CSI_Modified  HRV_SampEn
>>> 0  69.697983  696.395349  62.135891  ...  4.829101        592.095372    1.259931
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_hrv.png

ECG Delineation

  • Delineate the QRS complex of an electrocardiac signal (ECG) including P-peaks, T-peaks, as well as their onsets and offsets.
# Download data
ecg_signal = nk.data(dataset="ecg_3000hz")['ECG']

# Extract R-peaks locations
_, rpeaks = nk.ecg_peaks(ecg_signal, sampling_rate=3000)

# Delineate
signal, waves = nk.ecg_delineate(ecg_signal, rpeaks, sampling_rate=3000, method="dwt", show=True, show_type='all')
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_delineate.png

Signal Processing

  • Signal processing functionalities
    • Filtering: Using different methods.
    • Detrending: Remove the baseline drift or trend.
    • Distorting: Add noise and artifacts.
# Generate original signal
original = nk.signal_simulate(duration=6, frequency=1)

# Distort the signal (add noise, linear trend, artifacts etc.)
distorted = nk.signal_distort(original,
                              noise_amplitude=0.1,
                              noise_frequency=[5, 10, 20],
                              powerline_amplitude=0.05,
                              artifacts_amplitude=0.3,
                              artifacts_number=3,
                              linear_drift=0.5)

# Clean (filter and detrend)
cleaned = nk.signal_detrend(distorted)
cleaned = nk.signal_filter(cleaned, lowcut=0.5, highcut=1.5)

# Compare the 3 signals
plot = nk.signal_plot([original, distorted, cleaned])
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_signalprocessing.png

Complexity (Entropy, Fractal Dimensions, …)

  • Optimize complexity parameters (delay tau, dimension m, tolerance r)
# Generate signal
signal = nk.signal_simulate(frequency=[1, 3], noise=0.01, sampling_rate=100)

# Find optimal time delay, embedding dimension and r
parameters = nk.complexity_optimize(signal, show=True)
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_complexity_optimize.png
  • Compute complexity features
    • Entropy: Sample Entropy (SampEn), Approximate Entropy (ApEn), Fuzzy Entropy (FuzzEn), Multiscale Entropy (MSE), Shannon Entropy (ShEn)
    • Fractal dimensions: Correlation Dimension D2, …
    • Detrended Fluctuation Analysis
nk.entropy_sample(signal)
nk.entropy_approximate(signal)

Signal Decomposition

# Create complex signal
signal = nk.signal_simulate(duration=10, frequency=1)  # High freq
signal += 3 * nk.signal_simulate(duration=10, frequency=3)  # Higher freq
signal += 3 * np.linspace(0, 2, len(signal))  # Add baseline and linear trend
signal += 2 * nk.signal_simulate(duration=10, frequency=0.1, noise=0)  # Non-linear trend
signal += np.random.normal(0, 0.02, len(signal))  # Add noise

# Decompose signal using Empirical Mode Decomposition (EMD)
components = nk.signal_decompose(signal, method='emd')
nk.signal_plot(components)  # Visualize components

# Recompose merging correlated components
recomposed = nk.signal_recompose(components, threshold=0.99)
nk.signal_plot(recomposed)  # Visualize components
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_decomposition.png

Signal Power Spectrum Density (PSD)

# Generate complex signal
signal = nk.signal_simulate(duration=20, frequency=[0.5, 5, 10, 15], amplitude=[2, 1.5, 0.5, 0.3], noise=0.025)

# Get the PSD using different methods
welch = nk.signal_psd(signal, method="welch", min_frequency=1, max_frequency=20, show=True)
multitaper = nk.signal_psd(signal, method="multitapers", max_frequency=20, show=True)
lomb = nk.signal_psd(signal, method="lomb", min_frequency=1, max_frequency=20, show=True)
burg = nk.signal_psd(signal, method="burg", min_frequency=1, max_frequency=20, order=10, show=True)
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_psd.png

Statistics

  • Highest Density Interval (HDI)
x = np.random.normal(loc=0, scale=1, size=100000)

ci_min, ci_max = nk.hdi(x, ci=0.95, show=True)
https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_hdi.png

Popularity

https://img.shields.io/pypi/dd/neurokit2 https://img.shields.io/github/stars/neuropsychology/NeuroKit https://img.shields.io/github/forks/neuropsychology/NeuroKit

NeuroKit2 is one of the most welcoming package for new contributors and users, as well as the fastest growing package. So stop hesitating and hop onboard 🤗

https://raw.github.com/neuropsychology/NeuroKit/master/docs/readme/README_popularity.png

Notes

The authors do not provide any warranty. If this software causes your keyboard to blow up, your brain to liquefy, your toilet to clog or a zombie plague to break loose, the authors CANNOT IN ANY WAY be held responsible.

News

0.0.1 (2019-10-29)

  • First release on PyPI.

0.1.1

New Features

  • Use duration from nk.events_find() as epochs_end in nk.epochs_create()
  • Allow customized subsets of epoch lengths in nk.bio_analyze() with window_lengths argument
  • Add nk.find_outliers() to identify outliers (abnormal values)
  • Add utility function - nk.check_type() to return appropriate boolean values of input (integer, list, ndarray, pandas dataframe or pandas series)
  • (experimental) Add error bars in the summary plot method to illustrate standard error of each bin

Fix Bugs

  • Fix type of value in nk.signal_formatpeaks() to ensure slice assignment is done on the same type

0.1.2

New Features

  • Additional features for nk.rsp_intervalrelated(): average inspiratory and expiratory durations, inspiratory-to-expiratory (I/E) time ratio
  • Add multiscale entropy measures (MSE, CMSE, RCMSE) and fractal methods (Detrended Fluctuation Analysis, Correlation Dimension) into nk.hrv_nonlinear()
  • Allow for data resampling in nk.read_bitalino()
  • Add bio_resting_8min_200hz into database for reading with nk.data()
  • Reading of url links in nk.data()
  • Allow for nk.hrv() to compute RSA indices if respiratory data is present
  • All hrv functions to automatically detect correct sampling rate if tuple or dict is passed as input
  • Add support for PPG analysis: nk.ppg_eventrelated(), nk.ppg_intervalrelated(), nk.ppg_analyze()
  • Add Zhao et al. (2018) method for nk.ecg_quality()
  • Add tests for epochs module
  • Add sub-epoch option for ECG and RSP event-related analysis:
    • users can create a smaller sub-epoch within the event-related epoch
    • the rate-related features of ECG and RSP signals are calculated over the sub-epoch
    • the remaining features are calculated over the original epoch, not the sub-epoch

Fix Bugs

  • Fix propagation of values in nk.signal_formatpeaks() for formatting SCR column outputs generated by eda_peaks()
  • Fix docstrings of nk.rsp_phase(), from “RSP_Inspiration” to “RSP_Phase”
  • Update signal_filter() method for rsp_clean(): to use sos form, instead of ba form of butterworth (similar to eda_clean())

Project details


Download files

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

Files for neurokit2, version 0.1.2
Filename, size File type Python version Upload date Hashes
Filename, size neurokit2-0.1.2-py2.py3-none-any.whl (1.0 MB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size neurokit2-0.1.2.tar.gz (19.5 MB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page