update references in help texts

src/pspm_convert_ecg2hb.m

@@ -33,12 +33,25 @@
 %   │                 [def. 0.36s].
 %   └.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.
+%
 % ● Output
 %      channel_index: index of channel containing the processed data
 %      quality_info:  generated if options.debugmode == 1
+%
 % ● Reference
-%   Pan J & Tomkins WJ (1985). A Real-Time QRS Detection Algorithm. IEEE
-%   Transactions on Biomedical Engineering, 32, 230-236.
+%   [1] Adjusted algorithm:
+%       Paulus PC, Castegnetti G, & Bach DR (2016). Modeling event-related 
+%       heart period responses. Psychophysiology, 53, 837-846.
+%   [2] Original algorithm:
+%       Pan J & Tomkins WJ (1985). A Real-Time QRS Detection Algorithm. IEEE
+%       Transactions on Biomedical Engineering, 32, 230-236.
+% 
+% ● History
+%   Introduced in PsPM 3.0
+%   Written in 2013-2015 Philipp C Paulus & Dominik R Bach
+%   (Technische Universitaet Dresden, University of Zurich)
+%   Updated in 2022 Teddy Chao
 % ● Developer's Notes
 %   ▶︎ Changes from the original Pan & Tompkins algorithm
 %   filter:       P. & T. intend to achieve a pass band from 5-15 Hz with a
@@ -99,11 +112,6 @@
 %
 %   R:            Vector of the same length as the raw data, containing
 %                 information on the position of the QRS complexes.
-% ● History
-%   Introduced in PsPM 3.0
-%   Written in 2013-2015 Philipp C Paulus & Dominik R Bach
-%   (Technische Universitaet Dresden, University of Zurich)
-%   Updated in 2022 Teddy Chao
 
 %% Initialise
 global settings

src/pspm_convert_ecg2hb_amri.m

@@ -70,13 +70,16 @@
 %                     does not replace the raw data channel, but a previously
 %                     stored heartbeat channel.
 %                     (Default: 'replace')
-% ● Output
+% ● Outputs
+%                sts: status marker showing whether the function works normally.
 %      channel_index: index of channel containing the processed data
+%
 % ● References
 %   [1] Liu, Zhongming, et al. "Statistical feature extraction for artifact
 %       removal from concurrent fMRI-EEG recordings." Neuroimage 59.3 (2012):
 %       2073-2087.
 %   [2] http://www.amri.ninds.nih.gov/software.html
+% 
 % ● History
 %   Written in 2019 by Eshref Yozdemir (University of Zurich)
 %   Updated in 2022 by Teddy Chao

src/pspm_convert_hb2hp.m

@@ -36,6 +36,11 @@
 %                     heart periods in seconds. Default is 0.2.
 % ● Output
 %      channel_index: index of channel containing the processed data
+% 
+% % ● Reference
+%     [1] Paulus PC, Castegnetti G, & Bach DR (2016). Modeling event-related 
+%         heart period responses. Psychophysiology, 53, 837-846.
+%  
 % ● History
 %   Introduced in PsPM 3.0
 %   Written in 2008-2015 by Dominik R Bach (Wellcome Trust Centre for Neuroimaging)

src/pspm_dcm.m

@@ -145,16 +145,20 @@
 %   the trials use much less than available amount of samples in both case
 %   (1) and (2). Instead, we aim to use as much data as possible in (1), and
 %   perform (2) only if this edge case is not present.
+% 
 % ● References
