Merge branch 'develop' into Test-app_designer-display

Author: 4gwe

doc/PsPM.bib

@@ -2,10 +2,10 @@
 This file contains the steps required for finalising a PsPM release. Many items at the beginning don't have to be followed sequentially. However, it is important that there aren't any revisions (commits) that implement/fix something new in the release branch, because we don't merge these branches back to trunk. Therefore, it is sensible to create the release branch after making absolutely sure that no new stuff will be implemented.
 
 - [ ] Update version number & date in
-	 - [ ] `pspm_msg`
+	 - [ ] `pspm_msg.txt`
 	 - [ ] `pspm_quit`
 	 - [ ] `pspm_ui`
-	 - [ ] `pspm.fig`: Load `pspm.fig` into MATLAB using `openfig`, update `fig.Children(9).String` and save back to `pspm.fig`
+	 - [ ] `pspm_ui_app`
 - [ ] Manual and Developers Guide: front pages
 - [ ] Make sure both manuals are updated
 - [ ] Add release notes section of the new version to manual (at the end) and release\_notes.tex
@@ -23,3 +23,5 @@ This file contains the steps required for finalising a PsPM release. Many items
 - [ ] Add release message to GitHub
 - [ ] Change release number on lab webpage (gh-pages branch)
 - [ ] Add release message to lab webpage (gh-pages branch)
+- [ ] Update `PsPM_installer` in `/src/helper` with the new version number and download link, and merge this pull request on the official release date.
+

doc/PsPM_Developers_Guide.lyx

@@ -188,7 +188,7 @@
 while strncmp(curr_line, '**', numel('**'))
   if contains(curr_line, 'DATE')
     colon_idx = strfind(curr_line, ':');
-    date_part = curr_line(colon_idx + 1 : end);
+    date_part = curr_line(colon_idx(1) + 1 : end);
     date_fmt = 'eee MMM d HH:mm:ss yyyy';
     date = datetime(date_part, 'InputFormat', date_fmt);
     file_info.record_date = sprintf('%.2d.%.2d.%.2d', date.Day, date.Month, date.Year);
@@ -364,6 +364,7 @@
 function chan_info = parse_session_headers(messages)
 prev_n_messages = 0;
 pupil_str = sprintf('PUPIL\t');
+global  settings;
 for sess_idx = 1:numel(messages)
   i = 1;
   while true
@@ -387,7 +388,12 @@
       parts = split(msg);
       chan_info{sess_idx}.track_mode = parts{4};
       chan_info{sess_idx}.sr = str2num(parts{5});
-      chan_info{sess_idx}.eyesObserved = parts{8};
+      chan_info{sess_idx}.eyesObserved = parts{end};
+      if ~any(structfun( @(x) strcmpi(chan_info{sess_idx}.eyesObserved  , x), settings.eye.cap ) )
+         warning(['Parsing Error: The value for "eyesObserved"' ...
+             ' must be ''R'', ''L'', ''RL'', or ''LR''.']);
+      end
+
     elseif contains(msg, pupil_str)
       parts = split(msg);
       chan_info{sess_idx}.diam_vals = lower(parts{2});

doc/PsPM_Developers_Guide.pdf

@@ -1,20 +1,22 @@
 function [gx,dgdx,dgdPhi] = g_SCR(Xt,Phi,ut,inG)
-% ● Description
-%   TBA.
+% ● Description 
+%   This is the SCR observation function required by the VBA toolbox. It 
+%   adds the three generative processes (phasic SCR, SF, SCL) modelled in
+%   f_SCR.
 % ● Arguments
-%     Xt:
-%    Phi:
-%     ut:
-%    inG:
+%     Xt: a 7-element vector
+%    Phi: input required by VBA, ignored
+%     ut: input required by VBA, ignored
+%    inG: input required by VBA, ignored
 % ● History
 %   Introduced in PsPM 3.0
 %   Written in 2008-2015 by Dominik R Bach (Wellcome Trust Centre for Neuroimaging)
 
 global settings;
-if isempty(settings), pspm_init; end;
+if isempty(settings), pspm_init; end
 gx = Xt(1) + Xt(4) + Xt(7);
 dgdx = zeros(size(Xt,1),1);
 dgdx([1;4;7]) = 1;
 dgdPhi = [];
