update function reference files

bachlab · Feb 1, 2025 · 2260cb2 · 2260cb2
1 parent 2f3dad1
commit 2260cb2
Show file tree

Hide file tree

Showing 33 changed files with 119 additions and 71 deletions.
diff --git a/_posts/ref/2024-01-01-pspm_combine_markerchannels.md b/_posts/ref/2024-01-01-pspm_combine_markerchannels.md
@@ -3,7 +3,7 @@ layout: post
 title: pspm_combine_markerchannels
 permalink: /ref/pspm_combine_markerchannels
 ---
-
+ 
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -29,4 +29,5 @@ This allows for example creating GLM timing definitions based on markers distrib
 | options.channel_action | Accepted values: 'add'/'replace' Defines whether the new channel should be added on top of combined marker channels ('add'), or all combined marker channels should be deleted and replaced with the one new channel ('replace'). If the first option is used, then use marker channel indexing in further processing which by default takes the first marker channel as input. |
 | options.marker_chan_num | Choose any number of marker channel numbers to combine. If 0 all marker channels are used [default: use all channels]. |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_convert_area2diameter.md b/_posts/ref/2024-01-01-pspm_convert_area2diameter.md
@@ -3,7 +3,7 @@ layout: post
 title: pspm_convert_area2diameter
 permalink: /ref/pspm_convert_area2diameter
 ---
-
+ 
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -29,4 +29,5 @@ All pupil size models in PsPM are defined for diameter values and require this c
 | options.channel | [optional][numeric/string] [Default: 'both'] Channel ID to be preprocessed. To process both eyes, use 'both', which will work on 'pupil_r' and 'pupil_l'. To process a specific eye, use 'pupil_l' or 'pupil_r'. To process the combined left and right eye, use 'pupil_c'. The identifier 'pupil' will use the first existing option out of the following: (1) L-R-combined pupil; (2) non-lateralised pupil; (3) best eye pupil; (4) any pupil channel. ; If there are multiple channels of the specified type, only last one will be processed. You can also specify the number of a channel. |
 | options.channel_action | ['add'/'replace', default as 'add'] Defines whether the new channel should be added or the previous outputs of this function should be replaced. |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_convert_au2unit.md b/_posts/ref/2024-01-01-pspm_convert_au2unit.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_convert_au2unit
 permalink: /ref/pspm_convert_au2unit
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -46,4 +45,5 @@ Using the given variables, the following calculations are performed: 0. Take squ
 | options.channel | [optional][numeric/string] [Default: 'both'] Channel ID to be preprocessed. To process both eyes, use 'both', which will work on 'pupil_r' and 'pupil_l'. To process a specific eye, use 'pupil_l' or 'pupil_r'. To process the combined left and right eye, use 'pupil_c'. The identifier 'pupil' will use the first existing option out of the following: (1) L-R-combined pupil; (2) non-lateralised pupil; (3) best eye pupil; (4) any pupil channel. If there are multiple channels of the specified type, only last one will be processed. You can also specify the number of a channel. |
 | options.channel_action | ['add'/'replace', default as 'add'] Defines whether the new channel should be added or the previous outputs of this function should be replaced. |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_convert_ecg2hb.md b/_posts/ref/2024-01-01-pspm_convert_ecg2hb.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_convert_ecg2hb
 permalink: /ref/pspm_convert_ecg2hb
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -31,4 +30,5 @@ pspm_convert_ecg2hb identifies the position of QRS complexes in ECG data and wri
 | options.twthresh | Sets the threshold to perform the twave check. [def. 0.36s]. |
 | options.channel_action | ['add'/'replace', default as 'replace'] Defines whether the new channel should be added or the previous outputs of this function should be replaced. |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_convert_ecg2hb_amri.md b/_posts/ref/2024-01-01-pspm_convert_ecg2hb_amri.md
@@ -3,7 +3,7 @@ layout: post
 title: pspm_convert_ecg2hb_amri
 permalink: /ref/pspm_convert_ecg2hb_amri
 ---
-
+ 
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -33,6 +33,7 @@ pspm_convert_ecg2hb_amri performs R-peak detection from an ECG signal using the
 | options.min_relative_amplitude | [numeric, default as 0.4] Minimum relative peak amplitude of a candidate R-peak such that it is classified as an R-peak. |
 | options.channel_action | ['add'/'replace'] Defines whether corrected data should be added or the corresponding preprocessed channel should be replaced. Note that 'replace' mode does not replace the raw data channel, but a previously stored heartbeat channel. Default as 'replace'. |
 
