release 0.1.1 dominique makowski - read the docs · 2020-03-30 · ecg signal quality...
Post on 03-Aug-2020
3 Views
Preview:
TRANSCRIPT
neurokit DocumentationRelease 0.1.1
Dominique Makowski
Mar 30, 2020
Contents
1 Tutorials 3
2 Features 13
3 Documentation 15
4 About 55
5 Installation 57
6 Questions? Help? Movie Recommendations? 59
7 Index 61
Index 63
i
ii
neurokit Documentation, Release 0.1.1
NeuroKit is a Python module that provides high-level integrative functions with good and flexible defaults, allowingusers to focus on what’s important.
Contents:
Contents 1
neurokit Documentation, Release 0.1.1
2 Contents
CHAPTER 1
Tutorials
Contents:
1.1 Installing Python
This part focuses on how to get a working, portable distribution of python.
1.1.1 Windows
• Easy (1.5go)
1. Download a working winpython distribution (includes Python 3.7, NeuroKit 0.2.7 and Neuropsydia 1.0.6)
2. Unzip it
3. Open the folder
4. Run Spyder.exe
• Intermediate (> 1.5go)
1. Download a non-zero version of Winython
2. Install it somewhere (desktop’s a good place). It creates a folder called WinPython-XXbits-x.x.x.x
3. In the WinPython-XXbits-x.x.x.x folder open WinPython Command Prompt.exe
4. Run pip install https://github.com/neuropsychology/NeuroKit.py/zipball/master
5. Run pip install https://github.com/neuropsychology/Neuropsydia.py/zipball/master
6. Launch Spyder.exe
• Hard (1.5go)
3
neurokit Documentation, Release 0.1.1
1. Download the latest Winython Zero
2. Install it somewhere (desktop’s a good place). It creates a folder called WinPython-XXbits-x.x.x.xZero (or WPy-xxxx)
3. Download the following files (adapted to your version of python, e.g. 3.7 and whether it’s a 32 or 64 bits distribution) and place them into the script subfolder:
• numpy+mkl
• scipy
• scikit-learn
• cvxopt
• kiwisolver
• cycler
• matplotlib
4. In the WinPython-XXbits-x.x.x.xZero (or WPy-xxxx) folder open WinPython Command Prompt.exe and run the following:
• Run pip install numpy --no-index --trusted-host=None --find-links=./
• Run pip install scipy --no-index --trusted-host=None --find-links=./
• Run pip install scikit-learn --no-index --trusted-host=None--find-links=./
• Run pip install cvxopt --no-index --trusted-host=None --find-links=./
• Run pip install kiwisolver --no-index --trusted-host=None--find-links=./
• Run pip install cycler --no-index --trusted-host=None --find-links=./
– Run pip install dateutils
– Run pip install pyparsing
• Run pip install matplotlib --no-index --trusted-host=None--find-links=./
• Run pip install PyQt5
• Run pip install pylint
• Run pip install spyder
• Run pip install https://github.com/neuropsychology/NeuroKit.py/zipball/master
• Run pip install https://github.com/neuropsychology/Neuropsydia.py/zipball/master
10. Launch Spyder.exe
1.1.2 Mac OS
1. Install Anaconda
4 Chapter 1. Tutorials
neurokit Documentation, Release 0.1.1
2. Open the terminal
3. Run source activate root
4. Run pip install https://github.com/neuropsychology/NeuroKit.py/zipball/master
5. Run pip install https://github.com/neuropsychology/Neuropsydia.py/zipball/master
6. Launch Spyder.exe
1.2 Biosignals Processing in Python
Welcome to the course for biosignals processing using NeuroKit and python. You’ll find the necessary files to run thisexample in the **examples** section.
1.2.1 Preprocessing
Preparation
# Import packagesimport neurokit as nkimport pandas as pdimport numpy as npimport seaborn as sns
# Download datadf = pd.read_csv("https://raw.githubusercontent.com/neuropsychology/NeuroKit.py/→˓master/examples/Bio/bio_100Hz.csv")# Plot itdf.plot()
1.2. Biosignals Processing in Python 5
neurokit Documentation, Release 0.1.1
df contains 2.5 minutes of data recorded at 100Hz (2.5 x 60 x 100 = 15000 data points). There are 4 channels, EDA,ECG, RSP and the Photosensor used to localize events. In the present case, there are four events, corresponding toemotionally negative and neutral pictures presented for 3 seconds.
Processing
Biosignals processing can be done quite easily using NeuroKit with the bio_process() function. Simply pro-vide the appropriate biosignal channels and additional channels that you want to keep (for example, the photosensor),and bio_process() will take care of the rest. It will returns a dict containing a dataframe df, including the raw aswell as processed signals, and features relevant to each provided signal.
# Process the signalsbio = nk.bio_process(ecg=df["ECG"], rsp=df["RSP"], eda=df["EDA"], add=df["Photosensor→˓"], sampling_rate=100)# Plot the processed dataframe, normalizing all variables for viewing purposenk.z_score(bio["df"]).plot()
6 Chapter 1. Tutorials
neurokit Documentation, Release 0.1.1
Woah, there’s a lot going on there! From 3 variables of interest (ECG, RSP and EDA), bio_process() produced18 signals. Moreover, the bio dict contains three other dicts, ECG, RSP and EDA containing other features that cannotbe simply added in a dataframe. Let’s see what we can do with that.
1.2.2 Bio Features Extraction
ECG Signal quality
bio["ECG"]["Average_Signal_Quality"] # Get average quality
0.9855753217220407
As you can see, the average quality of the ECG signal is 99%. See this TO BE DONE tutorial for how to record a goodsignal.
Heart Beats / Cardiac Cycles
Let’s take a look at each individual heart beat, synchronized by their R peak. You can plot all of them by doing thefollowing:
pd.DataFrame(bio["ECG"]["Cardiac_Cycles"]).plot(legend=False) # Plot all the heart→˓beats
1.2. Biosignals Processing in Python 7
neurokit Documentation, Release 0.1.1
Heart Rate Variability (HRV)
A large number of HRV indices can be found by checking out bio["ECG"]["HRV"].
Respiratory Sinus Arrythmia (RSA)
One of the most popular RSA algorithm (P2T) implementation can be found in the main data frame.
nk.z_score(bio["df"][["ECG_Filtered", "RSP_Filtered", "RSA"]])[1000:2500].plot()
8 Chapter 1. Tutorials
neurokit Documentation, Release 0.1.1
find_events returns a dict containing onsets and durations of each event. Here, it correctly detected only one event.Then, we’re gonna crop our data according to that event. The create_epochs function returns a list containingepochs of data corresponding to each event. As we have only one event, we’re gonna select the 0th element of thatlist.
1.2.3 Event-Related Analysis
This experiment consisted of 4 events (when the photosensor signal goes down), which were 2 types of images thatwere shown to the participant: “Negative” vs “Neutral”. The following list is the condition order.
condition_list = ["Negative", "Neutral", "Neutral", "Negative"]
Find Events
First, we must find events onset within our photosensor’s signal using the find_events() function. Specify a cutdirection (should it select events that are higher or lower than the treshold).
events = nk.find_events(df["Photosensor"], cut="lower")events
{'durations': array([300, 299, 300, 300]),'onsets': array([ 1024, 4958, 9224, 12984])}
1.2. Biosignals Processing in Python 9
neurokit Documentation, Release 0.1.1
As we can see, find_events() returns a dict containing onsets and durations for each event. Here, each event lastsfor approximately 300 data points (= 3 seconds sampled at 100Hz).
Create Epochs
Then, we have to split our dataframe in epochs, i.e. segments of data around the event. We set our epochs to start onesecond before the event start (onset=-100) and to last for 700 data points, in our case equal to 7 s (since the signalis sampled at 100Hz).
epochs = nk.create_epochs(bio["df"], events["onsets"], duration=700, onset=-100)
Let’s plot the first epoch.
nk.z_score(epochs[0][["ECG_Filtered", "EDA_Filtered", "Photosensor"]]).plot()
Extract Event Related Features
We can then itereate through the epochs and store the interesting results in a new dict that will be, at the end, convertedto a dataframe.
data = {} # Initialize an empty dictfor epoch_index in epochs:
data[epoch_index] = {} # Initialize an empty dict for the current epochepoch = epochs[epoch_index]
(continues on next page)
10 Chapter 1. Tutorials
neurokit Documentation, Release 0.1.1
(continued from previous page)
# ECGbaseline = epoch["ECG_RR_Interval"].ix[-100:0].mean() # Baselinerr_max = epoch["ECG_RR_Interval"].ix[0:400].max() # Maximum RR intervaldata[epoch_index]["HRV_MaxRR"] = rr_max - baseline # Corrected for baseline
# EDA - SCRscr_max = epoch["SCR_Peaks"].ix[0:600].max() # Maximum SCR peakif np.isnan(scr_max):
scr_max = 0 # If no SCR, consider the magnitude, i.e. that the value is 0data[epoch_index]["SCR_Magnitude"] = scr_max
data = pd.DataFrame.from_dict(data, orient="index") # Convert to a dataframedata["Condition"] = condition_list # Add the conditionsdata # Print
Plot Results
sns.boxplot(x="Condition", y="HRV_MaxRR", data=data)
In accord with the litterature, we observe that the RR interval is higher in the negative than in the neutral condition.
sns.boxplot(x="Condition", y="SCR_Magnitude", data=data)
1.2. Biosignals Processing in Python 11
neurokit Documentation, Release 0.1.1
In the same line, the skin conductance response (SCR) magnitude is higher in the negative condition compared tothe neutral one. Overall, these results suggest that the acquired biosignals are sensitive to the cognitive processing ofemotional stimuli.
1.3 M/EEG
Welcome to the course for EEG and MEG processing using neurokit.
Warning: the M/EEG related part is currently under developpment.
12 Chapter 1. Tutorials
CHAPTER 2
Features
Contents:
2.1 ECG Signal Quality
Warning:
This chapter must be further developped.
Using the PTB-Diagnostic dataset available from PhysioNet, we extracted all the ECG signals from the healthyparticipants, that contained 15 recording leads/subject. We extracted all cardiac cycles, for each lead, and down-sampled them from 600 to 200 datapoints. Note that we dropped the 8 first values that were NaNs. Then, wefitted a neural network model on 2/3 of the dataset (that contains 134392 cardiac cycles) to predict the lead. Modelevaluation was done on the remaining 1/3. The model show good performances in predicting the correct recordinglead (accuracy=0.91, precision=0.91). In this function, this model is fitted on each cardiac cycle of the providedECG signal. It returns the probable recording lead (the most common predicted lead), the signal quality of eachcardiac cycle (the probability of belonging to the probable recording lead) and the overall signal quality (the meanof signal quality). See the utils folder on NeuroKit’s github.
13
neurokit Documentation, Release 0.1.1
14 Chapter 2. Features
CHAPTER 3
Documentation
This part of the documentation details the complete neurokit for python API.
3.1 Biosignal Processing
3.1.1 bio_process
neurokit.bio_process(ecg=None, rsp=None, eda=None, emg=None, add=None,sampling_rate=1000, age=None, sex=None, position=None,ecg_filter_type=’FIR’, ecg_filter_band=’bandpass’, ecg_filter_frequency=[3,45], ecg_segmenter=’hamilton’, ecg_quality_model=’default’,ecg_hrv_features=[’time’, ’frequency’], eda_alpha=0.0008,eda_gamma=0.01, scr_method=’makowski’, scr_treshold=0.1,emg_names=None, emg_envelope_freqs=[10, 400], emg_envelope_lfreq=4,emg_activation_treshold=’default’, emg_activation_n_above=0.25,emg_activation_n_below=1)
Automated processing of bio signals. Wrapper for other bio processing functions.
Parameters
• ecg (list or array) – ECG signal array.
• rsp (list or array) – Respiratory signal array.
• eda (list or array) – EDA signal array.
• emg (list, array or DataFrame) – EMG signal array. Can include multiple chan-nels.
• add (pandas.DataFrame) – Dataframe or channels to add by concatenation to the pro-cessed dataframe.
• sampling_rate (int) – Sampling rate (samples/second).
• age (float) – Subject’s age.
15
neurokit Documentation, Release 0.1.1
• sex (str) – Subject’s gender (“m” or “f”).
• position (str) – Recording position. To compare with data from Voss et al. (2015), use“supine”.
• ecg_filter_type (str) – Can be Finite Impulse Response filter (“FIR”), Butterworthfilter (“butter”), Chebyshev filters (“cheby1” and “cheby2”), Elliptic filter (“ellip”) or Besselfilter (“bessel”).
• ecg_filter_band (str) – Band type, can be Low-pass filter (“lowpass”), High-passfilter (“highpass”), Band-pass filter (“bandpass”), Band-stop filter (“bandstop”).
• ecg_filter_frequency (int or list) – Cutoff frequencies, format depends ontype of band: “lowpass” or “bandpass”: single frequency (int), “bandpass” or “bandstop”:pair of frequencies (list).
• ecg_quality_model (str) – Path to model used to check signal quality. “default” usesthe builtin model. None to skip this function.
• ecg_hrv_features (list) – What HRV indices to compute. Any or all of ‘time’,‘frequency’ or ‘nonlinear’. None to skip this function.
• ecg_segmenter (str) – The cardiac phase segmenter. Can be “hamilton”, “gamboa”,“engzee”, “christov” or “ssf”. See neurokit.ecg_preprocess() for details.
• eda_alpha (float) – cvxEDA penalization for the sparse SMNA driver.
• eda_gamma (float) – cvxEDA penalization for the tonic spline coefficients.
• scr_method (str) – SCR extraction algorithm. “makowski” (default), “kim” (biosPPy’sdefault; See Kim et al., 2004) or “gamboa” (Gamboa, 2004).
• scr_treshold (float) – SCR minimum treshold (in terms of signal standart deviation).
• emg_names (list) – List of EMG channel names.
Returns
processed_bio – Dict containing processed bio features.
Contains the ECG raw signal, the filtered signal, the R peaks indexes, HRV characteristics, allthe heartbeats, the Heart Rate, and the RSP filtered signal (if respiration provided), respiratorysinus arrhythmia (RSA) features, the EDA raw signal, the filtered signal, the phasic component(if cvxEDA is True), the SCR onsets, peak indexes and amplitudes, the EMG raw signal, thefiltered signal and pulse onsets.
Return type dict
Example
>>> import neurokit as nk>>>>>> bio_features = nk.bio_process(ecg=ecg_signal, rsp=ecg_signal, eda=eda_signal)
Notes
Details
• ECG Features: See neurokit.ecg_process().
• EDA Features: See neurokit.eda_process().
16 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
• RSP Features: See neurokit.rsp_process().
• EMG Features: See neurokit.emg_process().
Authors
• Dominique Makowski
Dependencies
• pandas
See Also
• BioSPPY: https://github.com/PIA-Group/BioSPPy
• hrv: https://github.com/rhenanbartels/hrv
• cvxEDA: https://github.com/lciti/cvxEDA
References
• Heart rate variability. (1996). Standards of measurement, physiological interpretation, and clinical use.Task Force of the European Society of Cardiology and the North American Society of Pacing and Electro-physiology. Eur Heart J, 17, 354-381.
• Voss, A., Schroeder, R., Heitmann, A., Peters, A., & Perz, S. (2015). Short-term heart rate variabil-ity—influence of gender and age in healthy subjects. PloS one, 10(3), e0118308.
• Greco, A., Valenza, G., & Scilingo, E. P. (2016). Evaluation of CDA and CvxEDA Models. In Advances inElectrodermal Activity Processing with Applications for Mental Health (pp. 35-43). Springer InternationalPublishing.
• Greco, A., Valenza, G., Lanata, A., Scilingo, E. P., & Citi, L. (2016). cvxEDA: A convex optimizationapproach to electrodermal activity processing. IEEE Transactions on Biomedical Engineering, 63(4), 797-804.
• Zohar, A. H., Cloninger, C. R., & McCraty, R. (2013). Personality and heart rate variability: exploringpathways from personality to cardiac coherence and health. Open Journal of Social Sciences, 1(06), 32.
• Smith, A. L., Owen, H., & Reynolds, K. J. (2013). Heart rate variability indices for very short-term (30beat) analysis. Part 2: validation. Journal of clinical monitoring and computing, 27(5), 577-585.
• Azevedo, R. T., Garfinkel, S. N., Critchley, H. D., & Tsakiris, M. (2017). Cardiac afferent activity modu-lates the expression of racial stereotypes. Nature communications, 8.
• Edwards, L., Ring, C., McIntyre, D., & Carroll, D. (2001). Modulation of the human nociceptive flexionreflex across the cardiac cycle. Psychophysiology, 38(4), 712-718.
• Gray, M. A., Rylander, K., Harrison, N. A., Wallin, B. G., & Critchley, H. D. (2009). Following one’sheart: cardiac rhythms gate central initiation of sympathetic reflexes. Journal of Neuroscience, 29(6),1817-1825.
• Kim, K. H., Bang, S. W., & Kim, S. R. (2004). Emotion recognition system using short-term monitoringof physiological signals. Medical and biological engineering and computing, 42(3), 419-427.
• Gamboa, H. (2008). Multi-Modal Behavioral Biometrics Based on HCI and Electrophysiology (Doctoraldissertation, PhD thesis, Universidade Técnica de Lisboa, Instituto Superior Técnico).
3.1. Biosignal Processing 17
neurokit Documentation, Release 0.1.1
3.1.2 ecg_process
neurokit.ecg_process(ecg, rsp=None, sampling_rate=1000, filter_type=’FIR’, fil-ter_band=’bandpass’, filter_frequency=[3, 45], segmenter=’hamilton’,quality_model=’default’, hrv_features=[’time’, ’frequency’], age=None,sex=None, position=None)
Automated processing of ECG and RSP signals.
Parameters
• ecg (list or ndarray) – ECG signal array.
• rsp (list or ndarray) – Respiratory (RSP) signal array.
• sampling_rate (int) – Sampling rate (samples/second).
• filter_type (str) – Can be Finite Impulse Response filter (“FIR”), Butterworth filter(“butter”), Chebyshev filters (“cheby1” and “cheby2”), Elliptic filter (“ellip”) or Bessel filter(“bessel”).
• filter_band (str) – Band type, can be Low-pass filter (“lowpass”), High-pass filter(“highpass”), Band-pass filter (“bandpass”), Band-stop filter (“bandstop”).
• filter_frequency (int or list) – Cutoff frequencies, format depends on type ofband: “lowpass” or “bandpass”: single frequency (int), “bandpass” or “bandstop”: pair offrequencies (list).
• segmenter (str) – The cardiac phase segmenter. Can be “hamilton”, “gamboa”, “en-gzee”, “christov” or “ssf”. See neurokit.ecg_preprocess() for details.
• quality_model (str) – Path to model used to check signal quality. “default” uses thebuiltin model. None to skip this function.
• hrv_features (list) – What HRV indices to compute. Any or all of ‘time’, ‘fre-quency’ or ‘nonlinear’. None to skip this function.
• age (float) – Subject’s age for adjusted HRV.
• sex (str) – Subject’s gender (“m” or “f”) for adjusted HRV.
• position (str) – Recording position. To compare with data from Voss et al. (2015), use“supine”.
Returns
processed_ecg – Dict containing processed ECG features.
Contains the ECG raw signal, the filtered signal, the R peaks indexes, HRV features, all theheartbeats, the Heart Rate, the RSP filtered signal (if respiration provided) and the respiratorysinus arrhythmia (RSA).
Return type dict
Example
>>> import neurokit as nk>>> processed_ecg = nk.ecg_process(ecg_signal, resp_signal)
18 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
Notes
Details
• Cardiac Cycle: A typical ECG showing a heartbeat consists of a P wave, a QRS complex and a T wave.TheP wave represents the wave of depolarization that spreads from the SA-node throughout the atria. The QRScomplex reflects the rapid depolarization of the right and left ventricles. Since the ventricles are the largestpart of the heart, in terms of mass, the QRS complex usually has a much larger amplitude than the P-wave.The T wave represents the ventricular repolarization of the ventricles. On rare occasions, a U wave canbe seen following the T wave. The U wave is believed to be related to the last remnants of ventricularrepolarization.
• RSA: Respiratory sinus arrhythmia (RSA) is a naturally occurring variation in heart rate that occurs duringthe breathing cycle, serving as a measure of parasympathetic nervous system activity. See neurokit.ecg_rsa() for details.
• HRV: Heart-Rate Variability (HRV) is a finely tuned measure of heart-brain communication, as well asa strong predictor of morbidity and death (Zohar et al., 2013). It describes the complex variation ofbeat-to-beat intervals mainly controlled by the autonomic nervous system (ANS) through the interplay ofsympathetic and parasympathetic neural activity at the sinus node. In healthy subjects, the dynamic cardio-vascular control system is characterized by its ability to adapt to physiologic perturbations and changingconditions maintaining the cardiovascular homeostasis (Voss, 2015). In general, the HRV is influencedby many several factors like chemical, hormonal and neural modulations, circadian changes, exercise,emotions, posture and preload. There are several procedures to perform HRV analysis, usually classifiedinto three categories: time domain methods, frequency domain methods and non-linear methods. Seeneurokit.ecg_hrv() for a description of indices.
• Adjusted HRV: The raw HRV features are normalized (𝑟𝑎𝑤 − 𝑀𝑐𝑙𝑢𝑠𝑡𝑒𝑟)/𝑠𝑑 according to the partic-ipant’s age and gender. In data from Voss et al. (2015), HRV analysis was performed on 5-min ECGrecordings (lead II and lead V2 simultaneously, 500 Hz sample rate) obtained in supine position after a5–10 minutes resting phase. The cohort of healthy subjects consisted of 782 women and 1124 men betweenthe ages of 25 and 74 years, clustered into 4 groups: YF (Female, Age = [25-49], n=571), YM (Male, Age= [25-49], n=744), EF (Female, Age = [50-74], n=211) and EM (Male, Age = [50-74], n=571).
• Systole/Diastole: One prominent channel of body and brain communication is that conveyed by barore-ceptors, pressure and stretch-sensitive receptors within the heart and surrounding arteries. Within eachcardiac cycle, bursts of baroreceptor afferent activity encoding the strength and timing of each heartbeatare carried via the vagus and glossopharyngeal nerve afferents to the nucleus of the solitary tract. This is theprincipal route that communicates to the brain the dynamic state of the heart, enabling the representationof cardiovascular arousal within viscerosensory brain regions, and influence ascending neuromodulatorsystems implicated in emotional and motivational behaviour. Because arterial baroreceptors are activatedby the arterial pulse pressure wave, their phasic discharge is maximal during and immediately after thecardiac systole, that is, when the blood is ejected from the heart, and minimal during cardiac diastole, thatis, between heartbeats (Azevedo, 2017).
• ECG Signal Quality: Using the PTB-Diagnostic dataset available from PhysioNet, we extracted all theECG signals from the healthy participants, that contained 15 recording leads/subject. We extracted allcardiac cycles, for each lead, and downsampled them from 600 to 200 datapoints. Note that we droppedthe 8 first values that were NaNs. Then, we fitted a neural network model on 2/3 of the dataset (thatcontains 134392 cardiac cycles) to predict the lead. Model evaluation was done on the remaining 1/3. Themodel show good performances in predicting the correct recording lead (accuracy=0.91, precision=0.91).In this function, this model is fitted on each cardiac cycle of the provided ECG signal. It returns theprobable recording lead (the most common predicted lead), the signal quality of each cardiac cycle (theprobability of belonging to the probable recording lead) and the overall signal quality (the mean of signalquality). See creation scripts.
Authors
3.1. Biosignal Processing 19
neurokit Documentation, Release 0.1.1
• Dominique Makowski
• Rhenan Bartels (https://github.com/rhenanbartels)
Dependencies
• biosppy
• numpy
• pandas
See Also
• BioSPPY: https://github.com/PIA-Group/BioSPPy
• hrv: https://github.com/rhenanbartels/hrv
• RHRV: http://rhrv.r-forge.r-project.org/
References
• Heart rate variability. (1996). Standards of measurement, physiological interpretation, and clinical use.Task Force of the European Society of Cardiology and the North American Society of Pacing and Electro-physiology. Eur Heart J, 17, 354-381.
• Voss, A., Schroeder, R., Heitmann, A., Peters, A., & Perz, S. (2015). Short-term heart rate variabil-ity—influence of gender and age in healthy subjects. PloS one, 10(3), e0118308.
• Zohar, A. H., Cloninger, C. R., & McCraty, R. (2013). Personality and heart rate variability: exploringpathways from personality to cardiac coherence and health. Open Journal of Social Sciences, 1(06), 32.
• Smith, A. L., Owen, H., & Reynolds, K. J. (2013). Heart rate variability indices for very short-term (30beat) analysis. Part 2: validation. Journal of clinical monitoring and computing, 27(5), 577-585.
• Azevedo, R. T., Garfinkel, S. N., Critchley, H. D., & Tsakiris, M. (2017). Cardiac afferent activity modu-lates the expression of racial stereotypes. Nature communications, 8.
• Edwards, L., Ring, C., McIntyre, D., & Carroll, D. (2001). Modulation of the human nociceptive flexionreflex across the cardiac cycle. Psychophysiology, 38(4), 712-718.
• Gray, M. A., Rylander, K., Harrison, N. A., Wallin, B. G., & Critchley, H. D. (2009). Following one’sheart: cardiac rhythms gate central initiation of sympathetic reflexes. Journal of Neuroscience, 29(6),1817-1825.
3.1.3 ecg_preprocess
neurokit.ecg_preprocess(ecg, sampling_rate=1000, filter_type=’FIR’, filter_band=’bandpass’, fil-ter_frequency=[3, 45], filter_order=0.3, segmenter=’hamilton’)
ECG signal preprocessing.
Parameters
• ecg (list or ndarray) – ECG signal array.
• sampling_rate (int) – Sampling rate (samples/second).
• filter_type (str or None) – Can be Finite Impulse Response filter (“FIR”), But-terworth filter (“butter”), Chebyshev filters (“cheby1” and “cheby2”), Elliptic filter (“ellip”)or Bessel filter (“bessel”).
• filter_band (str) – Band type, can be Low-pass filter (“lowpass”), High-pass filter(“highpass”), Band-pass filter (“bandpass”), Band-stop filter (“bandstop”).
20 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
• filter_frequency (int or list) – Cutoff frequencies, format depends on type ofband: “lowpass” or “bandpass”: single frequency (int), “bandpass” or “bandstop”: pair offrequencies (list).
• filter_order (float) – Filter order.
• segmenter (str) – The cardiac phase segmenter. Can be “hamilton”, “gamboa”, “en-gzee”, “christov”, “ssf” or “pekkanen”.
Returns ecg_preprocessed – Preprocesed ECG.
Return type dict
Example
>>> import neurokit as nk>>> ecg_preprocessed = nk.ecg_preprocess(signal)
Notes
Details
• segmenter: Different methods of segmentation are implemented: hamilton (Hamilton, 2002) , gamboa(gamboa, 2008), engzee (Engelse and Zeelenberg, 1979; Lourenco et al., 2012), christov (Christov, 2004)or ssf (Slope Sum Function), pekkanen (Kathirvel, 2001).
Authors
• the bioSSPy dev team (https://github.com/PIA-Group/BioSPPy)
• Dominique Makowski
Dependencies
• biosppy
• numpy
See Also
• BioSPPY: https://github.com/PIA-Group/BioSPPy
References
• Hamilton, P. (2002, September). Open source ECG analysis. In Computers in Cardiology, 2002 (pp.101-104). IEEE.
• Kathirvel, P., Manikandan, M. S., Prasanna, S. R. M., & Soman, K. P. (2011). An efficient R-peak detectionbased on new nonlinear transformation and first-order Gaussian differentiator. Cardiovascular Engineeringand Technology, 2(4), 408-425.
• Canento, F., Lourenço, A., Silva, H., & Fred, A. (2013). Review and Comparison of Real Time Electrocar-diogram Segmentation Algorithms for Biometric Applications. In Proceedings of the 6th Int’l Conferenceon Health Informatics (HEALTHINF).
• Christov, I. I. (2004). Real time electrocardiogram QRS detection using combined adaptive threshold.Biomedical engineering online, 3(1), 28.
• Engelse, W. A. H., & Zeelenberg, C. (1979). A single scan algorithm for QRS-detection and featureextraction. Computers in cardiology, 6(1979), 37-42.
3.1. Biosignal Processing 21
neurokit Documentation, Release 0.1.1
• Lourenço, A., Silva, H., Leite, P., Lourenço, R., & Fred, A. L. (2012, February). Real Time Electrocardio-gram Segmentation for Finger based ECG Biometrics. In Biosignals (pp. 49-54).
3.1.4 ecg_hrv
neurokit.ecg_hrv(rpeaks=None, rri=None, sampling_rate=1000, hrv_features=[’time’, ’frequency’,’nonlinear’])
Computes the Heart-Rate Variability (HRV). Shamelessly stolen from the hrv package by Rhenan Bartels. Allcredits go to him.
Parameters
• rpeaks (list or ndarray) – R-peak location indices.
• rri (list or ndarray) – RR intervals in the signal. If this argument is passed, rpeaksshould not be passed.
• sampling_rate (int) – Sampling rate (samples/second).
• hrv_features (list) – What HRV indices to compute. Any or all of ‘time’, ‘fre-quency’ or ‘nonlinear’.
Returns hrv – Contains hrv features and percentage of detected artifacts.
Return type dict
Example
>>> import neurokit as nk>>> sampling_rate = 1000>>> hrv = nk.bio_ecg.ecg_hrv(rpeaks=rpeaks, sampling_rate=sampling_rate)
Notes
Details
• HRV: Heart-Rate Variability (HRV) is a finely tuned measure of heart-brain communication, as well asa strong predictor of morbidity and death (Zohar et al., 2013). It describes the complex variation ofbeat-to-beat intervals mainly controlled by the autonomic nervous system (ANS) through the interplay ofsympathetic and parasympathetic neural activity at the sinus node. In healthy subjects, the dynamic cardio-vascular control system is characterized by its ability to adapt to physiologic perturbations and changingconditions maintaining the cardiovascular homeostasis (Voss, 2015). In general, the HRV is influenced bymany several factors like chemical, hormonal and neural modulations, circadian changes, exercise, emo-tions, posture and preload. There are several procedures to perform HRV analysis, usually classified intothree categories: time domain methods, frequency domain methods and non-linear methods.
– sdNN: The standard deviation of the time interval between successive normal heart beats (i.e., theRR intervals). Reflects all influences on HRV including slow influences across the day, circadianvariations, the effect of hormonal influences such as cortisol and epinephrine. It should be noted thattotal variance of HRV increases with the length of the analyzed recording.
– meanNN: The the mean RR interval.
– CVSD: The coefficient of variation of successive differences (van Dellen et al., 1985), the RMSSDdivided by meanNN.
– cvNN: The Coefficient of Variation, i.e. the ratio of sdNN divided by meanNN.
22 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
– RMSSD is the root mean square of the RR intervals (i.e., square root of the mean of the squareddifferences in time between successive normal heart beats). Reflects high frequency (fast or parasym-pathetic) influences on HRV (i.e., those influencing larger changes from one beat to the next).
– medianNN: Median of the Absolute values of the successive Differences between the RR intervals.
– madNN: Median Absolute Deviation (MAD) of the RR intervals.
– mcvNN: Median-based Coefficient of Variation, i.e. the ratio of madNN divided by medianNN.
– pNN50: The proportion derived by dividing NN50 (The number of interval differences of successiveRR intervals greater than 50 ms) by the total number of RR intervals.
– pNN20: The proportion derived by dividing NN20 (The number of interval differences of successiveRR intervals greater than 20 ms) by the total number of RR intervals.
– Triang: The HRV triangular index measurement is the integral of the density distribution (that is, thenumber of all RR intervals) divided by the maximum of the density distribution (class width of 8ms).
– Shannon_h: Shannon Entropy calculated on the basis of the class probabilities pi (i = 1,. . . ,n withn—number of classes) of the NN interval density distribution (class width of 8 ms resulting in asmoothed histogram suitable for HRV analysis).
– VLF is the variance (i.e., power) in HRV in the Very Low Frequency (.003 to .04 Hz). Reflect anintrinsic rhythm produced by the heart which is modulated by primarily by sympathetic activity.
– LF is the variance (i.e., power) in HRV in the Low Frequency (.04 to .15 Hz). Reflects a mixtureof sympathetic and parasympathetic activity, but in long-term recordings like ours, it reflects sympa-thetic activity and can be reduced by the beta-adrenergic antagonist propanolol (McCraty & Atkinson,1996).
– HF is the variance (i.e., power) in HRV in the High Frequency (.15 to .40 Hz). Reflects fast changesin beat-to-beat variability due to parasympathetic (vagal) activity. Sometimes called the respiratoryband because it corresponds to HRV changes related to the respiratory cycle and can be increasedby slow, deep breathing (about 6 or 7 breaths per minute) (Kawachi et al., 1995) and decreased byanticholinergic drugs or vagal blockade (Hainsworth, 1995).
– Total_Power: Total power of the density spectra.
– LFHF: The LF/HF ratio is sometimes used by some investigators as a quantitative mirror of thesympatho/vagal balance.
– LFn: normalized LF power LFn = LF/(LF+HF).
– HFn: normalized HF power HFn = HF/(LF+HF).
– LFp: ratio between LF and Total_Power.
– HFp: ratio between H and Total_Power.
– DFA: Detrended fluctuation analysis (DFA) introduced by Peng et al. (1995) quantifies the fractalscaling properties of time series. DFA_1 is the short-term fractal scaling exponent calculated over n= 4–16 beats, and DFA_2 is the long-term fractal scaling exponent calculated over n = 16–64 beats.
– Shannon: Shannon Entropy over the RR intervals array.
– Sample_Entropy: Sample Entropy (SampEn) over the RR intervals array with emb_dim=2.
– Correlation_Dimension: Correlation Dimension over the RR intervals array with emb_dim=2.
– Entropy_Multiscale: Multiscale Entropy over the RR intervals array with emb_dim=2.
– Entropy_SVD: SVD Entropy over the RR intervals array with emb_dim=2.
3.1. Biosignal Processing 23
neurokit Documentation, Release 0.1.1
– Entropy_Spectral_VLF: Spectral Entropy over the RR intervals array in the very low frequency(0.003-0.04).
– Entropy_Spectral_LF: Spectral Entropy over the RR intervals array in the low frequency (0.4-0.15).
– Entropy_Spectral_HF: Spectral Entropy over the RR intervals array in the very high frequency(0.15-0.40).
– Fisher_Info: Fisher information over the RR intervals array with tau=1 and emb_dim=2.
– Lyapunov: Lyapunov Exponent over the RR intervals array with emb_dim=58 and matrix_dim=4.
– FD_Petrosian: Petrosian’s Fractal Dimension over the RR intervals.
– FD_Higushi: Higushi’s Fractal Dimension over the RR intervals array with k_max=16.
Authors
• Dominique Makowski
• Rhenan Bartels (https://github.com/rhenanbartels)
Dependencies
• scipy
• numpy
See Also
• RHRV: http://rhrv.r-forge.r-project.org/
References
• Heart rate variability. (1996). Standards of measurement, physiological interpretation, and clinical use.Task Force of the European Society of Cardiology and the North American Society of Pacing and Electro-physiology. Eur Heart J, 17, 354-381.
• Voss, A., Schroeder, R., Heitmann, A., Peters, A., & Perz, S. (2015). Short-term heart rate variabil-ity—influence of gender and age in healthy subjects. PloS one, 10(3), e0118308.
• Zohar, A. H., Cloninger, C. R., & McCraty, R. (2013). Personality and heart rate variability: exploringpathways from personality to cardiac coherence and health. Open Journal of Social Sciences, 1(06), 32.
• Smith, A. L., Owen, H., & Reynolds, K. J. (2013). Heart rate variability indices for very short-term (30beat) analysis. Part 2: validation. Journal of clinical monitoring and computing, 27(5), 577-585.
• Lippman, N. E. A. L., Stein, K. M., & Lerman, B. B. (1994). Comparison of methods for removal ofectopy in measurement of heart rate variability. American Journal of Physiology-Heart and CirculatoryPhysiology, 267(1), H411-H418.
• Peltola, M. A. (2012). Role of editing of R–R intervals in the analysis of heart rate variability. Frontiers inphysiology, 3.
3.1.5 ecg_rsa
neurokit.ecg_rsa(rpeaks, rsp, sampling_rate=1000)Returns Respiratory Sinus Arrhythmia (RSA) features. Only the Peak-to-trough (P2T) algorithm is currentlyimplemented (see details).
Parameters
• rpeaks (list or ndarray) – List of R peaks indices.
24 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
• rsp (list or ndarray) – Filtered RSP signal.
• sampling_rate (int) – Sampling rate (samples/second).
Returns rsa – Contains RSA features.
Return type dict
Example
>>> import neurokit as nk>>> rsa = nk.ecg_rsa(rpeaks, rsp)
Notes
Details
• RSA: Respiratory sinus arrhythmia (RSA) is a naturally occurring variation in heart rate that occurs duringthe breathing cycle, serving as a measure of parasympathetic nervous system activity. Neurophysiologyinforms us that the functional output of the myelinated vagus originating from the nucleus ambiguus has arespiratory rhythm. Thus, there would a temporal relation between the respiratory rhythm being expressedin the firing of these efferent pathways and the functional effect on the heart rate rhythm manifested asRSA. Several methods exist to quantify RSA:
– P2T: The peak to trough (P2T) method measures the statistical range in ms of the heart period os-cillation associated with synchronous respiration. Operationally, subtracting the shortest heart periodduring inspiration from the longest heart period during a breath cycle produces an estimate of RSAduring each breath. The peak-to-trough method makes no statistical assumption or correction (e.g.,adaptive filtering) regarding other sources of variance in the heart period time series that may con-found, distort, or interact with the metric such as slower periodicities and baseline trend. Although ithas been proposed that the P2T method “acts as a time-domain filter dynamically centered at the exactongoing respiratory frequency” (Grossman, 1992), the method does not transform the time series inany way, as a filtering process would. Instead the method uses knowledge of the ongoing respiratorycycle to associate segments of the heart period time series with either inhalation or exhalation (Lewis,2012).
Authors
• Dominique Makowski
• Rhenan Bartels (https://github.com/rhenanbartels)
Dependencies
• numpy
• pandas
References
• Lewis, G. F., Furman, S. A., McCool, M. F., & Porges, S. W. (2012). Statistical strategies to quantifyrespiratory sinus arrhythmia: Are commonly used metrics equivalent?. Biological psychology, 89(2), 349-364.
3.1. Biosignal Processing 25
neurokit Documentation, Release 0.1.1
3.1.6 ecg_simulate
neurokit.ecg_simulate(duration=10, sampling_rate=1000, bpm=60, noise=0.01)Simulates an ECG signal.
Parameters
• duration (int) – Desired recording length.
• sampling_rate (int) – Desired sampling rate.
• bpm (int) – Desired simulated heart rate.
• noise (float) – Desired noise level.
Returns ECG_Response – Event-related ECG response features.
Return type dict
Example
>>> import neurokit as nk>>> import pandas as pd>>>>>> ecg = nk.ecg_simulate(duration=10, bpm=60, sampling_rate=1000, noise=0.01)>>> pd.Series(ecg).plot()
Notes
Authors
• Diarmaid O Cualain
• Dominique Makowski
Dependencies
• numpy
• scipy.signal
References
3.1.7 rsp_process
neurokit.rsp_process(rsp, sampling_rate=1000)Automated processing of RSP signals.
Parameters
• rsp (list or array) – Respiratory (RSP) signal array.
• sampling_rate (int) – Sampling rate (samples/second).
Returns
processed_rsp – Dict containing processed RSP features.
Contains the RSP raw signal, the filtered signal, the respiratory cycles onsets, and respiratoryphases (inspirations and expirations).
26 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
Return type dict
Example
>>> import neurokit as nk>>>>>> processed_rsp = nk.rsp_process(rsp_signal)
Notes
Authors
• Dominique Makowski (https://github.com/DominiqueMakowski)
Dependencies
• biosppy
• numpy
• pandas
See Also
• BioSPPY: https://github.com/PIA-Group/BioSPPy
3.1.8 eda_process
neurokit.eda_process(eda, sampling_rate=1000, alpha=0.0008, gamma=0.01, filter_type=’butter’,scr_method=’makowski’, scr_treshold=0.1)
Automated processing of EDA signal using convex optimization (CVXEDA; Greco et al., 2015).
Parameters
• eda (list or array) – EDA signal array.
• sampling_rate (int) – Sampling rate (samples/second).
• alpha (float) – cvxEDA penalization for the sparse SMNA driver.
• gamma (float) – cvxEDA penalization for the tonic spline coefficients.
• filter_type (str or None) – Can be Butterworth filter (“butter”), Finite ImpulseResponse filter (“FIR”), Chebyshev filters (“cheby1” and “cheby2”), Elliptic filter (“ellip”)or Bessel filter (“bessel”). Set to None to skip filtering.
• scr_method (str) – SCR extraction algorithm. “makowski” (default), “kim” (biosPPy’sdefault; See Kim et al., 2004) or “gamboa” (Gamboa, 2004).
• scr_treshold (float) – SCR minimum treshold (in terms of signal standart deviation).
Returns
processed_eda – Dict containing processed EDA features.
Contains the EDA raw signal, the filtered signal, the phasic compnent (if cvxEDA is True), theSCR onsets, peak indexes and amplitudes.
This function is mainly a wrapper for the biosppy.eda.eda() and cvxEDA() functions. Credits goto their authors.
3.1. Biosignal Processing 27
neurokit Documentation, Release 0.1.1
Return type dict
Example
>>> import neurokit as nk>>>>>> processed_eda = nk.eda_process(eda_signal)
Notes
Details
• cvxEDA: Based on a model which describes EDA as the sum of three terms: the phasic component, thetonic component, and an additive white Gaussian noise term incorporating model prediction errors as wellas measurement errors and artifacts. This model is physiologically inspired and fully explains EDA througha rigorous methodology based on Bayesian statistics, mathematical convex optimization and sparsity.
Authors
• Dominique Makowski
Dependencies
• biosppy
• numpy
• pandas
• cvxopt
See Also
• BioSPPy: https://github.com/PIA-Group/BioSPPy
• cvxEDA: https://github.com/lciti/cvxEDA
References
• Greco, A., Valenza, G., & Scilingo, E. P. (2016). Evaluation of CDA and CvxEDA Models. In Advances inElectrodermal Activity Processing with Applications for Mental Health (pp. 35-43). Springer InternationalPublishing.
• Greco, A., Valenza, G., Lanata, A., Scilingo, E. P., & Citi, L. (2016). cvxEDA: A convex optimizationapproach to electrodermal activity processing. IEEE Transactions on Biomedical Engineering, 63(4), 797-804.
• Kim, K. H., Bang, S. W., & Kim, S. R. (2004). Emotion recognition system using short-term monitoringof physiological signals. Medical and biological engineering and computing, 42(3), 419-427.
• Gamboa, H. (2008). Multi-Modal Behavioral Biometrics Based on HCI and Electrophysiology (Doctoraldissertation, PhD thesis, Universidade Técnica de Lisboa, Instituto Superior Técnico).
3.1.9 eda_scr
neurokit.eda_scr(signal, sampling_rate=1000, treshold=0.1, method=’fast’)Skin-Conductance Responses extraction algorithm.
28 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
Parameters
• signal (list or array) – EDA signal array.
• sampling_rate (int) – Sampling rate (samples/second).
• treshold (float) – SCR minimum treshold (in terms of signal standart deviation).
• method (str) – “fast” or “slow”. Either use a gradient-based approach or a local extremaone.
Returns onsets, peaks, amplitudes, recoveries – SCRs features.
Return type lists
Example
>>> import neurokit as nk>>>>>> onsets, peaks, amplitudes, recoveries = nk.eda_scr(eda_signal)
Notes
Authors
• Dominique Makowski
Dependencies
• biosppy
• numpy
• pandas
See Also
• BioSPPy: https://github.com/PIA-Group/BioSPPy
References
• Kim, K. H., Bang, S. W., & Kim, S. R. (2004). Emotion recognition system using short-term monitoringof physiological signals. Medical and biological engineering and computing, 42(3), 419-427.
• Gamboa, H. (2008). Multi-Modal Behavioral Biometrics Based on HCI and Electrophysiology (Doctoraldissertation, PhD thesis, Universidade Técnica de Lisboa, Instituto Superior Técnico).
3.1.10 emg_process
neurokit.emg_process(emg, sampling_rate=1000, emg_names=None, envelope_freqs=[10, 400], en-velope_lfreq=4, activation_treshold=’default’, activation_n_above=0.25, acti-vation_n_below=1)
Automated processing of EMG signal.
Parameters
• emg (list, array or DataFrame) – EMG signal array. Can include multiple chan-nels.
3.1. Biosignal Processing 29
neurokit Documentation, Release 0.1.1
• sampling_rate (int) – Sampling rate (samples/second).
• emg_names (list) – List of EMG channel names.
• envelope_freqs (list [fc_h, fc_l], optional) – cutoff frequencies for theband-pass filter (in Hz).
• envelope_lfreq (number, optional) – cutoff frequency for the low-pass filter (inHz).
• activation_treshold (float) – minimum amplitude of x to detect.
• activation_n_above (float) – minimum continuous time (in s) greater than or equalto threshold to detect (but see the parameter n_below).
• activation_n_below (float) – minimum time (in s) below threshold that will beignored in the detection of x >= threshold.
Returns
processed_emg – Dict containing processed EMG features.
Contains the EMG raw signal, the filtered signal and pulse onsets.
This function is mainly a wrapper for the biosppy.emg.emg() function. Credits go to its authors.
Return type dict
Example
>>> import neurokit as nk>>>>>> processed_emg = nk.emg_process(emg_signal)
Notes
Authors
• Dominique Makowski (https://github.com/DominiqueMakowski)
Dependencies
• biosppy
• numpy
• pandas
See Also
• BioSPPy: https://github.com/PIA-Group/BioSPPy
References
• None
30 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
3.1.11 bio_EventRelated
neurokit.bio_EventRelated(epoch, event_length, window_post_ecg=0, window_post_rsp=4, win-dow_post_eda=4, ecg_features=[’Heart_Rate’, ’Cardiac_Phase’,’RR_Interval’, ’RSA’, ’HRV’])
Extract event-related bio (EDA, ECG and RSP) changes.
Parameters
• epoch (pandas.DataFrame) – An epoch contains in the epochs dict re-turned by :function:‘neurokit.create_epochs()‘ on dataframe returned by :func-tion:‘neurokit.bio_process()‘.
• event_length (int) – In seconds.
• sampling_rate (int) – Sampling rate (samples/second).
• window_post_ecg (float) – Post-stimulus window size (in seconds) for ECG.
• window_post_rsp (float) – Post-stimulus window size (in seconds) for RSP.
• window_post_eda (float) – Post-stimulus window size (in seconds) for EDA.
• ecg_features (list) – List of ECG features to compute, can contain “Heart_Rate”,“Cardiac_Phase”, “RR_Interval”, “RSA”, “HRV”.
Returns RSP_Response – Event-locked bio response features.
Return type dict
Example
>>> import neurokit as nk>>> bio = nk.bio_process(ecg=data["ECG"], rsp=data["RSP"], eda=data["EDA"],→˓sampling_rate=1000, add=data["Photosensor"])>>> df = bio["df"]>>> events = nk.find_events(df["Photosensor"], cut="lower")>>> epochs = nk.create_epochs(df, events["onsets"], duration=7, onset=-0.5)>>> for epoch in epochs:>>> bio_response = nk.bio_EventRelated(epoch, event_length=4, window_post=3)
Notes
Details
• ECG Features
– *_Baseline: Signal at onset.
– *_Min: Mininmum of signal after stimulus onset.
– *_MinDiff: Signal mininum - baseline.
– *_MinTime: Time of signal minimum.
– *_Max: Maximum of signal after stimulus onset.
– *_MaxDiff: Signal maximum - baseline.
– *_MaxTime: Time of signal maximum.
– *_Mean: Mean signal after stimulus onset.
3.1. Biosignal Processing 31
neurokit Documentation, Release 0.1.1
– *_MeanDiff: Mean signal - baseline.
– ECG_Phase_Systole: Cardiac phase on stimulus onset (1 = systole, 0 = diastole).
– ECG_Phase_Systole_Completion: Percentage of cardiac phase completion on simulus onset.
– ECG_HRV_*: Time-domain HRV features. See neurokit.ecg_hrv().
• Respiration Features
– RSP_Rate_Baseline: mean RSP Rate before stimulus onset.
– RSP_Rate_Min: Min RSP Rate after stimulus onset.
– RSP_Rate_MinDiff: RSP Rate mininum - baseline.
– RSP_Rate_MinTime: Time of minimum.
– RSP_Rate_Max: Max RSP Rate after stimulus onset.
– RSP_Rate_MaxDiff: Max RSP Rate - baseline.
– RSP_Rate_MaxTime: Time of maximum.
– RSP_Rate_Mean: Mean RSP Rate after stimulus onset.
– RSP_Rate_MeanDiff: Mean RSP Rate - baseline.
– RSP_Min: Value in standart deviation (normalized by baseline) of the lowest point.
– RSP_MinTime: Time of RSP Min.
– RSP_Max: Value in standart deviation (normalized by baseline) of the highest point.
– RSP_MaxTime: Time of RSP Max.
– RSP_Inspiration: Respiration phase on stimulus onset (1 = inspiration, 0 = expiration).
– RSP_Inspiration_Completion: Percentage of respiration phase on stimulus onset.
• EDA Features
– EDA_Peak: Max of EDA (in a window starting 1s after the stim onset) minus baseline.
– SCR_Amplitude: Peak of SCR. If no SCR, returns NA.
– SCR_Magnitude: Peak of SCR. If no SCR, returns 0.
– SCR_Amplitude_Log: log of 1+amplitude.
– SCR_Magnitude_Log: log of 1+magnitude.
– SCR_PeakTime: Time of peak.
– SCR_Latency: Time between stim onset and SCR onset.
– SCR_RiseTime: Time between SCR onset and peak.
– SCR_Strength: Experimental: peak divided by latency. Angle of the line between peak and onset.
– SCR_RecoveryTime: Time between peak and recovery point (half of the amplitude).
Authors
• Dominique Makowski
Dependencies
• numpy
• pandas
32 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
See Also
References
• Gomez, P., Stahel, W. A., & Danuser, B. (2004). Respiratory responses during affective picture viewing.Biological Psychology, 67(3), 359-373.
• Schneider, R., Schmidt, S., Binder, M., Schäfer, F., & Walach, H. (2003). Respiration-related artifacts inEDA recordings: introducing a standardized method to overcome multiple interpretations. Psychologicalreports, 93(3), 907-920.
3.1.12 read_acqknowledge
neurokit.read_acqknowledge(filename, path=”, index=’datetime’, sampling_rate=’max’,resampling_method=’pad’, fill_interruptions=True, re-turn_sampling_rate=True)
Read and Format a BIOPAC’s AcqKnowledge file into a pandas’ dataframe.
Parameters
• filename (str) – Filename (with or without the extension) of a BIOPAC’s AcqKnowl-edge file.
• path (str) – Data directory.
• index (str) – How to index the dataframe. “datetime” for aproximate datetime (based onthe file creation/change) and “range” for a simple range index.
• sampling_rate (int) – Final sampling rate (samples/second).
• resampling_method (str) – The resampling method: “mean”, “pad” or “bfill”,
• fill_interruptions (bool) – Automatically fill the eventual signal interruptions us-ing a backfill method.
• return_sampling_rate (bool) – Should it return the sampling rate in a tuple withthe dataframe? Default will be changed to True in the future.
Returns df, sampling_rate – The AcqKnowledge file converted to a dataframe and its sam-pling_rate.
Return type pandas.DataFrame(), int
Example
>>> import neurokit as nk>>>>>> df, sampling_rate = nk.read_acqknowledge('file.acq', return_sampling_→˓rate=True)
Notes
Authors
• Dominique Makowski
Dependencies
3.1. Biosignal Processing 33
neurokit Documentation, Release 0.1.1
• pandas
• bioread
• datetime
See Also
• bioread package: https://github.com/njvack/bioread
3.2 EEG
3.2.1 eeg_add_channel
neurokit.eeg_add_channel(raw, channel, sync_index_eeg=0, sync_index_channel=0, chan-nel_type=None, channel_name=None)
Add a channel to a mne’s Raw m/eeg file. It will basically synchronize the channel to the eeg data following aparticular index and add it.
Parameters
• raw (mne.io.Raw) – Raw EEG data.
• channel (list or numpy.array) – The channel to be added.
• sync_index_eeg (int or list) – An index, in the raw data, by which to align thetwo inputs.
• sync_index_channel (int or list) – An index, in the channel to add, by whichto align the two inputs.
• channel_type (str) – Channel type. Currently supported fields are ‘ecg’, ‘bio’, ‘stim’,‘eog’, ‘misc’, ‘seeg’, ‘ecog’, ‘mag’, ‘eeg’, ‘ref_meg’, ‘grad’, ‘emg’, ‘hbr’ or ‘hbo’.
Returns raw – Raw data in FIF format.
Return type mne.io.Raw
Example
>>> import neurokit as nk>>> event_index_in_eeg = 42>>> event_index_in_ecg = 666>>> raw = nk.eeg_add_channel(raw, ecg, sync_index_raw=event_index_in_eeg, sync_→˓index_channel=event_index_in_ecg, channel_type="ecg")
Notes
Authors
• Dominique Makowski
Dependencies
• mne
See Also
• mne: http://martinos.org/mne/dev/index.html
34 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
3.2.2 eeg_select_channels
neurokit.eeg_select_channels(raw, channel_names)Select one or several channels by name and returns them in a dataframe.
Parameters
• raw (mne.io.Raw) – Raw EEG data.
• channel_names (str or list) – Channel’s name(s).
Returns channels – Channel.
Return type pd.DataFrame
Example
>>> import neurokit as nk>>> raw = nk.eeg_select_channel(raw, "TP7")
Notes
Authors
• Dominique Makowski
Dependencies
• mne
See Also
• mne package: http://martinos.org/mne/dev/index.html
3.2.3 eeg_select_electrodes
neurokit.eeg_select_electrodes(eeg, include=’all’, exclude=None, hemisphere=’both’, cen-tral=True)
Returns electrodes/sensors names of selected region (according to a 10-20 EEG montage).
Parameters
• eeg (mne.Raw or mne.Epochs) – EEG data.
• include (str ot list) – Sensor area to include.
• exclude (str or list or None) – Sensor area to exclude.
• hemisphere (str) – Select both hemispheres? “both”, “left” or “right”.
• central (bool) – Select the central line.
Returns electrodes – List of electrodes/sensors corresponding to the selected area.
Return type list
3.2. EEG 35
neurokit Documentation, Release 0.1.1
Example
>>> import neurokit as nk>>> nk.eeg_select_electrodes(include="F", exclude="C")
Notes
Authors
• Dominique Makowski
3.2.4 eeg_create_mne_events
neurokit.eeg_create_mne_events(onsets, conditions=None)Create MNE compatible events.
Parameters
• onsets (list or array) – Events onsets.
• conditions (list) – A list of equal length containing the stimuli types/conditions.
Returns (events, event_id) – MNE-formated events and a dictionary with event’s names.
Return type tuple
Example
>>> import neurokit as nk>>> events, event_id = nk.eeg_create_mne_events(events_onset, conditions)
• Dominique Makowski
3.2.5 eeg_add_events
neurokit.eeg_add_events(raw, events_channel, conditions=None, treshold=’auto’, cut=’higher’,time_index=None, number=’all’, after=0, before=None, min_duration=1)
Find events on a channel, convert them into an MNE compatible format, and add them to the raw data.
Parameters
• raw (mne.io.Raw) – Raw EEG data.
• events_channel (str or array) – Name of the trigger channel if in the raw, orarray of equal length if externally supplied.
• conditions (list) – List containing the stimuli types/conditions.
• treshold (float) – The treshold value by which to select the events. If “auto”, takesthe value between the max and the min.
• cut (str) – “higher” or “lower”, define the events as above or under the treshold. Forphotosensors, a white screen corresponds usually to higher values. Therefore, if your eventswere signalled by a black colour, events values would be the lower ones, and you should setthe cut to “lower”. Add a corresponding datetime index, will return an addional array withthe onsets as datetimes.
36 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
• number (str or int) – How many events should it select.
• after (int) – If number different than “all”, then at what time should it start selecting theevents.
• before (int) – If number different than “all”, before what time should it select the events.
• min_duration (int) – The minimum duration of an event (in timepoints).
Returns (raw, events, event_id) – The raw file with events, the mne-formatted events and event_id.
Return type tuple
Example
>>> import neurokit as nk>>>>>> raw, events, event_id = nk.eeg_add_events(raw, events_channel, conditions)
Notes
Authors
• Dominique Makowski
Dependencies
• pandas
See Also
• mne: http://martinos.org/mne/dev/index.html
References
• None
3.2.6 eeg_complexity
neurokit.eeg_complexity(eeg, sampling_rate, times=None, index=None, include=’all’, ex-clude=None, hemisphere=’both’, central=True, verbose=True, shan-non=True, sampen=True, multiscale=True, spectral=True, svd=True,correlation=True, higushi=True, petrosian=True, fisher=True, hurst=True,dfa=True, lyap_r=False, lyap_e=False, names=’Complexity’)
Compute complexity indices of epochs or raw object.
DOCS INCOMPLETE :(
3.2.7 eeg_erp
neurokit.eeg_erp(eeg, times=None, index=None, include=’all’, exclude=None, hemisphere=’both’,central=True, verbose=True, names=’ERP’, method=’mean’)
DOCS INCOMPLETE :(
3.2. EEG 37
neurokit Documentation, Release 0.1.1
3.2.8 plot_eeg_erp
neurokit.plot_eeg_erp(all_epochs, conditions=None, times=None, include=’all’, exclude=None,hemisphere=’both’, central=True, name=None, colors=None, gfp=False,ci=0.95, ci_alpha=0.333, invert_y=False, linewidth=1, linestyle=’-’, fil-ter_hfreq=None)
DOCS INCOMPLETE :(
3.2.9 plot_eeg_erp_topo
neurokit.plot_eeg_erp_topo(all_epochs, colors=None)Plot butterfly plot.
DOCS INCOMPLETE :(
3.3 Signal
3.3.1 find_events
neurokit.find_events(events_channel, treshold=’auto’, cut=’higher’, time_index=None, num-ber=’all’, after=0, before=None, min_duration=1)
Find and select events based on a continuous signal.
Parameters
• events_channel (array or list) – The trigger channel.
• treshold (float) – The treshold value by which to select the events. If “auto”, takesthe value between the max and the min.
• cut (str) – “higher” or “lower”, define the events as above or under the treshold. Forphotosensors, a white screen corresponds usually to higher values. Therefore, if your eventswere signalled by a black colour, events values would be the lower ones, and you should setthe cut to “lower”. Add a corresponding datetime index, will return an addional array withthe onsets as datetimes.
• number (str or int) – How many events should it select.
• after (int) – If number different than “all”, then at what time should it start selecting theevents.
• before (int) – If number different than “all”, before what time should it select the events.
• min_duration (int) – The minimum duration of an event (in timepoints).
Returns events – Dict containing events onsets and durations.
Return type dict
Example
>>> import neurokit as nk>>> events = nk.select_events(events_channel)
38 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
Notes
Authors
• Dominique Makowski
Dependencies
• numpy
3.3.2 plot_events_in_signal
neurokit.plot_events_in_signal(signal, events_onsets, color=’red’, marker=None)Plot events in signal.
Parameters
• signal (array or DataFrame) – Signal array (can be a dataframe with many sig-nals).
• events_onsets (list or ndarray) – Events location.
• color (int or list) – Marker color.
• marker (marker or list of markers (for possible marker values, see: https://matplotlib.org/api/markers_api.html)) – Marker type.
Example
>>> import neurokit as nk>>> bio = nk.bio_process(ecg=signal, sampling_rate=1000)>>> events_onsets = bio["ECG"]["R_Peaks"]>>> plot_events_in_signal(bio["df"]["ECG_Filtered"], events_onsets)>>> plot_events_in_signal(bio["df"]["ECG_Filtered"], events_onsets, color="red",→˓marker="o")>>> plot_events_in_signal(bio["df"]["ECG_Filtered"], [bio["ECG"]["P_Waves"], bio[→˓"ECG"]["R_Peaks"]], color=["blue", "red"], marker=["d","o"])
Notes
Authors
• Dominique Makowski
• Renatosc
Dependencies
• matplotlib
• pandas
3.3.3 create_epochs
neurokit.create_epochs(data, events_onsets, sampling_rate=1000, duration=1, onset=0, in-dex=None)
Epoching a dataframe.
3.3. Signal 39
neurokit Documentation, Release 0.1.1
Parameters
• data (pandas.DataFrame) – Data*time.
• events_onsets (list) – A list of event onsets indices.
• sampling_rate (int) – Sampling rate (samples/second).
• duration (int or list) – Duration(s) of each epoch(s) (in seconds).
• onset (int) – Epoch onset(s) relative to events_onsets (in seconds).
• index (list) – Events names in order that will be used as index. Must contains uniquesnames. If not provided, will be replaced by event number.
Returns epochs – dict containing all epochs.
Return type dict
Example
>>> import neurokit as nk>>> epochs = nk.create_epochs(data, events_onsets)
Notes
Authors
• Dominique Makowski (https://github.com/DominiqueMakowski)
Dependencies
• numpy
3.3.4 complexity
neurokit.complexity(signal, sampling_rate=1000, shannon=True, sampen=True, multiscale=True,spectral=True, svd=True, correlation=True, higushi=True, petrosian=True,fisher=True, hurst=True, dfa=True, lyap_r=False, lyap_e=False, emb_dim=2,tolerance=’default’, k_max=8, bands=None, tau=1)
Computes several chaos/complexity indices of a signal (including entropy, fractal dimensions, Hurst and Lya-punov exponent etc.).
Parameters
• signal (list or array) – List or array of values.
• sampling_rate (int) – Sampling rate (samples/second).
• shannon (bool) – Computes Shannon entropy.
• sampen (bool) – Computes approximate sample entropy (sampen) using Chebychev andEuclidean distances.
• multiscale (bool) – Computes multiscale entropy (MSE). Note that it uses the ‘eu-clidean’ distance.
• spectral (bool) – Computes Spectral Entropy.
• svd (bool) – Computes the Singular Value Decomposition (SVD) entropy.
40 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
• correlation (bool) – Computes the fractal (correlation) dimension.
• higushi (bool) – Computes the Higushi fractal dimension.
• petrosian (bool) – Computes the Petrosian fractal dimension.
• fisher (bool) – Computes the Fisher Information.
• hurst (bool) – Computes the Hurst exponent.
• dfa (bool) – Computes DFA.
• lyap_r (bool) – Computes Positive Lyapunov exponents (Rosenstein et al. (1993)method).
• lyap_e (bool) – Computes Positive Lyapunov exponents (Eckmann et al. (1986)method).
• emb_dim (int) – The embedding dimension (m, the length of vectors to compare). Usedin sampen, fisher, svd and fractal_dim.
• tolerance (float) – Distance r threshold for two template vectors to be consideredequal. Default is 0.2*std(signal). Used in sampen and fractal_dim.
• k_max (int) – The maximal value of k used for Higushi fractal dimension. The pointat which the FD plateaus is considered a saturation point and that kmax value should beselected (Gómez, 2009). Some studies use a value of 8 or 16 for ECG signal and other 48for MEG.
• bands (int) – Used for spectral density. A list of numbers delimiting the bins of thefrequency bands. If None the entropy is computed over the whole range of the DFT (from 0to f_s/2).
• tau (int) – The delay. Used for fisher, svd, lyap_e and lyap_r.
Returns complexity – Dict containing values for each indices.
Return type dict
Example
>>> import neurokit as nk>>> import numpy as np>>>>>> signal = np.sin(np.log(np.random.sample(666)))>>> complexity = nk.complexity(signal)
Notes
Details
• Entropy: Entropy is a measure of unpredictability of the state, or equivalently, of its average informationcontent.
– Shannon entropy: Shannon entropy was introduced by Claude E. Shannon in his 1948 paper “AMathematical Theory of Communication”. Shannon entropy provides an absolute limit on the bestpossible average length of lossless encoding or compression of an information source.
– Sample entropy (sampen): Measures the complexity of a time-series, based on approximate entropy.The sample entropy of a time series is defined as the negative natural logarithm of the conditionalprobability that two sequences similar for emb_dim points remain similar at the next point, excluding
3.3. Signal 41
neurokit Documentation, Release 0.1.1
self-matches. A lower value for the sample entropy therefore corresponds to a higher probabilityindicating more self-similarity.
– Multiscale entropy: Multiscale entropy (MSE) analysis is a new method of measuring the complexityof finite length time series.
– SVD Entropy: Indicator of how many vectors are needed for an adequate explanation of the data set.Measures feature-richness in the sense that the higher the entropy of the set of SVD weights, the moreorthogonal vectors are required to adequately explain it.
• fractal dimension: The term fractal was first introduced by Mandelbrot in 1983. A fractal is a set ofpoints that when looked at smaller scales, resembles the whole set. The concept of fractak dimension(FD) originates from fractal geometry. In traditional geometry, the topological or Euclidean dimensionof an object is known as the number of directions each differential of the object occupies in space. Thisdefinition of dimension works well for geometrical objects whose level of detail, complexity or space-filling is the same. However, when considering two fractals of the same topological dimension, theirlevel of space-filling is different, and that information is not given by the topological dimension. TheFD emerges to provide a measure of how much space an object occupies between Euclidean dimensions.The FD of a waveform represents a powerful tool for transient detection. This feature has been used inthe analysis of ECG and EEG to identify and distinguish specific states of physiologic function. Manyalgorithms are available to determine the FD of the waveform (Acharya, 2005).
– Correlation: A measure of the fractal (or correlation) dimension of a time series which is also relatedto complexity. The correlation dimension is a characteristic measure that can be used to describe thegeometry of chaotic attractors. It is defined using the correlation sum C(r) which is the fraction ofpairs of points X_i in the phase space whose distance is smaller than r.
– Higushi: Higuchi proposed in 1988 an efficient algorithm for measuring the FD of discrete timesequences. As the reconstruction of the attractor phase space is not necessary, this algorithm is simplerand faster than D2 and other classical measures derived from chaos theory. FD can be used to quantifythe complexity and self-similarity of a signal. HFD has already been used to analyse the complexityof brain recordings and other biological signals.
– Petrosian Fractal Dimension: Provide a fast computation of the FD of a signal by translating the seriesinto a binary sequence.
• Other:
– Fisher Information: A way of measuring the amount of information that an observable random vari-able X carries about an unknown parameter 𝜃 of a distribution that models X. Formally, it is thevariance of the score, or the expected value of the observed information.
– Hurst: The Hurst exponent is a measure of the “long-term memory” of a time series. It can be usedto determine whether the time series is more, less, or equally likely to increase if it has increased inprevious steps. This property makes the Hurst exponent especially interesting for the analysis of stockdata.
– DFA: DFA measures the Hurst parameter H, which is very similar to the Hurst exponent. The maindifference is that DFA can be used for non-stationary processes (whose mean and/or variance changeover time).
– Lyap: Positive Lyapunov exponents indicate chaos and unpredictability. Provides the algorithm ofRosenstein et al. (1993) to estimate the largest Lyapunov exponent and the algorithm of Eckmann etal. (1986) to estimate the whole spectrum of Lyapunov exponents.
Authors
• Dominique Makowski (https://github.com/DominiqueMakowski)
• Christopher Schölzel (https://github.com/CSchoel)
42 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
• tjugo (https://github.com/nikdon)
• Quentin Geissmann (https://github.com/qgeissmann)
Dependencies
• nolds
• numpy
See Also
• nolds package: https://github.com/CSchoel/nolds
• pyEntropy package: https://github.com/nikdon/pyEntropy
• pyrem package: https://github.com/gilestrolab/pyrem
References
• Accardo, A., Affinito, M., Carrozzi, M., & Bouquet, F. (1997). Use of the fractal dimension for the analysisof electroencephalographic time series. Biological cybernetics, 77(5), 339-350.
• Pierzchalski, M. Application of Higuchi Fractal Dimension in Analysis of Heart Rate Variability withArtificial and Natural Noise. Recent Advances in Systems Science.
• Acharya, R., Bhat, P. S., Kannathal, N., Rao, A., & Lim, C. M. (2005). Analysis of cardiac health usingfractal dimension and wavelet transformation. ITBM-RBM, 26(2), 133-139.
• Richman, J. S., & Moorman, J. R. (2000). Physiological time-series analysis using approximate entropyand sample entropy. American Journal of Physiology-Heart and Circulatory Physiology, 278(6), H2039-H2049.
• Costa, M., Goldberger, A. L., & Peng, C. K. (2005). Multiscale entropy analysis of biological signals.Physical review E, 71(2), 021906.
3.4 Statistics
3.4.1 mad
neurokit.mad(var, constant=1)Median Absolute Deviation: a “robust” version of standard deviation.
Parameters
• var (list or ndarray) – Value array.
• constant (float) – Scale factor. Use 1.4826 for results similar to default R.
Returns mad – The MAD.
Return type float
Example
>>> import neurokit as nk>>> hrv = nk.mad([2, 8, 7, 5, 4, 12, 5, 1])
3.4. Statistics 43
neurokit Documentation, Release 0.1.1
Notes
Authors
• Dominique Makowski
Dependencies
• numpy
References
• https://en.wikipedia.org/wiki/Median_absolute_deviation
3.4.2 z_score
neurokit.z_score(raw_scores, center=True, scale=True)Transform an array, serie or list into Z scores (scaled and centered scores).
Parameters
• raw_scores (list, ndarray or pandas.Series) – ECG signal array.
• centered (bool) – Center the array (mean = 0).
• scale (bool) – scale the array (sd = 1).
Returns z_scores – The normalized scores.
Return type pandas.DataFrame
Example
>>> import neurokit as nk>>>>>> nk.z_score([3, 1, 2, 4, 6])
Notes
Authors
• Dominique Makowski
Dependencies
• pandas
3.4.3 find_outliers
neurokit.find_outliers(data, treshold=2.58)Identify outliers (abnormal values) using the standart deviation.
Parameters
• data (list or ndarray) – Data array
44 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
• treshold (float) – Maximum deviation (in terms of standart deviation). Rule of thumbof a gaussian distribution: 2.58 = rejecting 1%, 2.33 = rejecting 2%, 1.96 = 5% and 1.28 =rejecting 10%.
Returns outliers – A list of True/False with True being the outliers.
Return type ndarray
Example
>>> import neurokit as nk>>> outliers = nk.find_outliers([1, 2, 1, 5, 666, 4, 1 ,3, 5])
Notes
Authors
• Dominique Makowski
Dependencies
• numpy
3.4.4 normal_range
neurokit.normal_range(mean, sd, treshold=1.28)Returns a bottom and a top limit on a normal distribution portion based on a treshold.
Parameters treshold (float) – maximum deviation (in terms of standart deviation). Rule ofthumb of a gaussian distribution: 2.58 = keeping 99%, 2.33 = keeping 98%, 1.96 = 95% and1.28 = keeping 90%.
Returns (bottom, top) – Lower and higher range.
Return type tuple
Example
>>> import neurokit as nk>>> bottom, top = nk.normal_range(mean=100, sd=15, treshold=2)
Notes
Authors
• Dominique Makowski
3.4. Statistics 45
neurokit Documentation, Release 0.1.1
3.5 Routines
3.5.1 compute_dprime
neurokit.compute_dprime(n_Hit=None, n_Miss=None, n_FA=None, n_CR=None)Computes the d’, beta, aprime, b’‘d and c parameters based on the signal detection theory (SDT). Feel free tohelp me expand the documentation of this function with details and interpretation guides.
Parameters
• n_Hit (int) – Number of hits.
• n_Miss (int) – Number of misses.
• n_FA (int) – Number of false alarms.
• n_CR (int) – Number of correct rejections.
Returns parameters – A dictionary with the parameters (see details).
Return type dict
Example
>>> import neurokit as nk>>>>>> nk.compute_dprime(n_Hit=7, n_Miss=4, n_FA=6, n_CR=6)
Notes
Details
The Signal Detection Theory (often abridged as SDT) is used in very different domains from psychology (psy-chophysics, perception, memory), medical diagnostics (do the symptoms match a known diagnostic or can theybe dismissed are irrelevant), to statistical decision (do the data indicate that the experiment has an effect or not).It evolved from the development of communications and radar equipment the first half of this century to psy-chology, as an attempt to understand some features of human behavior that were not well explained by traditionmodels. SDT is, indeed, used to analyze data coming from experiments where the task is to categorize am-biguous stimuli which can be generated either by a known process (called the signal) or be obtained by chance(called the noise in the SDT framework). Based on the number of hits, misses, false alarms and correct rejec-tions, it estimates two main parameters from the experimental data: d’ (d-prime, for discriminability index)and C (a variant of it is called beta). Non parametric variants are aprime and b’‘d (bppd)
• dprime: The sensitivity index. Indicates the strength of the signal (relative to the noise). More specifically,it is the standardized difference between the means of the Signal Present and Signal Absent distributions.
• beta: Response bias index.
• aprime: Non-parametric sensitivity index.
• bppd: Non-parametric response bias index.
• c: Response bias index.
Authors
• Dominique Makowski
Dependencies
46 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
• scipy
See Also
• neuropsychology
• http://lindeloev.net/calculating-d-in-python-and-php/
3.5.2 compute_BMI
neurokit.compute_BMI(height, weight, age, sex)Returns the traditional BMI, the ‘new’ Body Mass Index and estimates the Body Fat Percentage (BFP; Deuren-berg et al., 1991).
Parameters
• height (float) – Height in cm.
• weight (float) – Weight in kg.
• age (float) – Age in years.
• sex (str) – “m” or “f”.
Returns bmi – dict containing values and their interpretations.
Return type dict
Example
>>> import neurokit as nk>>>>>> nk.compute_BMI(height=166, weight=54, age=22, sex="f")
Notes
Authors
• Dominique Makowski
See Also
• https://people.maths.ox.ac.uk/trefethen/bmi.html
References
• Deurenberg, P., Andreoli, A., Borg, P., & Kukkonen-Harjula, K. (2001). The validity of predicted body fatpercentage from body mass index and from impedance in samples of five European populations. EuropeanJournal of Clinical Nutrition, 55(11), 973.
• Deurenberg, P., Weststrate, J. A., & Seidell, J. C. (1991). Body mass index as a measure of body fatness:age-and sex-specific prediction formulas. British journal of nutrition, 65(02), 105-114.
3.5. Routines 47
neurokit Documentation, Release 0.1.1
3.5.3 compute_interoceptive_accuracy
neurokit.compute_interoceptive_accuracy(nbeats_real, nbeats_reported)Computes interoceptive accuracy according to Garfinkel et al., (2015).
Parameters
• nbeats_real (int or list) – Real number of heartbeats.
• nbeats_reported (int or list) – Reported number of heartbeats.
Returns accuracy – Objective accuracy in detecting internal bodily sensations. It is the centralconstruct underpinning other interoceptive measures (Garfinkel et al., 2015).
Return type float or list
Example
>>> import neurokit as nk>>>>>> nk.compute_interoceptive_accuracy(5, 3)
Notes
Authors
• Dominique Makowski
Dependencies
• numpy
References
• Garfinkel, S. N., Seth, A. K., Barrett, A. B., Suzuki, K., & Critchley, H. D. (2015). Knowing your ownheart: distinguishing interoceptive accuracy from interoceptive awareness. Biological psychology, 104,65-74.
3.5.4 staircase
neurokit.staircase()
3.6 Plot
3.6.1 plot_polarbar
neurokit.plot_polarbar(scores, labels=None, labels_size=15, colors=’default’, distribu-tion_means=None, distribution_sds=None, treshold=1.28, fig_size=(15,15))
Polar bar chart.
Parameters
• scores (list or dict) – Scores to plot.
48 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
• labels (list) – List of labels to be used for ticks.
• labels_size (int) – Label’s size.
• colors (list or str) – List of colors or “default”.
• distribution_means (int or list) – List of means to add a range ribbon.
• distribution_sds (int or list) – List of SDs to add a range ribbon.
• treshold (float) – Limits of the range ribbon (in terms of standart deviation frommean).
• fig_size (tuple) – Figure size.
Returns plot – The figure.
Return type matplotlig figure
Example
>>> import neurokit as nk>>> fig = nk.plot_polarbar(scores=[1, 2, 3, 4, 5], labels=["A", "B", "C", "D", "E→˓"], distribution_means=3, distribution_sds=1)>>> fig.show()
Notes
Authors
• Dominique Makowski
Dependencies
• matplotlib
• numpy
3.7 Miscellaneous
3.7.1 find_following_duplicates
neurokit.find_following_duplicates(array)Find the duplicates that are following themselves.
Parameters array (list or ndarray) – A list containing duplicates.
Returns uniques – A list containing True for each unique and False for following duplicates.
Return type list
Example
>>> import neurokit as nk>>> mylist = ["a","a","b","a","a","a","c","c","b","b"]>>> uniques = nk.find_following_duplicates(mylist)>>> indices = np.where(uniques) # Find indices of uniques
3.7. Miscellaneous 49
neurokit Documentation, Release 0.1.1
Notes
Authors
• Dominique Makowski
Dependencies
• numpy
3.7.2 find_closest_in_list
neurokit.find_closest_in_list(number, array, direction=’both’, strictly=False)Find the closest number in the array from x.
Parameters
• number (float) – The number.
• array (list) – The list to look in.
• direction (str) – “both” for smaller or greater, “greater” for only greater numbers and“smaller” for the closest smaller.
• strictly (bool) – False for stricly superior or inferior or True for including equal.
Returns closest – The closest number in the array.
Return type int
Example
>>> import neurokit as nk>>> nk.find_closest_in_list(1.8, [3, 5, 6, 1, 2])
Notes
Authors
• Dominique Makowski
3.7.3 Time
class neurokit.TimeA class object to get time.
Its methods (functions) are:
• reset()
• get()
See those for further informations.
Parameters None –
Returns
Return type None
50 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
Example
>>> import neurokit as nk>>> myclock = nk.Time()>>> time_passed_since_myclock_creation = myclock.get()>>> myclock.reset()>>> time_passed_since_reset = myclock.get()
Notes
Authors
• Dominique Makowski
Dependencies
• time
3.8 Data
3.8.1 find_creation_date
neurokit.find_creation_date(path)Try to get the date that a file was created, falling back to when it was last modified if that’s not possible.
Parameters path (str) – File’s path.
Returns creation_date – Time of file creation.
Return type str
Example
>>> import neurokit as nk>>> import datetime>>>>>> creation_date = nk.find_creation_date(file)>>> creation_date = datetime.datetime.fromtimestamp(creation_date)
Notes
Authors
• Dominique Makowski
• Mark Amery
Dependencies
• platform
• os
See Also
• http://stackoverflow.com/a/39501288/1709587
3.8. Data 51
neurokit Documentation, Release 0.1.1
3.8.2 save_nk_object
neurokit.save_nk_object(obj, filename=’file’, path=”, extension=’nk’, compress=False,compatibility=-1)
Save whatever python object to a pickled file.
Parameters
• file (object) – Whatever python thing (list, dict, . . . ).
• filename (str) – File’s name.
• path (str) – File’s path.
• extension (str) – File’s extension. Default “nk” but can be whatever.
• compress (bool) – Enable compression using gzip.
• compatibility (int) – See pickle.dump().
Example
>>> import neurokit as nk>>> obj = [1, 2]>>> nk.save_nk_object(obj, filename="myobject")
Notes
Authors
• Dominique Makowski
Dependencies
• pickle
• gzip
3.8.3 read_nk_object
neurokit.read_nk_object(filename, path=”)Read a pickled file.
Parameters
• filename (str) – Full file’s name (with extension).
• path (str) – File’s path.
Example
>>> import neurokit as nk>>> obj = [1, 2]>>> nk.save_nk_object(obj, filename="myobject")>>> loaded_obj = nk.read_nk_object("myobject.nk")
52 Chapter 3. Documentation
neurokit Documentation, Release 0.1.1
Notes
Authors
• Dominique Makowski
Dependencies
• pickle
• gzip
3.8. Data 53
neurokit Documentation, Release 0.1.1
54 Chapter 3. Documentation
CHAPTER 4
About
NeuroKit is looking for developers, support and pretty much everything. Join the team by contributing :)
4.1 Core Team
• Dominique Makowski (France).
4.2 Contributors
• Julien Lamour (Switzerland): ECG.
• Rhenan Bartels Ferreira (Brazil): HRV, Testing, RSP, RSA.
• Nate Vack (USA): Acqknowledge files reading.
• Vassilios Vonikakis (USA): HRV.
• Anthony Gatti (Canada): Multi scale entropy.
• Nicolas Beaudoin-Gagnon (Canada): Bug corrections in EDA/ECG.
• Renato Cordeiro (USA/Brazil): ECG.
4.3 Support
• Memory & Cognition Lab, University of Sorbonne Paris Cité, Paris, France.
• L’École de Neuropsychologie, Paris, France.
55
neurokit Documentation, Release 0.1.1
4.4 Credits
Credits go to the authors of NeuroKit’s dependencies.
4.5 Featured in
NeuroKit has been used in the following publications:
• Let me know!
56 Chapter 4. About
CHAPTER 5
Installation
Installation can be easily done using pip:
pip install https://github.com/neuropsychology/NeuroKit.py/zipball/master
Note: Starting from scratch? Note that a ready-to-go python distribution (that includes NeuroKit) can be downloadedhere.
57
neurokit Documentation, Release 0.1.1
58 Chapter 5. Installation
CHAPTER 6
Questions? Help? Movie Recommendations?
Do it on the dedicated chats!
Room LinkGeneralBiosignalsEEG
59
neurokit Documentation, Release 0.1.1
60 Chapter 6. Questions? Help? Movie Recommendations?
CHAPTER 7
Index
• genindex
• modindex
• search
61
neurokit Documentation, Release 0.1.1
62 Chapter 7. Index
Index
Bbio_EventRelated() (in module neurokit), 31bio_process() (in module neurokit), 15
Ccomplexity() (in module neurokit), 40compute_BMI() (in module neurokit), 47compute_dprime() (in module neurokit), 46compute_interoceptive_accuracy() (in mod-
ule neurokit), 48create_epochs() (in module neurokit), 39
Eecg_hrv() (in module neurokit), 22ecg_preprocess() (in module neurokit), 20ecg_process() (in module neurokit), 18ecg_rsa() (in module neurokit), 24ecg_simulate() (in module neurokit), 26eda_process() (in module neurokit), 27eda_scr() (in module neurokit), 28eeg_add_channel() (in module neurokit), 34eeg_add_events() (in module neurokit), 36eeg_complexity() (in module neurokit), 37eeg_create_mne_events() (in module neurokit),
36eeg_erp() (in module neurokit), 37eeg_select_channels() (in module neurokit), 35eeg_select_electrodes() (in module neurokit),
35emg_process() (in module neurokit), 29
Ffind_closest_in_list() (in module neurokit), 50find_creation_date() (in module neurokit), 51find_events() (in module neurokit), 38find_following_duplicates() (in module neu-
rokit), 49find_outliers() (in module neurokit), 44
Mmad() (in module neurokit), 43
Nnormal_range() (in module neurokit), 45
Pplot_eeg_erp() (in module neurokit), 38plot_eeg_erp_topo() (in module neurokit), 38plot_events_in_signal() (in module neurokit),
39plot_polarbar() (in module neurokit), 48
Rread_acqknowledge() (in module neurokit), 33read_nk_object() (in module neurokit), 52rsp_process() (in module neurokit), 26
Ssave_nk_object() (in module neurokit), 52staircase() (in module neurokit), 48
TTime (class in neurokit), 50
Zz_score() (in module neurokit), 44
63
top related