diff --git a/docs/_static/neurokit_codebook.csv b/docs/_static/neurokit_codebook.csv new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/codebook.rst b/docs/codebook.rst new file mode 100644 index 0000000000..1a33073fc3 --- /dev/null +++ b/docs/codebook.rst @@ -0,0 +1,90 @@ +Codebook +======== + +Here you can download the complete codebook which details the variables that you can compute using the NeuroKit package. + +.. raw:: html + +
+ + + +
+ +This codebook contains detailed descriptions of all variables, their descriptions, and additional metadata. + + +Codebook Table +============== + +.. raw:: html + + + +
+ +
+
+ + + diff --git a/docs/conf.py b/docs/conf.py index 635cf94de6..1580ffe22b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,7 +21,7 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath("../")) @@ -69,6 +69,7 @@ def find_version(): "sphinxemoji.sphinxemoji", "sphinx_copybutton", "myst_nb", + "directives.csv_codebook_directive", ] # Add any paths that contain templates here, relative to this directory. @@ -140,4 +141,4 @@ def find_version(): # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ["_static"] +html_static_path = ["_static"] diff --git a/docs/directives/csv_codebook_directive.py b/docs/directives/csv_codebook_directive.py new file mode 100644 index 0000000000..7f48514758 --- /dev/null +++ b/docs/directives/csv_codebook_directive.py @@ -0,0 +1,89 @@ +import csv +import os +from docutils import nodes +from docutils.parsers.rst import Directive + +abrv_to_sensor = { + "ecg": "Electrocardiography", + "eda": "Electrodermal Activity", + "rsp": "Respiration", + "ppg": "Photoplethysmography", + "eeg": "Electroencephalography", + "emg": "Electromyography", + "eog": "Electrooculography", + "hrv": "Heart Rate Variability", + } + +class CSVDocDirective(Directive): + has_content = True + + def run(self): + # Codebook path + csv_file_path = os.path.join(os.path.abspath('.'), "_static", "neurokit_codebook.csv") + + # Check if the file exists and whether it is empty + file_empty = not os.path.exists(csv_file_path) or os.stat(csv_file_path).st_size == 0 + + # List to hold bullet list nodes + bullet_list = nodes.bullet_list() + + doc_source_name = self.state.document.settings.env.temp_data.get('object')[0] + + maybe_sensor = doc_source_name.split("_") + doc_sensor = "N/A" + + if len(maybe_sensor) > 0 and maybe_sensor[0] in abrv_to_sensor: + doc_sensor = abrv_to_sensor[maybe_sensor[0]] + + # Open the CSV file and append the content + with open(csv_file_path, 'a', newline='', encoding='utf-8') as csvfile: + writer = csv.writer(csvfile) + + # Write header if file is newly created or empty + if file_empty: + header = ['Field Name', 'Field Description', 'Field Category', 'Source File Name'] + writer.writerow(header) + + # Iterate through rows: add them to the codebook and add them to the page + for line in self.content: + + fields = line.split('|') + + # Remove multi line long space sequences + for fid in range(len(fields)): + fields[fid] = " ".join(fields[fid].split()) + + # Append last fields + fields.append(doc_sensor) + fields.append(f"{doc_source_name}.py") + + # Write to CSV + writer.writerow([field.strip() for field in fields]) + + + # Prepare the documentation stylization + if len(fields) >= 2: + paragraph = nodes.paragraph() + + # Create backtick formatting around the field name + field1 = nodes.literal('', '', nodes.Text(fields[0].strip())) + + # Add the remainder of the line + colon_space = nodes.Text(': ') + field2 = nodes.Text(fields[1].strip()) + + # Add all the parts to the paragraph + paragraph += field1 + paragraph += colon_space + paragraph += field2 + + # Add to the bullet point list + list_item = nodes.list_item() + list_item += paragraph + bullet_list += list_item + + return [bullet_list] + + +def setup(app): + app.add_directive("codebookadd", CSVDocDirective) diff --git a/docs/index.rst b/docs/index.rst index 801447140a..3c9218c68b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -35,6 +35,7 @@ You can navigate to the different sections using the left panel. We recommend ch installation authors cite_us + codebook examples/index functions/index resources/index diff --git a/neurokit2/ecg/ecg_eventrelated.py b/neurokit2/ecg/ecg_eventrelated.py index c3ea51f229..893c2e7887 100644 --- a/neurokit2/ecg/ecg_eventrelated.py +++ b/neurokit2/ecg/ecg_eventrelated.py @@ -30,28 +30,30 @@ def ecg_eventrelated(epochs, silent=False): by the `Label` column (if not present, by the `Index` column). The analyzed features consist of the following: - * ``ECG_Rate_Max``: the maximum heart rate after stimulus onset. - * ``ECG_Rate_Min``: the minimum heart rate after stimulus onset. - * ``ECG_Rate_Mean``: the mean heart rate after stimulus onset. - * ``ECG_Rate_SD``: the standard deviation of the heart rate after stimulus onset. - * ``ECG_Rate_Max_Time``: the time at which maximum heart rate occurs. - * ``ECG_Rate_Min_Time``: the time at which minimum heart rate occurs. - * ``ECG_Phase_Atrial``: indication of whether the onset of the event concurs with - respiratory systole (1) or diastole (0). - * ``ECG_Phase_Ventricular``: indication of whether the onset of the event concurs with - respiratory systole (1) or diastole (0). - * ``ECG_Phase_Atrial_Completion``: indication of the stage of the current cardiac (atrial) - phase (0 to 1) at the onset of the event. - * ``ECG_Phase_Ventricular_Completion``: indication of the stage of the current cardiac - (ventricular) phase (0 to 1) at the onset of the event. + .. codebookadd:: + ECG_Rate_Max|The maximum heart rate after stimulus onset. + ECG_Rate_Min|The minimum heart rate after stimulus onset. + ECG_Rate_Mean|The mean heart rate after stimulus onset. + ECG_Rate_SD|The standard deviation of the heart rate after stimulus onset. + ECG_Rate_Max_Time|The time at which maximum heart rate occurs. + ECG_Rate_Min_Time|The time at which minimum heart rate occurs. + ECG_Phase_Atrial|Indication of whether the onset of the event concurs with \ + respiratory systole (1) or diastole (0). + ECG_Phase_Ventricular|Indication of whether the onset of the event concurs with \ + respiratory systole (1) or diastole (0). + ECG_Phase_Atrial_Completion|Indication of the stage of the current cardiac (atrial) \ + phase (0 to 1) at the onset of the event. + ECG_Phase_Ventricular_Completion|Indication of the stage of the current cardiac \ + (ventricular) phase (0 to 1) at the onset of the event. We also include the following *experimental* features related to the parameters of a quadratic model: - * ``ECG_Rate_Trend_Linear``: The parameter corresponding to the linear trend. - * ``ECG_Rate_Trend_Quadratic``: The parameter corresponding to the curvature. - * ``ECG_Rate_Trend_R2``: the quality of the quadratic model. If too low, the parameters - might not be reliable or meaningful. + .. codebookadd:: + ECG_Rate_Trend_Linear|The parameter corresponding to the linear trend. + ECG_Rate_Trend_Quadratic|The parameter corresponding to the curvature. + ECG_Rate_Trend_R2|The quality of the quadratic model. If too low, the parameters \ + might not be reliable or meaningful. See Also -------- diff --git a/neurokit2/ecg/ecg_intervalrelated.py b/neurokit2/ecg/ecg_intervalrelated.py index d735b2869e..5e223cb665 100644 --- a/neurokit2/ecg/ecg_intervalrelated.py +++ b/neurokit2/ecg/ecg_intervalrelated.py @@ -25,7 +25,9 @@ def ecg_intervalrelated(data, sampling_rate=1000): DataFrame A dataframe containing the analyzed ECG features. The analyzed features consist of the following: - * ``ECG_Rate_Mean``: the mean heart rate. + .. codebookadd:: + ECG_Rate_Mean|The mean heart rate. + * ``ECG_HRV``: the different heart rate variability metrices. See :func:`.hrv_summary()` docstrings for details. diff --git a/neurokit2/ecg/ecg_process.py b/neurokit2/ecg/ecg_process.py index 39a6274a0a..584843bc7c 100644 --- a/neurokit2/ecg/ecg_process.py +++ b/neurokit2/ecg/ecg_process.py @@ -39,28 +39,27 @@ def ecg_process(ecg_signal, sampling_rate=1000, method="neurokit"): signals : DataFrame A DataFrame of the same length as the ``ecg_signal`` containing the following columns: - * ``"ECG_Raw"``: the raw signal. - * ``"ECG_Clean"``: the cleaned signal. - * ``"ECG_Rate"``: heart rate interpolated between R-peaks. - * ``"ECG_Quality"``: the quality of the cleaned signal - * ``"ECG_R_Peaks"``: the R-peaks marked as "1" in a list of zeros. - * ``"ECG_P_Peaks"``: the P-peaks marked as "1" in a list of zeros - * ``"ECG_P_Onsets"``: the P-onsets marked as "1" in a list of zeros. - * ``"ECG_P_Offsets"``: the P-offsets marked as "1" in a list of zeros. - * ``"ECG_Q_Peaks"``: the Q-peaks marked as "1" in a list of zeros . - * ``"ECG_R_Onsets"``: the R-onsets marked as "1" in a list of zeros. - * ``"ECG_R_Offsets"``: the R-offsets marked as "1" in a list of zeros. - * ``"ECG_S_Peaks"``: the S-peaks marked as "1" in a list of zeros. - * ``"ECG_T_Peaks"``: the T-peaks marked as "1" in a list of zeros. - * ``"ECG_T_Onsets"``: the T-onsets marked as "1" in a list of zeros. - * ``"ECG_T_Offsets"``: the T-offsets marked as "1" in a list of zeros. - * ``"ECG_Phase_Atrial"``: cardiac phase, marked by "1" for systole and "0" for diastole. - * ``"ECG_Phase_Completion_Atrial"``: cardiac phase (atrial) completion, expressed in - percentage (from 0 to 1), representing the stage of the current cardiac phase. - * ``"ECG_Phase_Ventricular"``: cardiac phase, marked by "1" for systole and "0" for - diastole. - * ``"ECG_Phase_Completion_Ventricular"``: cardiac phase (ventricular) completion, expressed - in percentage (from 0 to 1), representing the stage of the current cardiac phase. + .. codebookadd:: + ECG_Raw|The raw signal. + ECG_Clean|The cleaned signal. + ECG_Rate|Heart rate interpolated between R-peaks. + ECG_Quality|The quality of the cleaned signal. + ECG_R_Peaks|The R-peaks marked as "1" in a list of zeros. + ECG_R_Onsets|The R-onsets marked as "1" in a list of zeros. + ECG_R_Offsets|The R-offsets marked as "1" in a list of zeros. + ECG_P_Peaks|The P-peaks marked as "1" in a list of zeros. + ECG_P_Onsets|The P-onsets marked as "1" in a list of zeros. + ECG_P_Offsets|The P-offsets marked as "1" in a list of zeros. + ECG_Q_Peaks|The Q-peaks marked as "1" in a list of zeros. + ECG_S_Peaks|The S-peaks marked as "1" in a list of zeros. + ECG_T_Peaks|The T-peaks marked as "1" in a list of zeros. + ECG_T_Onsets|The T-onsets marked as "1" in a list of zeros. + ECG_T_Offsets|The T-offsets marked as "1" in a list of zeros. + ECG_Phase_Atrial|Cardiac phase, marked by "1" for systole and "0" for diastole. + ECG_Phase_Completion_Atrial|Cardiac phase (atrial) completion, expressed in \ + percentage (from 0 to 1), representing the stage of the current cardiac phase. + ECG_Phase_Completion_Ventricular|Cardiac phase (ventricular) completion, expressed \ + in percentage (from 0 to 1), representing the stage of the current cardiac phase. rpeaks : dict A dictionary containing the samples at which the R-peaks occur, accessible with the key @@ -88,6 +87,8 @@ def ecg_process(ecg_signal, sampling_rate=1000, method="neurokit"): @suppress plt.close() + + """ # Sanitize and clean input diff --git a/neurokit2/eda/eda_eventrelated.py b/neurokit2/eda/eda_eventrelated.py index 732088672a..d12b58ecab 100644 --- a/neurokit2/eda/eda_eventrelated.py +++ b/neurokit2/eda/eda_eventrelated.py @@ -30,22 +30,18 @@ def eda_eventrelated(epochs, silent=False): by the `Label` column (if not present, by the `Index` column). The analyzed features consist the following: - * ``"EDA_SCR"``: indication of whether Skin Conductance Response (SCR) occurs following the event - (1 if an SCR onset is present and 0 if absent) and if so, its corresponding peak amplitude, - time of peak, rise and recovery time. If there is no occurrence of SCR, nans are displayed - for the below features. - - * ``"EDA_Peak_Amplitude"``: the maximum amplitude of the phasic component of the signal. - - * ``"SCR_Peak_Amplitude"``: the peak amplitude of the first SCR in each epoch. - - * ``"SCR_Peak_Amplitude_Time"``: the timepoint of each first SCR peak amplitude. - - * ``"SCR_RiseTime"``: the risetime of each first SCR i.e., the time it takes for SCR to - reach peak amplitude from onset. - - * ``"SCR_RecoveryTime"``: the half-recovery time of each first SCR i.e., the time it takes - for SCR to decrease to half amplitude. + .. codebookadd:: + EDA_SCR|indication of whether Skin Conductance Response (SCR) occurs following the \ + event (1 if an SCR onset is present and 0 if absent) and if so, its corresponding \ + peak amplitude, time of peak, rise and recovery time. If there is no occurrence \ + of SCR, nans are displayed for the below features. + EDA_Peak_Amplitude|The maximum amplitude of the phasic component of the signal. + SCR_Peak_Amplitude|The peak amplitude of the first SCR in each epoch. + SCR_Peak_Amplitude_Time|The timepoint of each first SCR peak amplitude. + SCR_RiseTime|The risetime of each first SCR i.e., the time it takes for SCR to \ + reach peak amplitude from onset. + SCR_RecoveryTime|The half-recovery time of each first SCR i.e., the time it takes \ + for SCR to decrease to half amplitude. See Also -------- diff --git a/neurokit2/eda/eda_intervalrelated.py b/neurokit2/eda/eda_intervalrelated.py index 7cdebabd4a..f480ec7569 100644 --- a/neurokit2/eda/eda_intervalrelated.py +++ b/neurokit2/eda/eda_intervalrelated.py @@ -33,9 +33,11 @@ def eda_intervalrelated(data, sampling_rate=1000, **kwargs): A dataframe containing the analyzed EDA features. The analyzed features consist of the following: - * ``"SCR_Peaks_N"``: the number of occurrences of Skin Conductance Response (SCR). - * ``"SCR_Peaks_Amplitude_Mean"``: the mean amplitude of the SCR peak occurrences. - * ``"EDA_Tonic_SD"``: the mean amplitude of the SCR peak occurrences. + .. codebookadd:: + SCR_Peaks_N|The number of occurrences of Skin Conductance Response (SCR). + SCR_Peaks_Amplitude_Mean|The mean amplitude of the SCR peak occurrences. + EDA_Tonic_SD|The mean amplitude of the SCR peak occurrences. + * ``"EDA_Sympathetic"``: see :func:`eda_sympathetic` (only computed if signal duration > 64 sec). * ``"EDA_Autocorrelation"``: see :func:`eda_autocor` (only computed if signal duration diff --git a/neurokit2/eda/eda_process.py b/neurokit2/eda/eda_process.py index 862dd5cd2d..c93361eaa3 100644 --- a/neurokit2/eda/eda_process.py +++ b/neurokit2/eda/eda_process.py @@ -40,31 +40,20 @@ def eda_process( A DataFrame of same length as ``"eda_signal"`` containing the following columns: - * ``"EDA_Raw"``: the raw signal. + .. codebookadd:: + EDA_Raw|The raw signal. + EDA_Clean|The cleaned signal. + EDA_Tonic|The tonic component of the signal, or the Tonic Skin Conductance Level (SCL). + EDA_Phasic|The phasic component of the signal, or the Phasic Skin Conductance Response (SCR). + SCR_Onsets|The samples at which the onsets of the peaks occur, marked as "1" in a list of zeros. + SCR_Peaks|The samples at which the peaks occur, marked as "1" in a list of zeros. + SCR_Height|The SCR amplitude of the signal including the Tonic component. Note that cumulative \ + effects of close-occurring SCRs might lead to an underestimation of the amplitude. + SCR_Amplitude|The SCR amplitude of the signal excluding the Tonic component. + SCR_RiseTime|The SCR amplitude of the signal excluding the Tonic component. + SCR_Recovery|The samples at which SCR peaks recover (decline) to half amplitude, marked as "1" \ + in a list of zeros. - * ``"EDA_Clean"``: the cleaned signal. - - * ``"EDA_Tonic"``: the tonic component of the signal, or the Tonic Skin Conductance Level - (SCL). - - * ``"EDA_Phasic"``: the phasic component of the signal, or the Phasic Skin Conductance - Response (SCR). - - * ``"SCR_Onsets"``: the samples at which the onsets of the peaks occur, marked as "1" in a - list of zeros. - - * ``"SCR_Peaks"``: the samples at which the peaks occur, marked as "1" in a list of zeros. - - * ``"SCR_Height"``: the SCR amplitude of the signal including the Tonic component. Note that - cumulative effects of close-occurring SCRs might lead to an underestimation of the - amplitude. - - * ``"SCR_Amplitude"``: the SCR amplitude of the signal excluding the Tonic component. - - * ``"SCR_RiseTime"``: the time taken for SCR onset to reach peak amplitude within the SCR. - - * ``"SCR_Recovery"``: the samples at which SCR peaks recover (decline) to half amplitude, - marked as "1" in a list of zeros. info : dict A dictionary containing the information of each SCR peak (see :func:`eda_findpeaks`), as well as the signals' sampling rate. diff --git a/neurokit2/eda/eda_sympathetic.py b/neurokit2/eda/eda_sympathetic.py index 3a9f311d0a..bd7c93816b 100644 --- a/neurokit2/eda/eda_sympathetic.py +++ b/neurokit2/eda/eda_sympathetic.py @@ -47,6 +47,12 @@ def eda_sympathetic( ``"EDA_Sympathetic"`` and ``"EDA_SympatheticN"`` (normalized, obtained by dividing EDA_Symp by total power). + .. codebookadd:: + EDA_Sympathetic|Derived from Posada-Quintero et al. (2016), who argue that dynamics of \ + the sympathetic component of EDA signal is represented in the frequency band of 0.045-0.25Hz. + EDA_SympatheticN|normalized version of "EDA_Sympathetic" obtained by dividing \ + EDA_Sympathetic by total power + Examples -------- .. ipython:: python diff --git a/neurokit2/emg/emg_eventrelated.py b/neurokit2/emg/emg_eventrelated.py index ee2336a5c6..6b8bf3eb36 100644 --- a/neurokit2/emg/emg_eventrelated.py +++ b/neurokit2/emg/emg_eventrelated.py @@ -31,15 +31,13 @@ def emg_eventrelated(epochs, silent=False): by the `Label` column (if not present, by the `Index` column). The analyzed features consist of the following: - * ``"EMG_Activation*``: indication of whether there is muscular activation following - the onset of the event (1 if present, 0 if absent) and if so, its corresponding - amplitude features and the number of activations in each epoch. If there is no - activation, nans are displayed for the below features. - * ``"EMG_Amplitude_Mean*``: the mean amplitude of the activity. - * ``"EMG_Amplitude_Max*``: the maximum amplitude of the activity. - * ``"EMG_Amplitude_SD*``: the standard deviation of the activity amplitude. - * ``"EMG_Amplitude_Max_Time*``: the time of maximum amplitude. - * ``"EMG_Bursts*``: the number of activations, or bursts of activity, within each epoch. + .. codebookadd:: + EMG_Activation|Indication of whether there is muscular activation following. + EMG_Amplitude_Mean|The mean amplitude of the activity. + EMG_Amplitude_Max|The maximum amplitude of the activity. + EMG_Amplitude_SD|The standard deviation of the activity amplitude. + EMG_Amplitude_Max_Time|The time of maximum amplitude. + EMG_Bursts|The number of activations, or bursts of activity, within each epoch. See Also -------- diff --git a/neurokit2/emg/emg_intervalrelated.py b/neurokit2/emg/emg_intervalrelated.py index 8eac5392dc..13af79e791 100644 --- a/neurokit2/emg/emg_intervalrelated.py +++ b/neurokit2/emg/emg_intervalrelated.py @@ -19,8 +19,10 @@ def emg_intervalrelated(data): ------- DataFrame A dataframe containing the analyzed EMG features. The analyzed features consist of the following: - * ``"EMG_Activation_N"``: the number of bursts of muscular activity. - * ``"EMG_Amplitude_Mean"``: the mean amplitude of the muscular activity. + + .. codebookadd:: + EMG_Activation_N|The number of bursts of muscular activity. + ECG_Amplitude_Mean|The mean amplitude of the muscular activity. See Also -------- diff --git a/neurokit2/emg/emg_process.py b/neurokit2/emg/emg_process.py index 91229ae890..20b2cb12ba 100644 --- a/neurokit2/emg/emg_process.py +++ b/neurokit2/emg/emg_process.py @@ -35,13 +35,14 @@ def emg_process(emg_signal, sampling_rate=1000, report=None, **kwargs): signals : DataFrame A DataFrame of same length as ``emg_signal`` containing the following columns: - * ``"EMG_Raw"``: the raw signal. - * ``"EMG_Clean"``: the cleaned signal. - * ``"EMG_Amplitude"``: the signal amplitude, or the activation level of the signal. - * ``"EMG_Activity"``: the activity of the signal for which amplitude exceeds the threshold - specified,marked as "1" in a list of zeros. - * ``"EMG_Onsets"``: the onsets of the amplitude, marked as "1" in a list of zeros. - * ``"EMG_Offsets"``: the offsets of the amplitude, marked as "1" in a list of zeros. + .. codebookadd:: + EMG_Raw|The raw EMG signal. + EMG_Clean|The cleaned EMG signal. + EMG_Amplitude|The signal amplitude, or the activation of the signal. + EMG_Activity|The activity of the signal for which amplitude exceeds the threshold \ + specified,marked as "1" in a list of zeros. + EMG_Onsets|The onsets of the amplitude, marked as "1" in a list of zeros. + EMG_Offsets|The offsets of the amplitude, marked as "1" in a list of zeros. info : dict A dictionary containing the information of each amplitude onset, offset, and peak activity diff --git a/neurokit2/eog/eog_eventrelated.py b/neurokit2/eog/eog_eventrelated.py index ce5b377508..ac8a56beda 100644 --- a/neurokit2/eog/eog_eventrelated.py +++ b/neurokit2/eog/eog_eventrelated.py @@ -31,21 +31,15 @@ def eog_eventrelated(epochs, silent=False): by the `Label` column (if not present, by the `Index` column). The analyzed features consist of the following: - * ``"EOG_Rate_Baseline"``: the baseline EOG rate before stimulus onset. - - * ``"EOG_Rate_Max"``: the maximum EOG rate after stimulus onset. - - * ``"EOG_Rate_Min"``: the minimum EOG rate after stimulus onset. - - * ``"EOG_Rate_Mean"``: the mean EOG rate after stimulus onset. - - * ``"EOG_Rate_SD"``: the standard deviation of the EOG rate after stimulus onset. - - * ``"EOG_Rate_Max_Time"``: the time at which maximum EOG rate occurs. - - * ``"EOG_Rate_Min_Time"``: the time at which minimum EOG rate occurs. - - * ``"EOG_Blinks_Presence"``: marked with '1' if a blink occurs in the epoch, and '0' if not. + .. codebookadd:: + EOG_Rate_Baseline|The baseline EOG rate before stimulus onset. + EOG_Rate_Max|The maximum EOG rate after stimulus onset. + EOG_Rate_Min|The minimum EOG rate after stimulus onset. + EOG_Rate_Mean|The mean EOG rate after stimulus onset. + EOG_Rate_SD|The standard deviation of the EOG rate after stimulus onset. + EOG_Rate_Max_Time|The time at which maximum EOG rate occurs. + EOG_Rate_Min_Time|The time at which minimum EOG rate occurs. + EOG_Blinks_Presence|Marked with '1' if a blink occurs in the epoch, and '0' if not. See Also -------- diff --git a/neurokit2/eog/eog_intervalrelated.py b/neurokit2/eog/eog_intervalrelated.py index 71abf08ca6..ff2c26689b 100644 --- a/neurokit2/eog/eog_intervalrelated.py +++ b/neurokit2/eog/eog_intervalrelated.py @@ -22,9 +22,9 @@ def eog_intervalrelated(data): A dataframe containing the analyzed EOG features. The analyzed features consist of the following: - * ``"EOG_Rate_Mean"``: the mean heart rate. - - * ``"EOG_Peaks_N"``: the number of blink peak occurrences. + .. codebookadd:: + EOG_Rate_Mean|The mean EOG value. + EOG_Peaks_N|The number of blink peak occurrences. See Also -------- diff --git a/neurokit2/eog/eog_process.py b/neurokit2/eog/eog_process.py index 13ec77a858..1cf1823c7b 100644 --- a/neurokit2/eog/eog_process.py +++ b/neurokit2/eog/eog_process.py @@ -30,10 +30,11 @@ def eog_process(veog_signal, sampling_rate=1000, **kwargs): signals : DataFrame A DataFrame of the same length as the :func:`.eog_signal` containing the following columns: - * ``"EOG_Raw"``: the raw signal. - * ``"EOG_Clean"``: the cleaned signal. - * ``"EOG_Blinks"``: the blinks marked as "1" in a list of zeros. - * ``"EOG_Rate"``: eye blinks rate interpolated between blinks. + .. codebookadd:: + EOG_Raw|The raw signal. + EOG_Clean|The cleaned signal. + EOG_Blinks|The blinks marked as "1" in a list of zeros. + EOG_Rate|Eye blink rate interpolated between blinks info : dict A dictionary containing the samples at which the eye blinks occur, accessible with the key diff --git a/neurokit2/hrv/hrv_frequency.py b/neurokit2/hrv/hrv_frequency.py index 5b61ad6286..1fb7031f76 100644 --- a/neurokit2/hrv/hrv_frequency.py +++ b/neurokit2/hrv/hrv_frequency.py @@ -101,7 +101,24 @@ def hrv_frequency( Returns ------- DataFrame - Contains frequency domain HRV metrics. + DataFrame consisting of the computed HRV frequency metrics, which includes: + + .. codebookadd:: + HRV_ULF|The spectral power of ultra low frequencies (by default, .0 to .0033 Hz). \ + Very long signals are required for this to index to be extracted, otherwise, \ + will return NaN. + HRV_VLF|The spectral power of very low frequencies (by default, .0033 to .04 Hz). + HRV_LF|The spectral power of low frequencies (by default, .04 to .15 Hz). + HRV_HF|The spectral power of high frequencies (by default, .15 to .4 Hz). + HRV_VHF|The spectral power of very high frequencies (by default, .4 to .5 Hz). + HRV_TP|The total spectral power. + HRV_LFHF|The ratio obtained by dividing the low frequency power by the high frequency \ + power. + HRV_LFn|The normalized low frequency, obtained by dividing the low frequency power by \ + the total power. + HRV_HFn|The normalized high frequency, obtained by dividing the low frequency power by \ + the total power. + HRV_LnHF|The log transformed HF. See Also -------- diff --git a/neurokit2/hrv/hrv_nonlinear.py b/neurokit2/hrv/hrv_nonlinear.py index cf7c6058a6..cb699b8be2 100644 --- a/neurokit2/hrv/hrv_nonlinear.py +++ b/neurokit2/hrv/hrv_nonlinear.py @@ -144,7 +144,62 @@ def hrv_nonlinear(peaks, sampling_rate=1000, show=False, **kwargs): Returns ------- DataFrame - Contains non-linear HRV metrics. + DataFrame consisting of the computed non-linear HRV metrics, which includes: + + .. codebookadd:: + HRV_SD1|Standard deviation perpendicular to the line of identity. It is an index of \ + short-term RR interval fluctuations, i.e., beat-to-beat variability. It is \ + equivalent (although on another scale) to RMSSD, and therefore it is redundant to \ + report correlation with both. + HRV_SD2|Standard deviation along the identity line. Index of long-term HRV changes. + HRV_SD1SD2|Ratio of SD1 to SD2. Describes the ratio of short term to long term \ + variations in HRV. + HRV_S|Area of ellipse described by *SD1* and *SD2* (``pi * SD1 * SD2``). It is \ + proportional to *SD1SD2*. + HRV_CSI|The Cardiac Sympathetic Index (Toichi, 1997) is a measure of cardiac \ + sympathetic function independent of vagal activity, calculated by dividing the \ + longitudinal variability of the Poincaré plot (``4*SD2``) by its transverse \ + variability (``4*SD1``). + HRV_CVI|The Cardiac Vagal Index (Toichi, 1997) is an index of cardiac parasympathetic \ + function (vagal activity unaffected by sympathetic activity), and is equal equal \ + to the logarithm of the product of longitudinal (``4*SD2``) and transverse \ + variability (``4*SD1``). + HRV_CSI_Modified|The modified CSI (Jeppesen, 2014) obtained by dividing the square of \ + the longitudinal variability by its transverse variability. + HRV_GI|Guzik's Index, defined as the distance of points above line of identity (LI) to \ + LI divided by the distance of all points in Poincaré plot to LI except those that \ + are located on LI. + HRV_SI|Slope Index, defined as the phase angle of points above LI divided by the phase \ + angle of all points in Poincaré plot except those that are located on LI. + HRV_AI|Area Index, defined as the cumulative area of the sectors corresponding to the \ + points that are located above LI divided by the cumulative area of sectors \ + corresponding to all points in the Poincaré plot except those that are located \ + on LI. + HRV_PI|Porta's Index, defined as the number of points below LI divided by the total \ + number of points in Poincaré plot except those that are located on LI. + HRV_SD1a|Short-term variance of contributions of decelerations (prolongations of RR \ + intervals), (Piskorski, 2011). + HRV_SD1d|Short-term variance of contributions of accelerations (shortenings of RR \ + intervals), (Piskorski, 2011). + HRV_C1a|The contributions of heart rate accelerations to short-term HRV, (Piskorski, 2011). + HRV_C1d|The contributions of heart rate decelerations to short-term HRV, (Piskorski, 2011). + HRV_SD2a|Long-term variance of contributions of accelerations (shortenings of RR \ + intervals), (Piskorski, 2011). + HRV_SD2d|Long-term variance of contributions of decelerations (prolongations of RR \ + intervals), (Piskorski, 2011). + HRV_C2a|The contributions of heart rate accelerations to long-term HRV, (Piskorski, 2011). + HRV_C2d|The contributions of heart rate decelerations to long-term HRV, (Piskorski, 2011). + HRV_SDNNa|Total variance of contributions of accelerations (shortenings of RR \ + intervals), (Piskorski, 2011). + HRV_SDNNd|Total variance of contributions of decelerations (prolongations of RR \ + intervals), (Piskorski, 2011). + HRV_Ca|The total contributions of heart rate accelerations to HRV. + HRV_Cd|The total contributions of heart rate decelerations to HRV. + HRV_PIP|Percentage of inflection points of the RR intervals series. + HRV_IALS|Inverse of the average length of the acceleration/deceleration segments. + HRV_PSS|Percentage of short segments. + HRV_PAS|Percentage of NN intervals in alternation segments. + See Also -------- diff --git a/neurokit2/hrv/hrv_rsa.py b/neurokit2/hrv/hrv_rsa.py index 2970212fbc..9aee3fcfe7 100644 --- a/neurokit2/hrv/hrv_rsa.py +++ b/neurokit2/hrv/hrv_rsa.py @@ -95,16 +95,15 @@ def hrv_rsa( rsa : dict A dictionary containing the RSA features, which includes: - * ``"RSA_P2T_Values"``: the estimate of RSA during each breath cycle, produced by - subtracting the shortest heart period (or RR interval) from the longest heart period in - ms. - * ``"RSA_P2T_Mean"``: the mean peak-to-trough across all cycles in ms - * ``"RSA_P2T_Mean_log"``: the logarithm of the mean of RSA estimates. - * ``"RSA_P2T_SD"``: the standard deviation of all RSA estimates. - * ``"RSA_P2T_NoRSA"``: the number of breath cycles - from which RSA could not be calculated. - * ``"RSA_PorgesBohrer"``: the Porges-Bohrer estimate of RSA, optimal - when the signal to noise ratio is low, in ``ln(ms^2)``. + .. codebookadd:: + RSA_P2T_Values|The estimate of RSA during each breath cycle, produced by subtracting \ + the shortest heart period (or RR interval) from the longest heart period in ms. + RSA_P2T_Mean|The mean peak-to-trough across all cycles in ms. + RSA_P2T_Mean_log|The logarithm of the mean of RSA estimates. + RSA_P2T_SD|The standard deviation of all RSA estimates. + RSA_P2T_NoRSA|The number of breath cycles from which RSA could not be calculated. + RSA_PorgesBohrer|The Porges-Bohrer estimate of RSA, optimal when the signal to noise \ + ratio is low, in ln(ms^2). Example ---------- diff --git a/neurokit2/ppg/ppg_eventrelated.py b/neurokit2/ppg/ppg_eventrelated.py index a6e8aa72d5..59518f0afc 100644 --- a/neurokit2/ppg/ppg_eventrelated.py +++ b/neurokit2/ppg/ppg_eventrelated.py @@ -26,29 +26,23 @@ def ppg_eventrelated(epochs, silent=False): by the `Label` column (if not present, by the `Index` column). The analyzed features consist of the following: - * ``"PPG_Rate_Baseline"``: the baseline heart rate (at stimulus onset). - - * ``"PPG_Rate_Max"``: the maximum heart rate after stimulus onset. - - * ``"PPG_Rate_Min"``: the minimum heart rate after stimulus onset. - - * ``"PPG_Rate_Mean"``: the mean heart rate after stimulus onset. - - * ``"PPG_Rate_SD"``: the standard deviation of the heart rate after stimulus onset. - - * ``"PPG_Rate_Max_Time"``: the time at which maximum heart rate occurs. - - * ``"PPG_Rate_Min_Time"``: the time at which minimum heart rate occurs. + .. codebookadd:: + PPG_Rate_Baseline|The baseline heart rate (at stimulus onset). + PPG_Rate_Max|The maximum heart rate after stimulus onset. + PPG_Rate_Min|The minimum heart rate after stimulus onset. + PPG_Rate_Mean|The mean heart rate after stimulus onset. + PPG_Rate_SD|The standard deviation of the heart rate after stimulus onset. + PPG_Rate_Max_Time|The time at which maximum heart rate occurs. + PPG_Rate_Min_Time|The time at which minimum heart rate occurs. We also include the following *experimental* features related to the parameters of a quadratic model: - * ``"PPG_Rate_Trend_Linear"``: The parameter corresponding to the linear trend. - - * ``"PPG_Rate_Trend_Quadratic"``: The parameter corresponding to the curvature. - - * ``"PPG_Rate_Trend_R2"``: the quality of the quadratic model. If too low, the parameters - might not be reliable or meaningful. + .. codebookadd:: + PPG_Rate_Trend_Linear|The parameter corresponding to the linear trend. + PPG_Rate_Trend_Quadratic|The parameter corresponding to the curvature. + PPG_Rate_Trend_R2|The quality of the quadratic model. If too low, the parameters \ + might not be reliable or meaningful. See Also -------- diff --git a/neurokit2/ppg/ppg_intervalrelated.py b/neurokit2/ppg/ppg_intervalrelated.py index fdee4fd9d8..4f46ba0c03 100644 --- a/neurokit2/ppg/ppg_intervalrelated.py +++ b/neurokit2/ppg/ppg_intervalrelated.py @@ -23,7 +23,8 @@ def ppg_intervalrelated(data, sampling_rate=1000): DataFrame A dataframe containing the analyzed PPG features. The analyzed features consist of the following: - * ``"PPG_Rate_Mean"``: the mean heart rate. + .. codebookadd:: + PPG_Rate_Mean|The mean PPG rate. * ``"HRV"``: the different heart rate variability metrices. diff --git a/neurokit2/ppg/ppg_process.py b/neurokit2/ppg/ppg_process.py index 21a94993ba..31302aca2c 100644 --- a/neurokit2/ppg/ppg_process.py +++ b/neurokit2/ppg/ppg_process.py @@ -44,10 +44,11 @@ def ppg_process( signals : DataFrame A DataFrame of same length as :func:`.ppg_signal` containing the following columns: - * ``"PPG_Raw"``: the raw signal. - * ``"PPG_Clean"``: the cleaned signal. - * ``"PPG_Rate"``: the heart rate as measured based on PPG peaks. - * ``"PPG_Peaks"``: the PPG peaks marked as "1" in a list of zeros. + .. codebookadd:: + PPG_Raw|The raw signal. + PPG_Clean|The cleaned signal. + PPG_Rate|The heart rate as measured based on PPG peaks. + PPG_Peaks|The PPG peaks marked as "1" in a list of zeros. info : dict A dictionary containing the information of peaks and the signals' sampling rate. diff --git a/neurokit2/rsp/rsp_eventrelated.py b/neurokit2/rsp/rsp_eventrelated.py index 321fc645e0..8750b690b5 100644 --- a/neurokit2/rsp/rsp_eventrelated.py +++ b/neurokit2/rsp/rsp_eventrelated.py @@ -31,25 +31,20 @@ def rsp_eventrelated(epochs, silent=False): by the `Label` column (if not present, by the `Index` column). The analyzed features consist of the following: - * ``"RSP_Rate_Max"``: the maximum respiratory rate after stimulus onset. - * ``"RSP_Rate_Min"``: the minimum respiratory rate after stimulus onset. - * ``"RSP_Rate_Mean"``: the mean respiratory rate after stimulus onset. - * ``"RSP_Rate_SD"``: the standard deviation of the respiratory rate after stimulus onset. - * ``"RSP_Rate_Max_Time"``: the time at which maximum respiratory rate occurs. - * ``"RSP_Rate_Min_Time"``: the time at which minimum respiratory rate occurs. - * ``"RSP_Amplitude_Baseline"``: the respiratory amplitude at stimulus onset. - * ``"RSP_Amplitude_Max"``: the change in maximum respiratory amplitude from before stimulus - onset. - * ``"RSP_Amplitude_Min"``: the change in minimum respiratory amplitude from before stimulus - onset. - * ``"RSP_Amplitude_Mean"``: the change in mean respiratory amplitude from before stimulus - onset. - * ``"RSP_Amplitude_SD"``: the standard deviation of the respiratory amplitude after - stimulus onset. - * ``"RSP_Phase"``: indication of whether the onset of the event concurs with respiratory - inspiration (1) or expiration (0). - * ``"RSP_PhaseCompletion"``: indication of the stage of the current respiration phase (0 to - 1) at the onset of the event. + .. codebookadd:: + RSP_Rate_Max|The maximum respiratory rate after stimulus onset. + RSP_Rate_Min|The minimum respiratory rate after stimulus onset. + RSP_Rate_Mean|The mean respiratory rate after stimulus onset. + RSP_Rate_SD|The standard deviation of the respiratory rate after stimulus onset. + RSP_Rate_Max_Time|The time at which maximum respiratory rate occurs. + RSP_Rate_Min_Time|The time at which minimum respiratory rate occurs. + RSP_Amplitude_Baseline|The respiratory amplitude at stimulus onset. + RSP_Amplitude_Max|The change in maximum respiratory amplitude from before stimulus onset. + RSP_Amplitude_Min|The change in minimum respiratory amplitude from before stimulus onset. + RSP_Amplitude_Mean|The change in mean respiratory amplitude from before stimulus onset. + RSP_Amplitude_SD|The standard deviation of the respiratory amplitude after stimulus onset. + RSP_Phase|Indication of whether the onset of the event concurs with respiratory inspiration (1) or expiration (0). + RSP_PhaseCompletion|Indication of the stage of the current respiration phase (0 to 1) at the onset of the event. See Also -------- diff --git a/neurokit2/rsp/rsp_intervalrelated.py b/neurokit2/rsp/rsp_intervalrelated.py index 10b7342b6b..738083a027 100644 --- a/neurokit2/rsp/rsp_intervalrelated.py +++ b/neurokit2/rsp/rsp_intervalrelated.py @@ -28,13 +28,15 @@ def rsp_intervalrelated(data, sampling_rate=1000): A dataframe containing the analyzed RSP features. The analyzed features consist of the following: - * ``"RSP_Rate_Mean"``: the mean respiratory rate. - * ``"RSP_Amplitude_Mean"``: the mean respiratory amplitude. + .. codebookadd:: + RSP_Rate_Mean|The mean respiratory rate. + RSP_Amplitude_Mean|The mean respiratory amplitude. + RSP_Phase_Duration_Inspiration|The average inspiration duration. + RSP_Phase_Duration_Expiration|The average expiration duration. + RSP_Phase_Duration_Ratio|The inspiration-to-expiratory time ratio (I/E). + * ``"RSP_RRV"``: the different respiratory rate variability metrices. See :func:`.rsp_rrv` docstrings for details. - * ``"RSP_Phase_Duration_Inspiration"``: the average inspiratory duration. - * ``"RSP_Phase_Duration_Expiration"``: the average expiratory duration. - * ``"RSP_Phase_Duration_Ratio "``: the inspiratory-to-expiratory time ratio (I/E). See Also -------- diff --git a/neurokit2/rsp/rsp_process.py b/neurokit2/rsp/rsp_process.py index 9e32036fee..3dd153157e 100644 --- a/neurokit2/rsp/rsp_process.py +++ b/neurokit2/rsp/rsp_process.py @@ -57,18 +57,18 @@ def rsp_process( signals : DataFrame A DataFrame of same length as :func:`.rsp_signal` containing the following columns: - * ``"RSP_Raw"``: the raw signal. - * ``"RSP_Clean"``: the cleaned signal. - * ``"RSP_Peaks"``: the respiratory peaks (exhalation onsets) marked as "1" in a list of - zeros. - * ``"RSP_Troughs"``: the respiratory troughs (inhalation onsets) marked as "1" in a list of - zeros. - * ``"RSP_Rate"``: breathing rate interpolated between inhalation peaks. - * ``"RSP_Amplitude"``: breathing amplitude interpolated between inhalation peaks. - * ``"RSP_Phase"``: breathing phase, marked by "1" for inspiration and "0" for expiration. - * ``"RSP_Phase_Completion"``: breathing phase completion, expressed in percentage (from 0 to - 1), representing the stage of the current respiratory phase. - * ``"RSP_RVT"``: respiratory volume per time (RVT). + .. codebookadd:: + RSP_Raw|The raw signal. + RSP_Clean|The raw signal. + RSP_Peaks|The respiratory peaks (exhalation onsets) marked as "1" in a list of zeros. + RSP_Troughs|The respiratory troughs (inhalation onsets) marked as "1" in a list \ + of zeros. + RSP_Rate|The breathing rate interpolated between inhalation peaks. + RSP_Amplitude|The breathing amplitude interpolated between inhalation peaks. + RSP_Phase|The breathing phase, marked by "1" for inspiration and "0" for expiration. + RSP_Phase_Completion|The breathing phase completion, expressed in percentage \ + (from 0 to 1), representing the stage of the current respiratory phase. + RSP_RVT|Respiratory volume per time (RVT). info : dict A dictionary containing the samples at which inhalation peaks and exhalation troughs occur, diff --git a/neurokit2/rsp/rsp_rrv.py b/neurokit2/rsp/rsp_rrv.py index 3516911a11..7bc114dc1c 100644 --- a/neurokit2/rsp/rsp_rrv.py +++ b/neurokit2/rsp/rsp_rrv.py @@ -41,43 +41,40 @@ def rsp_rrv(rsp_rate, troughs=None, sampling_rate=1000, show=False, silent=True) DataFrame DataFrame consisting of the computed RRV metrics, which includes: - * ``"RRV_SDBB"``: the standard deviation of the breath-to-breath intervals. - * ``"RRV_RMSSD"``: the root mean square of successive differences of the breath-to-breath - intervals. - * ``"RRV_SDSD"``: the standard deviation of the successive differences between adjacent - breath-to-breath intervals. - * ``"RRV_BBx"``: the number of successive interval differences that are greater than x - seconds. - * ``"RRV-pBBx"``: the proportion of breath-to-breath intervals that are greater than x - seconds, - out of the total number of intervals. - * ``"RRV_VLF"``: spectral power density pertaining to very low frequency band (i.e., 0 to . - 04 Hz) by default. - * ``"RRV_LF"``: spectral power density pertaining to low frequency band (i.e., .04 to .15 - Hz) by default. - * ``"RRV_HF"``: spectral power density pertaining to high frequency band (i.e., .15 to .4 - Hz) by default. - * ``"RRV_LFHF"``: the ratio of low frequency power to high frequency power. - * ``"RRV_LFn"``: the normalized low frequency, obtained by dividing the low frequency - power by the total power. - * ``"RRV_HFn"``: the normalized high frequency, obtained by dividing the low frequency - power by total power. - * ``"RRV_SD1"``: SD1 is a measure of the spread of breath-to-breath intervals on the - Poincaré plot perpendicular to the line of identity. It is an index of short-term - variability. - * ``"RRV_SD2"``: SD2 is a measure of the spread of breath-to-breath intervals on the - Poincaré plot along the line of identity. It is an index of long-term variability. - * ``"RRV_SD2SD1"``: the ratio between short and long term fluctuations of the - breath-to-breath intervals (SD2 divided by SD1). - * ``"RRV_ApEn"``: the approximate entropy of RRV, calculated - by :func:`.entropy_approximate`. - * ``"RRV_SampEn"``: the sample entropy of RRV, calculated by :func:`.entropy_sample`. - * ``"RRV_DFA_alpha1"``: the "short-term" fluctuation value generated from Detrended - Fluctuation Analysis i.e. the root mean square deviation from the fitted trend of the - breath-to-breath intervals. Will only be computed if mora than 160 breath cycles in the - signal. - * ``"RRV_DFA_alpha2"``: the long-term fluctuation value. Will only be computed if mora - than 640 breath cycles in the signal. + .. codebookadd:: + RRV_SDBB|The standard deviation of the breath-to-breath intervals. + RRV_RMSSD|The root mean square of successive differences of the breath-to-breath intervals. + RRV_SDSD|The standard deviation of the successive differences between adjacent \ + breath-to-breath intervals. + RRV_BBx|The number of successive interval differences that are greater than x seconds. + RRV_pBBx|the proportion of breath-to-breath intervals that are greater than x seconds, \ + out of the total number of intervals. + RRV_VLF|Spectral power density pertaining to very low frequency band (i.e., 0 to\ + .04 Hz) by default. + RRV_LF|Spectral power density pertaining to low frequency band (i.e., .04 to \ + .15 Hz) by default. + RRV_HF|Spectral power density pertaining to high frequency band (i.e., .15 to \ + .4 Hz) by default. + RRV_LFHF|The ratio of low frequency power to high frequency power. + RRV_LFn|The normalized low frequency, obtained by dividing the low frequency power by \ + the total power. + RRV_HFn|The normalized high frequency, obtained by dividing the low frequency power by \ + total power. + RRV_SD1|SD1 is a measure of the spread of breath-to-breath intervals on the Poincaré \ + plot perpendicular to the line of identity. It is an index of short-term variability. + RRV_SD2|SD2 is a measure of the spread of breath-to-breath intervals on the Poincaré \ + plot along the line of identity. It is an index of long-term variability. + RRV_SD2SD1|The ratio between short and long term fluctuations of the breath-to-breath \ + intervals (SD2 divided by SD1). + RRV_DFA_alpha1|The "short-term" fluctuation value generated from Detrended Fluctuation \ + Analysis i.e. the root mean square deviation from the fitted trend of the \ + breath-to-breath intervals. Will only be computed if mora than 160 breath cycles \ + in the signal. + RRV_DFA_alpha2|The long-term fluctuation value. Will only be computed if mora than \ + 640 breath cycles in the signal. + RRV_ApEn|The approximate entropy of RRV, calculated by :func:`.entropy_approximate`. + RRV_SampEn|The sample entropy of RRV, calculated by :func:`.entropy_sample`. + * **MFDFA indices**: Indices related to the :func:`multifractal spectrum <.fractal_dfa()>`.