+
 ## Outputs
 
 | Variable | Definition |

diff --git a/_posts/ref/2024-01-01-pspm_convert_gaze.md b/_posts/ref/2024-01-01-pspm_convert_gaze.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_convert_gaze
 permalink: /ref/pspm_convert_gaze
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -34,4 +33,5 @@ Display width and height are required for conversion from pixels to relate the s
 | options.channel | gaze x and y channels to work on. This can be a pair of channel numbers, any pair of channel types, 'gaze', which will search gaze_x and gaze_y channel according to the precedence order specified in pspm_load_channel. Default is 'gaze'. |
 | options.channel_action | Channel action for sps data, add / replace existing sps data (default: add). |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_convert_hb2hp.md b/_posts/ref/2024-01-01-pspm_convert_hb2hp.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_convert_hb2hp
 permalink: /ref/pspm_convert_hb2hp
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -30,4 +29,5 @@ pspm_convert_hb2hp transforms heart beat data into an interpolated heart rate si
 | options.upper | [numeric] Specifies the upper limit of the heart periods in seconds. Default is 2. |
 | options.lower | [numeric] Specifies the lower limit of the heart periods in seconds. Default is 0.2. |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_convert_ppg2hb.md b/_posts/ref/2024-01-01-pspm_convert_ppg2hb.md
@@ -3,15 +3,14 @@ layout: post
 title: pspm_convert_ppg2hb
 permalink: /ref/pspm_convert_ppg2hb
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
 
 pspm_convert_ppg2hb converts a pulse oxymeter channel to heartbeats.
 