-if any(isnan(gx)|isinf(gx)), keyboard; end;
-if any(isnan(dgdx)|isinf(dgdx)), keyboard; end;
+if any(isnan(gx)|isinf(gx)), keyboard; end
+if any(isnan(dgdx)|isinf(dgdx)), keyboard; end

doc/PsPM_Manual.lyx

@@ -0,0 +1,112 @@
+% This is a convenience PsPM installer. As an alternative, download the
+% lastest release from https://github.com/bachlab/PsPM, or clone the
+% develop branch.
+% Uzay Gökay & Dominik Bach, 2025
+
+fprintf('Welcome to the PsPM installer.\n');
+[indx,tf] = listdlg('ListString',{'Latest PsPM release', 'GLM tutorial dataset', 'DCM tutorial dataset'}, ...
+    'PromptString', 'Select items to install.');
+
+if tf == 0
+    fprintf('PsPM installation aborted.\n');
+    return;
+end
+
+fprintf('Please select the parent directory for your PsPM installation.\n');
+destinationFolder = uigetdir('','Select parent directory for your PsPM installation');
+
+% -------------------------------------------------------------------------
+
+if ismember(1, indx)
+
+    % GitHub release URL for PsPM and the desired version
+    githubReleaseURL = 'https://github.com/bachlab/PsPM/releases/download'; 
+    version = 'v7.0.0';
+    packageName = 'PsPM_v7.0.0';
+
+    % Create the destination folder if it does not exist
+    if ~exist(destinationFolder, 'dir')
+        mkdir(destinationFolder);
+    end
+
+    % Construct the full URL for the specified version and platform (assuming Windows)
+    matlabPackageURL = sprintf('%s/%s/%s.zip', githubReleaseURL, version, packageName);
+
+    % Download the PsPM package
+    disp(['Downloading PsPM version ' version '...']);
+    websave('temp_package.zip', matlabPackageURL);
+
+    % Unzip the contents to the destination folder
+    disp('Unzipping package...');
+    unzip('temp_package.zip', destinationFolder);
+
+    % Clean up: delete the temporary ZIP file
+    delete('temp_package.zip');
+
+    disp(['PsPM package ' version ' download and unzip completed.']);
+    
+    %%%%%%%%%%%%%%%%%% add path %%%%%%%%%%%%%%%%%%%%%%%%%%
+    % Add the unzipped PsPM files to the MATLAB search path
+    addpath(fullfile(destinationFolder, packageName));
+
+    disp('PsPM added to MATLAB search path.');
+end
+
+
+%%%%%%%%%%% GLM dataset %%%%%%%%%%%%%%
+if ismember(2, indx)
+    % URL for the PsPM GLM tutorial dataset
+    glmTutorialDatasetURL = 'https://github.com/bachlab/PsPM-tutorial-datasets/releases/download/tutorial-datasets/Tutorial_dataset_GLM.zip';
+    glmTutorialDatasetName = 'Tutorial_dataset_GLM';
+
+    % Destination folder for the tutorial dataset
+    tutorialDestinationFolder = fullfile(destinationFolder, glmTutorialDatasetName);
+
+    % Create the destination folder if it does not exist
+    if ~exist(tutorialDestinationFolder, 'dir')
+        mkdir(tutorialDestinationFolder);
+    end
+
+    % Download the PsPM tutorial dataset
+    disp('Downloading GLM tutorial dataset...');
+    websave('temp_tutorial_dataset.zip', glmTutorialDatasetURL);
+
+    % Unzip the tutorial dataset to the destination folder
+    disp('Unzipping GLM tutorial dataset...');
+    unzip('temp_tutorial_dataset.zip', tutorialDestinationFolder);
+
+    % Clean up: delete the temporary ZIP file
+    delete('temp_tutorial_dataset.zip');
+
+    disp('GLM tutorial dataset download and unzip completed.');
+end
+
+%%%%%%%%%%%%%%% DCM Dataset %%%%%%%%%%%%%%%
+if ismember(3, indx)
+    % URL for the PsPM DCM tutorial dataset
+    dcmTutorialDatasetURL = 'https://github.com/bachlab/PsPM-tutorial-datasets/releases/download/tutorial-datasets/Tutorial_dataset_DCM.zip';
+    dcmTutorialDatasetName = 'Tutorial_dataset_DCM';
+
+    % Destination folder for the DCM tutorial dataset
+    dcmTutorialDestinationFolder = fullfile(destinationFolder, dcmTutorialDatasetName);
+
+    % Create the destination folder if it does not exist
+    if ~exist(dcmTutorialDestinationFolder, 'dir')
+        mkdir(dcmTutorialDestinationFolder);
+    end
+
+    % Download the PsPM DCM tutorial dataset
+    disp('Downloading DCM tutorial dataset...');
+    websave('temp_dcm_tutorial_dataset.zip', dcmTutorialDatasetURL);
+
+    % Unzip the DCM tutorial dataset to the destination folder
+    disp('Unzipping DCM tutorial dataset...');
+    unzip('temp_dcm_tutorial_dataset.zip', dcmTutorialDestinationFolder);
+
+    % Clean up: delete the temporary ZIP file
+    delete('temp_dcm_tutorial_dataset.zip');
+
+    disp('DCM tutorial dataset download and unzip completed.');
+
+end
+