-%   1.Bach DR, Daunizeau J, Friston KJ, Dolan RJ (2010).
-%     Dynamic causal modelling of anticipatory skin conductance changes.
-%     Biological Psychology, 85(1), 163-70
-%   2.Staib, M., Castegnetti, G., & Bach, D. R. (2015).
-%     Optimising a model-based approach to inferring fear learning from
-%     skin conductance responses.
-%     Journal of Neuroscience Methods, 255, 131-138.
+%   [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
+%   [2] Model validation and improvement:
+%       Staib, M., Castegnetti, G., & Bach, D. R. (2015). Optimising a
+%       model-based approach to inferring fear learning from skin  
+%       conductance responses. Journal of Neuroscience Methods, 255, 
+%       131-138.
+%       
 % ● History
-%   Introduced in PsPM 5.1.0
+%   Introduced in PsPM 3.0
 %   Written in 2010-2021 by Dominik R Bach (Wellcome Centre for Human Neuroimaging, UCL)
 
 %% 1 Initialise

src/pspm_emg_pp.m

@@ -29,9 +29,10 @@
 % ● Output
 %      channel_index: index of channel containing the processed data
 % ● References
-%   [1] Khemka S, Tzovara A, Gerster S, Quednow BB, Bach DR (2016).
-%       Modeling Startle Eyeblink Electromyogram to Assess Fear Learning.
-%       Psychophysiology
+%   [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.
+%
 % ● History
 %   Introduced in PsPM 3.1
 %   Written in 2009-2016 by Tobias Moser (University of Zurich)

src/pspm_glm.m

@@ -94,6 +94,78 @@
 %                 .stats_exclude but not used further.
 % ● Outputs
 %           glm:  a structure 'glm' which is also written to file
+% ● References
+% 
+%   Skin conductance response analysis
+%   ---------------------------------- 
+%   [1] GLM for SCR:
+%       Bach DR, Flandin G, Friston KJ, Dolan RJ (2009). Time-series analysis for
+%       rapid event-related skin conductance responses. Journal of Neuroscience
+%       Methods, 184, 224-234.
+%   [2] Canonical skin conductance response function, and GLM assumptions:
+%       Bach DR, Flandin G, Friston KJ, Dolan RJ (2010). Modelling event-related
+%       skin conductance responses. International Journal of Psychophysiology,
+%       75, 349-356.
+%   [3] Validating GLM assumptions with intraneural recordings:
+%       Gerster S, Namer B, Elam M, Bach DR (2018). Testing a linear time 
+%       invariant model for skin conductance responses by intraneural 
+%       recording and stimulation. Psychophysiology, 55, e12986.
+%   [4] Fine-tuning of SCR CLM:
+%       Bach DR, Friston KJ, Dolan RJ (2013). An improved algorithm for
+%       model-based analysis of evoked skin conductance responses. Biological
+%       Psychology, 94, 490-497.
+%   [5] SCR GLM validation and comparison with Ledalab:
+%       Bach DR (2014).  A head-to-head comparison of SCRalyze and Ledalab, two
+%       model-based methods for skin conductance analysis. Biological Psychology,
+%       103, 63-88.
+%  
+%   Pupil size analysis
+%   -------------------
+%   [6] GLM for fear-conditioned pupil dilation:
+%       Korn CK, Staib M, Tzovara A, Castegnetti G, Bach DR (2017). 
+%       A pupil size response model to assess fear learning. 
+%       Psychophysiology, 54, 330-343.
+%   
+%   Heart rate/period analysis
+%   --------------------------
+%   [7] GLM for evoked heart period responses:
+%       Paulus PC, Castegnetti G, & Bach DR (2016). Modeling event-related 
+%       heart period responses. Psychophysiology, 53, 837-846. 
+%   [8] GLM for fear-conditioned bradycardia:
+%       Castegnetti G, Tzovara A, Staib M, Paulus PC, Hofer N, & Bach DR 
+%       (2016). Modelling fear-conditioned bradycardia in humans. 
+%       Psychophysiology, 53, 930-939.
+%   
+%   Respiration analysis
+%   --------------------
+%   [9] GLM for evoked respiratory responses:
+%       Bach DR, Gerster S, Tzovara A, Castegnetti G (2016). A linear model 
+%       for event-related respiration responses. Journal of Neuroscience 
+%       Methods, 270, 174-155.
+%  [10] GLM for fear-conditioned respiration amplitude responses
+%       Castegnetti G, Tzovara A, Staib M, Gerster S, Bach DR (2017). 
+%       Assessing fear learning via conditioned respiratory amplitude 
+%       responses. Psychophysiology, 54, 215-223.
+%   
+%   Startle eye-blink analysis
+%   --------------------------
+%  [11] GLM for startle eye-blink responses: 
+%       Khemka S, Tzovara A, Gerster S, Quednow B and Bach DR (2017)
+%       Modeling Startle Eyeblink Electromyogram to Assess
+%       Fear Learning. Psychophysiology
+%
+%   Eye gaze analysis
+%   -----------------
+%  [12] GLM for saccadic scanpath speed
+%       Xia Y, Melinščak F,  Bach DR (2020). Saccadic scanpath length: an 
+%       index for human threat conditioning. Behavior Research Methods, 53, 
+%       1426-1439.
+% 
+% ● History
+%   Introduced in PsPM 3.1
+%   Written in 2008-2016 by Dominik R Bach (Wellcome Trust Centre for Neuroimaging)
+%   Maintained in 2022 by Teddy Chao (UCL)
+%
 % ● Developer's Notes
 %   TIMING - multiple condition file(s) or struct variable(s):
 %   The structure is equivalent to SPM2/5/8/12 (www.fil.ion.ucl.ac.uk/spm),
@@ -121,30 +193,6 @@
 %     names = {'condition a', 'condition b'};
 %     onsets = {[1 2 3], [4 5 6]};
 %     save('testfile', 'names', 'onsets');
-% ● References
-%   [1] GLM for SCR:
-%       Bach DR, Flandin G, Friston KJ, Dolan RJ (2009). Time-series analysis for
-%       rapid event-related skin conductance responses. Journal of Neuroscience
-%       Methods, 184, 224-234.
-%   [2] SCR: Canonical response function, and GLM assumptions:
-%       Bach DR, Flandin G, Friston KJ, Dolan RJ (2010). Modelling event-related
-%       skin conductance responses. International Journal of Psychophysiology,
-%       75, 349-356.
-%   [3] Fine-tuning of SCR CLM:
-%       Bach DR, Friston KJ, Dolan RJ (2013). An improved algorithm for
-%       model-based analysis of evoked skin conductance responses. Biological
-%       Psychology, 94, 490-497.
-%   [4] SCR GLM validation and comparison with Ledalab:
-%       Bach DR (2014).  A head-to-head comparison of SCRalyze and Ledalab, two
-%       model-based methods for skin conductance analysis. Biological Psychology,
-%       103, 63-88.
-%   [5] SEBR GLM: Khemka S, Tzovara A, Gerster S, Quednow B and Bach DR (2017)
-%       Modeling Startle Eyeblink Electromyogram to Assess
-%       Fear Learning. Psychophysiology
-% ● History
-%   Introduced in PsPM 3.1
-%   Written in 2008-2016 by Dominik R Bach (Wellcome Trust Centre for Neuroimaging)
-%   Maintained in 2022 by Teddy Chao (UCL)
 
 %% 1 Initialise
 global settings

src/pspm_process_illuminance.m

@@ -33,6 +33,10 @@
 %                out: has same size as ldata and contains either the
 %                     processed data or contains the path to the .mat file
 %                     where the data has been stored to
+% ● References
+%   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.
+%
 % ● History
 %   Introduced In PsPM 3.1
 %   Written in 2015 by Tobias Moser, Christoph Korn (University of Zurich)

src/pspm_resp_pp.m

@@ -33,6 +33,12 @@
 %                     corresponding channel should be replaced.
 % ● Output
 %      channel_index: index of channel containing the processed data
+%
+% ● References
+%   [1] Bach DR, Gerster S, Tzovara A, Castegnetti G (2016). A linear model
+%       for event-related respiration responses. Journal of Neuroscience 
+%       Methods, 270, 174-155.
+%   
 % ● History
 %   Introduced in PsPM 3.0
 %   Written in 2015 by Dominik R Bach (Wellcome Trust Centre for Neuroimaging)

src/pspm_sf.m

@@ -52,15 +52,21 @@
 %   │                   display intermediate windows.
 %   └──.missingthresh:  [numeric] [default: 2] [unit: second]
 %                       threshold value for controlling missing epochs.
+% 
 % ● References
-%   1.[DCM for SF]
-%     Bach DR, Daunizeau J, Kuelzow N, Friston KJ, Dolan RJ (2010). Dynamic
-%     causal modelling of spontaneous fluctuations in skin conductance.
-%     Psychophysiology, 48, 252-257.
-%   2.[AUC measure]
-%     Bach DR, Friston KJ, Dolan RJ (2010). Analytic measures for the
-%     quantification of arousal from spontanaeous skin conductance
-%     fluctuations. International Journal of Psychophysiology, 76, 52-55.
+%   [1] DCM for SF:
+%       Bach DR, Daunizeau J, Kuelzow N, Friston KJ, Dolan RJ (2010). Dynamic
+%       causal modelling of spontaneous fluctuations in skin conductance.
+%       Psychophysiology, 48, 252-257.
+%   [2] MP approximation:
+%       Bach DR, Staib M (2015). A matching pursuit algorithm for inferring 
+%       tonic sympathetic arousal from spontaneous skin conductance 
+%       fluctuations. Psychophysiology, 52, 1106-12.
+%   [3] AUC for SF: 
+%       Bach DR, Friston KJ, Dolan RJ (2010). Analytic measures for the
+%       quantification of arousal from spontanaeous skin conductance
+%       fluctuations. International Journal of Psychophysiology, 76, 52-55.
+% 
 % ● Developer's Note
 %   the output also contains a field .time that contains the inversion time
 %   in ms (for DCM and MP)

src/pspm_sf_auc.m

@@ -13,6 +13,12 @@
 %   Bach DR, Friston KJ, Dolan RJ (2010). Analytic measures for the
 %   quantification of arousal from spontanaeous skin conductance
 %   fluctuations. International Journal of Psychophysiology, 76, 52-55.
+% 
+% ● References
+%   [1] Bach DR, Friston KJ, Dolan RJ (2010). Analytic measures for the
+%       quantification of arousal from spontanaeous skin conductance
+%       fluctuations. International Journal of Psychophysiology, 76, 52-55.
+% 
 % ● History
 %   Introduced In PsPM 3.0
 %   Written in 2008-2015 by Dominik R Bach (Wellcome Trust Centre for Neuroimaging)

src/pspm_sf_dcm.m

@@ -32,10 +32,12 @@
 %                  [numeric] [default: 2] [unit: second]
 %                  threshold value for controlling missing epochs,
 %                  which is originally inherited from SF
+% 
 % ● References
 %   Bach DR, Daunizeau J, Kuelzow N, Friston KJ, & Dolan RJ (2011). Dynamic
 %   causal modelling of spontaneous fluctuations in skin conductance.
 %   Psychophysiology, 48, 252-57.
+% 
 % ● History
 %   Introduced In PsPM 3.0
 %   Written in 2008-2015 by Dominik R Bach (Wellcome Trust Centre for Neuroimaging)

src/pspm_sf_mp.m

@@ -34,6 +34,10 @@
 %             false. If set to true this will add a further field 'D' to the
 %             output struct. Default is false.
 % ● References
+%   [1] Bach DR, Staib M (2015). A matching pursuit algorithm for inferring 
+%       tonic sympathetic arousal from spontaneous skin conductance 
+%       fluctuations. Psychophysiology, 52, 1106-12.
+% 
 % ● History
 %   Introduced in PsPM 3.0
 %   Written in 2008-2015 by Dominik R Bach (UZH, WTCN) last edited 18.08.2014

src/pspm_tam.m

@@ -4,29 +4,6 @@
 %   trial-averaged data. pspm_tam starts by extracting and averaging signal segments of
 %   length `model.window` from each data file individually, then averages
 %   these mean segments and finally fits an LTI model.
-% ● Developer's Notes
-%   The fitting process is a residual least square minimisation where the
-%   predicted value is calculated as following:
-%     Y_predicted = input_function (*) basis_function
-%   with (*) represents a convolution. Only parameters of the input
-%   function are optimised.
-%   ---
-%   TIMING - multiple condition file(s) or struct variable(s):
-%    The structure is equivalent to SPM2/5/8/12 (www.fil.ion.ucl.ac.uk/spm),
-%    such that SPM files can be used.
-%    The file contains the following variables:
-%    - names: a cell array of string for the names of the experimental
-%      conditions
-%    - onsets: a cell array of number vectors for the onsets of events for
-%      each experimental condition, expressed in seconds, marker numbers, or
-%      samples, as specified in timeunits
-%    - durations (optional, default 0): a cell array of vectors for the
-%      duration of each event. You need to use 'seconds' or 'samples' as time
-%      units
-%    e.g. produce a simple multiple condition file by typing
-%      names = {'condition a', 'condition b'};
-%      onsets = {[1 2 3], [4 5 6]};
-%      save('testfilcircle_degreee', 'names', 'onsets');
 % ● Arguments
 %   ┌───────model:  [struct]
 %   │ ▶︎ mandatory
@@ -99,18 +76,47 @@
 %                   Default value: determined by pspm_overwrite.
 % ● Outputs
 %   tam: a structure 'tam' which is also written to file
+% 
 % ● Reference
-%   Korn, C. W., & Bach, D. R. (2016). A solid frame for the window on
-%   cognition: Modeling event-related pupil responses. Journal of Vision,
-%   16(3), 28. https://doi.org/10.1167/16.3.28
-%   Abivardi, A., Korn, C.W., Rojkov, I. et al. Acceleration of inferred
-%   neural responses to oddball targets in an individual with bilateral
-%   amygdala lesion compared to healthy controls. Sci Rep 13, 14550 (2023).
-%   https://doi.org/10.1038/s41598-023-41357-1
+%   [1] Model development:
+%       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. https://doi.org/10.1167/16.3.28
+%   [2] Model application:
+%       Abivardi A, Korn CW, Rojkov I, Gerster S, Hurlemann R, Bach DR 
+%       (2023). Acceleration of inferred neural responses to oddball 
+%       targets in an individual with bilateral amygdala lesion compared to 
+%       healthy controls. Scientific Reports, 13, 41357.
+%       https://doi.org/10.1038/s41598-023-41357-1
+% 
 % ● History
 %   Introduced In PsPM 4.2
 %   Written in 2020 by Ivan Rojkov (University of Zurich)
 %   Maintained in 2022 by Teddy Chao (UCL)
+% ● Developer's Notes
+%   The fitting process is a residual least square minimisation where the
+%   predicted value is calculated as following:
+%     Y_predicted = input_function (*) basis_function
+%   with (*) represents a convolution. Only parameters of the input
+%   function are optimised.
+%   ---
+%   TIMING - multiple condition file(s) or struct variable(s):
+%    The structure is equivalent to SPM2/5/8/12 (www.fil.ion.ucl.ac.uk/spm),
+%    such that SPM files can be used.
+%    The file contains the following variables:
+%    - names: a cell array of string for the names of the experimental
+%      conditions
+%    - onsets: a cell array of number vectors for the onsets of events for
+%      each experimental condition, expressed in seconds, marker numbers, or
+%      samples, as specified in timeunits
+%    - durations (optional, default 0): a cell array of vectors for the
+%      duration of each event. You need to use 'seconds' or 'samples' as time
+%      units
+%    e.g. produce a simple multiple condition file by typing
+%      names = {'condition a', 'condition b'};
+%      onsets = {[1 2 3], [4 5 6]};
+%      save('testfilcircle_degreee', 'names', 'onsets');
+
 
 %% Initialise
 global settings