-First a template is generated from non-ambiguous heartbeats. The ppg signal is then cross-correlated with the template and maxima are identified as heartbeats.
+Two methods are available: (1) Template-matching algorithm (method "classic"): First a template is generated from non-ambiguous heartbeats. The ppg signal is then cross-correlated with the template and maxima are identified as heartbeats. (2) HeartPy (see reference [1], requires Python installation. 
 
 
 ## Format
@@ -33,4 +32,11 @@ First a template is generated from non-ambiguous heartbeats. The ppg signal is t
 | options.lsm | [integer] for method 'classic' large spikes mode compensates for large spikes while generating template by removing the [integer] largest percentile of spikes from consideration. |
 | options.python_path | [char] for method 'heartpy' The path where python can be found. Mandatory if python environment is not yet set up. |
 
+
+## References
+
+[1] van Gent, P, Farah, H, van Nes, N, & van Arem, B. (2019) Heartpy:  A novel heart rate algorithm for the analysis of noisy signals.  Transportation Research Part F: Traffic Psychology and Behaviour 66,  368–378. 
+
+
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_dcm.md b/_posts/ref/2024-01-01-pspm_dcm.md
@@ -3,7 +3,7 @@ layout: post
 title: pspm_dcm
 permalink: /ref/pspm_dcm
 ---
-
+ 
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -62,6 +62,7 @@ For each session, experimental timing is defined by providing a 1-column vector
 | options.trlnames | Cell array of names for individual trials. This is only for housekeeping (e.g. condition descriptions), not for model estimation. Default: no trial names. |
 | options.eventnames | Cell array of names for individual events, in the order they are specified in the model.timing array - to be used for display and export only. |
 
+
 ## References
 
 [1] Model development: Bach DR, Daunizeau J, Friston KJ, Dolan RJ (2010). Dynamic causal modelling of anticipatory skin conductance changes. Biological Psychology, 85(1), 163-70

diff --git a/_posts/ref/2024-01-01-pspm_emg_pp.md b/_posts/ref/2024-01-01-pspm_emg_pp.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_emg_pp
 permalink: /ref/pspm_emg_pp
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -35,6 +34,7 @@ While the input data must be an EMG channel, the output channel will be of type
 | options.channel | [numeric/string] Channel to be preprocessed. Can be a channel ID or a channel name. Default is 'emg' (i.e. last EMG channel). |
 | options.channel_action | ['add'/'replace'] Defines whether the new channel should be added or the previous outputs of this function should be replaced. (Default: 'replace'). |
 
+
 ## References
 
 [1] Khemka S, Tzovara A, Gerster S, Quednow BB, Bach DR (2017). Modelling startle eye blink electromyogram to assess fear learning. Psychophysiology, 54, 202-214.

diff --git a/_posts/ref/2024-01-01-pspm_expand_epochs.md b/_posts/ref/2024-01-01-pspm_expand_epochs.md
@@ -0,0 +1,37 @@
+---
+layout: post
+title: pspm_expand_epochs
+permalink: /ref/pspm_expand_epochs
+---
+
+[Back to index](/PsPM/ref/)
+
+## Description
+
+pspm_expand_epochs expands epochs in time, and merges overlapping epochs. 
+
+This is useful in processing missing data epochs. The function can take a missing epochs file and creates a new file with the original name prepended with 'e', a matrix of missing epochs, or a PsPM data file with missing data in a given channel.
+
+
+## Format
+
+`[sts, output_file] = pspm_expand_epochs(epochs_fn, expansion, options)` or
+`[sts, expanded_epochs] = pspm_expand_epochs(epochs, expansion, options) ` or
+`[sts, channel_index] = pspm_expand_epochs(data_fn, channel, expansion , options)`
+
+
+## Arguments
+
+| Variable | Definition |
+|:--|:--|
+| epochs_fn | An epochs file as defined in pspm_get_timing. |
+| epochs | A 2-column matrix with epochs onsets and offsets in seconds. |
+| data_fn | A PsPM data file. |
+| channel | Channel identifier accepted by pspm_load_channel. |
+| expansion | A 2-element vector with positive numbers [pre, post]. |
+| options | See following fields. |
+| options.overwrite | Define if already existing files should be overwritten. Default ist 2. (Only used if input is epochs file.). |
+| options.channel_action | Channel action, add / replace existing data data (default: add). |
+
+
+[Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_export.md b/_posts/ref/2024-01-01-pspm_export.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_export
 permalink: /ref/pspm_export
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -30,4 +29,5 @@ The output is organised as a matrix with rows for observations (first-level mode
 | options.delim | [optional, default is tab('\t')] delimiter for output file. |
 | options.exclude_missing | [optional, default as 0] Exclude parameters from conditions with too many NaN values. This option can only be used for GLM files when exclude_missing was set during model setup. Otherwise this argument is ignored. |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_extract_segments.md b/_posts/ref/2024-01-01-pspm_extract_segments.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_extract_segments
 permalink: /ref/pspm_extract_segments
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -47,4 +46,5 @@ The output can also be written to a matlab file.
 | options.nan_output | ['screen', filename, or 'none'] Output NaN ratios of the trials for each condition. Values can be printed on the screen or written to a matlab file. Default is no NaN output. |
 | options.norm | If 1, z-scores the entire data time series (default: 0). |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_find_sounds.md b/_posts/ref/2024-01-01-pspm_find_sounds.md
@@ -3,9 +3,7 @@ layout: post
 title: pspm_find_sounds
 permalink: /ref/pspm_find_sounds
 ---
-
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -39,4 +37,5 @@ A sound is detected as event if it is longer than 10 ms, and events are recogniz
 | options.marker_chan_num | [integer] number of a channel holding markers. By default first 'marker' channel. |
 | options.expectedSoundCount | [integer] Checks for correct number of detected sounds. If too few are found, lowers threshold until at least specified count is reached. Threshold is lowered by .01 until 0.05 is reached for a max of 95 iterations. This is a EXPERIMENTAL variable, use with caution!. |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_find_valid_fixations.md b/_posts/ref/2024-01-01-pspm_find_valid_fixations.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_find_valid_fixations
 permalink: /ref/pspm_find_valid_fixations
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -43,6 +42,7 @@ By default, screen centre is assumed as fixation point. If an explicit fixation
 | options.add_invalid | [0/1] If this option is enabled, an extra channel will be written containing information about the valid samples. Data points equal to 1 correspond to invalid fixation. Default is not to add this channel. |
 | options.channel | Choose channels in which the data should be set to NaN during invalid fixations. This can be a channel number, any channel type including 'pupil' (which will select a channel according to the precedence order specified in pspm_load_channel), or 'both', which will work on 'pupil_r' and 'pupil_l' and then update channel statistics and best eye. The selected channel must be an eyetracker channel, and the file must contain the corresponding gaze channel(s) in the correct units: distance units for mode "fixation" and distance or pixel units for mode "bitmap". Default is 'pupil'. |
 
+
 ## References
 
 [1] Korn CW & Bach DR (2016). A solid frame for the window on cognition: Modelling event-related pupil responses. Journal of Vision, 16:28,1-6.

diff --git a/_posts/ref/2024-01-01-pspm_gaze_pp.md b/_posts/ref/2024-01-01-pspm_gaze_pp.md
@@ -3,9 +3,7 @@ layout: post
 title: pspm_gaze_pp
 permalink: /ref/pspm_gaze_pp
 ---
-
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -28,4 +26,5 @@ pspm_gaze_pp combines left/right gaze x and gaze y channels at the same time and
 | options.channel | gaze_x_r/gaze_x_l/gaze_y_r/gaze_y_l channels to work on. This can be a 4-element vector of channel numbers, or 'gaze', which will use the last channel of the types specified above. Default is 'gaze'. |
 | options.channel_action | 'replace' existing gaze_x_c and gaze_y_c channels, or 'add' new ones (default). |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_get_markerinfo.md b/_posts/ref/2024-01-01-pspm_get_markerinfo.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_get_markerinfo
 permalink: /ref/pspm_get_markerinfo
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -27,4 +26,5 @@ pspm_get_markerinfo extracts markerinfo from PsPM files that contain such inform
 | options.filename | [char] name of a file to write the markerinfo to; default value: empty, meaning no file will be written. |
 | options.overwrite | [logical] (0 or 1) Define whether to overwrite existing output files or not. Default value: determined by pspm_overwrite. |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_glm.md b/_posts/ref/2024-01-01-pspm_glm.md
@@ -3,7 +3,7 @@ layout: post
 title: pspm_glm
 permalink: /ref/pspm_glm
 ---
-
+ 
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -45,6 +45,7 @@ The user specifies events for different conditions. These are used to estimate t
 | options.marker_chan_num | [optional] marker channel number; default first marker channel. |
 | options.exclude_missing | [optional] marks trials during which NaN percentage exceeds a cutoff value. Requires two subfields: 'segment_length' (in s after onset) and 'cutoff' (in % NaN per segment). Results are written into model structure as fields .stats_missing and .stats_exclude but not used further. |
 
+
 ## Outputs
 
 | Variable | Definition |

diff --git a/_posts/ref/2024-01-01-pspm_import.md b/_posts/ref/2024-01-01-pspm_import.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_import
 permalink: /ref/pspm_import
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -36,4 +35,5 @@ pspm_import imports data from various formats and writes them to a PsPM file on
 | options | See following fields. |
 | options.overwrite | overwrite existing files by default. [logical] (0 or 1) Define whether to overwrite existing output files or not. Default value: determined by pspm_overwrite. |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_interpolate.md b/_posts/ref/2024-01-01-pspm_interpolate.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_interpolate
 permalink: /ref/pspm_interpolate
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -31,4 +30,5 @@ pspm_interpolate interpolates NaN values. It either acts on one selected channel
 | options.overwrite | Defines if existing datafiles should be overwritten. [logical] (0 or 1) Define whether to overwrite existing output files or not. Default value: do not overwrite. Only used if 'channel' is 'all'. |
 | options.channel_action | Defines whether the interpolated data should be added or the corresponding channel should be replaced. [optional; accept: 'add', 'replace'; default: 'add'] Only used if 'channel' is not 'all'. |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_merge.md b/_posts/ref/2024-01-01-pspm_merge.md
@@ -3,8 +3,7 @@ layout: post
 title: pspm_merge
 permalink: /ref/pspm_merge
 ---
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -28,4 +27,5 @@ pspm_merge merges two PsPM datafiles recorded in an overlapping time interval by
 | options.overwrite | overwrite existing file by default [logical] (0 or 1) Default value: determined by pspm_overwrite. |
 | options.marker_chan_num | 2-element vector of marker channel numbers to be used as a reference. Ignored if reference is specified as 'file'. If undefined or 0, the first marker channel of either file is used. |
 
+
 [Back to index](/PsPM/ref/)
diff --git a/_posts/ref/2024-01-01-pspm_pp.md b/_posts/ref/2024-01-01-pspm_pp.md
@@ -3,9 +3,7 @@ layout: post
 title: pspm_pp
 permalink: /ref/pspm_pp
 ---
-
-
-
+
 [Back to index](/PsPM/ref/)
 
 ## Description
@@ -39,4 +37,5 @@ pspm_pp contains various preprocessing/filtering utilities for reducing noise in
 | options | See following fields. |
 | options.channel_action | [optional][string][Accepts: 'add'/'replace'][Default: 'add'] Defines whether corrected data should be added or the corresponding preprocessed channel should be replaced. |
 
+
 [Back to index](/PsPM/ref/)