doc/PsPM_Manual.pdf

@@ -6,7 +6,7 @@
 %   [bs, x] = pspm_bf_hprf_fc([TD, D, soa])
 % ● Arguments
 %   *    td : time resolution in second.
-%   *     d : number of derivatives. Default as 0.
+%   *     d : number of derivatives. Default is 1.
 % ● History
 %   Introduced in PsPM 3.0
 %   Written in 2015 by Tobias Moser (University of Zurich)
@@ -21,7 +21,7 @@
 end
 td = varargin{1}(1);
 if numel(varargin{1}) == 1 && nargin == 1
-  d = 0;
+  d = 1;
   soa = 3.5;
 else
   if numel(varargin) > 1
@@ -32,7 +32,7 @@
   if numel(va) > 1
     d = va(2);
   else
-    d = 0;
+    d = 1;
   end
   if numel(va) > 2
     soa = va(3);

doc/PsPM_References.lyx doc/PsPM_options_documentation.lyx

@@ -1,15 +1,17 @@
 function [bs, x] = pspm_bf_hprf_rew(td)
 % ● Description
 %   This function implements a canonical gamma response function for
-%   reward-conditioned heart period responses.
+%   reward-conditioned heart period responses, based on exps 1-2 in Xia*, 
+%   Liu*, et al. (2024).
 % ● Format
 %   [bs, x] = pspm_bf_hprf_fc(TD)
 % ● Arguments
 %   *    td : time resolution in second.
 % ● References:
 %   GLM for reward-conditioned bradycardia:
-%   Xia Y, Liu H, Kälin OK, Gerster S, Bach DR (under review). Measuring
+%   Xia Y, Liu H, Kälin OK, Gerster S, Bach DR (2024). Measuring
 %   human Pavlovian appetitive conditioning and memory retention.
+%   Pre-print.
 % ● History
 %   Introduced in PsPM 7.0
 %   Written in 2021 by Oliver Keats Kälin and Yanfang Xia (University of Zurich)
@@ -28,7 +30,8 @@
 % default values
 duration = 30;
 % k, theta, c, t0
-p_cs = [1.716239999852250e+02,0.140004209328788,60.095121886556230,-17.607312178043863];
+% p_cs = [1.716239999852250e+02,0.140004209328788,60.095121886556230,-17.607312178043863]; % generated from REW1 data
+p_cs = [73.9977984802746, 0.210014413426350, 71.1984486930105, -9.19655727625912]; % generated from the combined data set of REW1 and REW2
 
 x = (0:td:duration-td)';
 bs = zeros(numel(x), 1);
@@ -51,3 +54,6 @@
 elseif t0 < 0
     bs(1:sto, 1) = g_cs(sta:end);
 end
+
+% normalise
+bs = bs/max(bs);

doc/PsPM_References.pdf doc/PsPM_options_documentation.pdf

@@ -10,8 +10,7 @@
 % ● Arguments
 %   *    td : time resolution in second.
 %   *     n : duration of the function in s. Default as 20 s.
-%   * offset: offset in s. tells the function where to start with
-%             the response function. Default as 0.2 s.
+%   * offset: offset of the response function (in s).
 %   *     a : shape of the function.
 %   *     b : scale of the function.
 %   *     A : quantifier or amplitude of the function

doc/PsPM_release_checklist.md

@@ -10,8 +10,7 @@
 % ● Arguments
 %   *     td : Time resolution in second.
 %   *      n : Duration of the function in second. Default as 20 s.
-%   * offset : Offset in s. tells the function where to start with
-%              the response function. Default as 0.2 s.
+%   * offset : Offset of the response (in s).
 %   *      a : Shape of the function.
 %   *      b : Scale of the function.
 %   *      A : Quantifier or amplitude of the function.

doc/release_notes.pdf

@@ -7,8 +7,8 @@
 % ● Arguments
 %   *      td:  The time the response function should have.
 %   * bf_type:  Which type of response function should be generated. Can be either 1 or 2.
-%               If 1, first type response function is generated, (default) = gamma_early + gamma_late.
-%               If 2, second type response function is generated, (default) = gamma_early + gamma_early'.
+%               If 1, first type response function is generated (default)                     : gamma_early + gamma_late.
+%               If 2, second type response function is generated (recommended for longer SOAs): gamma_early + gamma_early'.
 % ● History
 %   Introduced in PsPM 3.1
 %   Written in 2016 by G Castegnetti, Tobias Moser (University of Zurich)

doc/release_notes.tex

@@ -1,18 +1,17 @@
 function [bs, x] = pspm_bf_spsrf_box(varargin)
 % ● Description
 %   pspm_bf_spsrf_box constructs a boxcar function to produce the averaged
-%   scanpath speed over a 2-s time window in the end of SOA, which equals
-%   to scanpath length over a 2-s time window divided by 2/s
+%   scanpath speed over a 2-s time window in the end of SOA. This equals
+%   to scanpath length over a 2-s time window divided by 2.
 % ● Format
 %   [bs, x] = pspm_bf_spsrf_box(td, soa)
 %   [bs, x] = pspm_bf_spsrf_box([td, soa])
 % ● Arguments
 %   *    td : time resolution in second.
 % ● References
-%   Xia Y, Melinscak F, Bach DR (2020)
-%   Saccadic Scanpath Length: An Index for Human Threat Conditioning
-%   Behavioral Research Methods 53, pages 1426–1439 (2021)
-%   doi: 10.3758/s13428-020-01490-5
+%   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 4.0
 

src/Import/eyelink/import_eyelink.m

@@ -12,9 +12,7 @@
 channel_action   = pspm_cfg_selector_channel_action;
 
 %% Specific items
-marker_chan.help    = {['Choose any number of marker channel numbers ',...
-                           'to combine. If 0, all marker ',...
-                           'channels in the file are combined.']};
+marker_chan.help    = pspm_cfg_help_format('pspm_combine_markerchannels', 'options.marker_chan_num');
 
 %% Executable branch
 combine_markerchannels        = cfg_exbranch;

src/g_SCR.m

@@ -11,9 +11,11 @@
 cfg.name   = 'Data Preprocessing';
 cfg.tag    = 'data_preprocessing';
 cfg.values = {pspm_cfg_scr_pp,...
-    pspm_cfg_pp_cardiac, ...
-    pspm_cfg_resp_pp, ...
     pspm_cfg_pp_pupil, ...
-    pspm_cfg_pp_emg};
+    pspm_cfg_pp_cardiac, ...
+    pspm_cfg_resp_pp, ...    
+    pspm_cfg_pp_emg, ...
+    pspm_cfg_combine_markerchannels, ...
+    pspm_cfg_pp_general};
 cfg.forcestruct = true;
 cfg.help   = {'Help: Data preprocessing'};

src/helper/PsPM_installer.m

@@ -16,7 +16,7 @@
 timingfile.tag     = 'timingfile';
 timingfile.num     = [1 1];
 timingfile.filter  = '.*\.(mat|MAT)$';
-timingfile.help    = {'See general help for this item for more information on how to specify timings'};
+timingfile.help    = {'See general DCM help for more information on how to specify timings'};
 
 
 name         = cfg_entry;
@@ -44,7 +44,7 @@
 timing_man_rep.tag    = 'timing_man_rep';
 timing_man_rep.values = {timing_man};
 timing_man_rep.num   = [1 Inf];
-timing_man_rep.help   = {'See general help for this item for more information on how to specify timings'};
+timing_man_rep.help   = {'See general DCM help for more information on how to specify timings'};
 
 
 timing        = cfg_choice;