Add feature to export and load stim to and from BIDS events TSV files. (#147)

* v1.55.0

-- Change to stimulus loading to load from events .tsv file if it is present. It would override SNIRF stim field and StimEditGUI. If not present then default to SNIRF stim and StimEditGUI for stim loading and editing.

* v1.55.1

-- Fix some bugs with stim export to events TSV files.
-- Add documentation to DesignNotes.ppt describing the new stim loading (from events TSV files) and exporting (to events TSV files) feature.
-- Add option to Snirf2Tsv.m to find and delete all events TSV files

* v1.56.0

-- Fix issue in Snirf.GetDataTimeSeriesMatrix() with incorrect conversion to aux matrix when aux sample rate is different than data sample rate.
-- Move events TSV loading menu option from StimEditGUI.fig to MainGUI.fig per Davis's request
-- Fix bug in moving old output derived data folder homerOutput to new BIDS style derivative/homer.

* v1.56.1

-- One more bug fix in SnirfClass.GetAuxDataMatrix() where the case of if aux has same time base as data is not being handles properly.
-- Added config option "Quiet Mode" to be able to run processing without progress bars being displayed so it doesn't constantly take control of the mouse and one could work in parallel in other windows without interference.

* v1.56.2

-- Added automatic stim loading from TSV file (if changes were made or new file created) when clicking on run. 
-- Change to SnirfFile2Tsv.m: if snirf stim field is empty then generate empty TSV file with only the default column names instead not generating any file at all as was done before.
-- Change the way we detect if stim changes were made to acquisition file.
-- Minor change to readTsv.m to automatically complete input file name without an extention with a '.tsv' extension.
-- Add DeleteTsv.m for diagnostic purposes.

* v1.57.0

-- Make config changes made through Settings-->Edit App Configuration menu take effect immediately after saving so that one does not have to restart Homer3.

-- Fix bug loading stims: Change order at init time when DataTreeClass.SetConditions() is called; before or after loading groupResult.mat. This order was changed several months ago (I believe in version 1.38.2) to be SetConditions then load groupResults. The problem with this is that it groupResults then overwrites the correct condition initialization for the whole group if groupResults happened to have unsaved condition changes that differ from SetConditions. This may be inconsistent with the correct condition set generated by SetConditions. One solution could be that TreeNode.Copy() groupResults method SHOULD NOT BE copying conditions - i.e, TreeNode.CondNames field. The other solution - the one used here - is change the order back to calling SetConditions() after copying groupResults. Although I have to try to remember why that change to caLL SetConditions first was made in the first place IN v1.38.2. It seems like a mistaken solution to address some sort of issue which the commit message does not explain.

-- Clean up: delete unused and obsolete files.

* v1.58.0

-- Add back showing pruned channels in PlotProbeGUI. Also there's a new ability to display non-HRF time course in PlotProbeGUI. If user is displaying non-HRF data then a warning pops up informing about this. You can opt out of receiving with every element selection.

-- Standardized datatype names in methods GetDataTimeSeries() and GetMeasurementList(), across different levels in DataTreeClass, to be better able to use these methods in scripts.

-- Made small change to hmrR_PreprocessIntensity_Negative per Meryem's request.

-- Fix display issue in manually pruning channels with it not always being displayed correctly with a dotted line in the probe axes. This is because of lack of clarity with currently selected wavelength with only the currently selected wavelength measurement being toggled. To make things simple when selecting a channel for pruning measurements from ALL of the wavelengths are toggled simultaneously. Also to clarify, the meaning of manual pruning is always to the raw/OD timecourse data even when it is NOT selected in the Plot Select Data

-- Fix small issue in syncSubmodules when copying peerless files in non-existent folders in the destination the folder needs to be created first (that is, copyfile won't do it for you).

Author: jayd1860

AppSettings.cfg

@@ -10,5 +10,7 @@ don't ask again
 % Export HRF Mean Output Style # all child processing elements in one file, one processing element per file
 one processing element per file
 
+% Load Stim From TSV File # Yes, No
+Yes
 
 % END

DataTree/AcquiredData/AcqDataClass.m

@@ -1,5 +1,8 @@
 classdef AcqDataClass < matlab.mixin.Copyable
 
+    properties (Access = public)
+        bids
+    end
     properties (Access = private)
         logger
     end
@@ -76,19 +79,39 @@
 
     methods
 
+        % -------------------------------------------------------
+        function obj = AcqDataClass(fileobj)
+            if nargin == 0
+                return
+            end
+            if iscell(fileobj)
+                if ~isempty(fileobj)
+                    fileobj = fileobj{1};
+                end
+            end
+            if ~ischar(fileobj)
+                fileobj = '';
+            end
+            obj.LoadBids(fileobj);           
+        end
+
+
+        
         % -------------------------------------------------------
         function Initialize(obj)
             global logger
             obj.logger = InitLogger(logger);
         end
 
 
+        
         % -------------------------------------------------------
         function err = Error(obj)
             err = obj.GetError();
         end
 
 
+        
         % ---------------------------------------------------------
         function msg = GetErrorMsg(obj)
             msg = '';
@@ -106,6 +129,77 @@ function Initialize(obj)
         end
 
 
+        
+        % -------------------------------------------------------
+        function err = LoadBids(obj, fileobj)
+            err = obj.LoadStimOverride(fileobj);
+        end
+        
+
+        
+        % -------------------------------------------------------
+        function status = LoadStimOverride(obj, fileobj)
+            global cfg
+            status = false;
+            cfg = InitConfig(cfg);
+            if strcmpi(cfg.GetValue('Load Stim From TSV File'), 'no')
+                return
+            end
+            obj.bids = struct('stim',{{}});            
+            if isempty(fileobj)
+                return
+            end
+            [p,f] = fileparts(fileobj);
+            if isempty(p)
+                p = filesepStandard(pwd);
+            end
+            k = strfind(f, '_nirs');
+            if isempty(k)
+                k = length(f)+1;
+            end
+            fnameTsv = [filesepStandard(p), f(1:k-1), '_events.tsv'];
+            file = mydir(fnameTsv);
+            if isempty(file)
+                return
+            end
+            obj.bids.stim = readTsv([filesepStandard(p), file(1).name],'numstr2num');
+            if isempty(obj.bids.stim)
+                return
+            end
+            s = TsvFile2Snirf(obj.bids.stim);
+            obj.stim = s.stim.copy();
+            status = true;
+        end
+        
+        
+        
+        % -------------------------------------------------------
+        function err = ReloadStim(obj, fileobj)
+            err = 0;
+            obj.bids = struct('stim',{{}});            
+            if isempty(fileobj)
+                return
+            end
+            [p,f] = fileparts(fileobj);
+            if isempty(p)
+                p = filesepStandard(pwd);
+            end
+            k = strfind(f, '_nirs');
+            if isempty(k)
+                k = length(f)+1;
+            end
+            fnameTsv = [filesepStandard(p), f(1:k-1), '_events.tsv'];
+            file = mydir(fnameTsv);
+            if isempty(file)
+                return
+            end
+            obj.bids.stim = readTsv([filesepStandard(p), file(1).name],'numstr2num');
+            s = TsvFile2Snirf(obj.bids.stim);
+            obj.stim = s.stim.copy();
+        end
+        
+        
+        
         % -------------------------------------------------------
         function FreeMemory(obj, filename)
             if ~exist('filename','var')
@@ -118,6 +212,7 @@ function FreeMemory(obj, filename)
         end
 
 
+        
         % ---------------------------------------------------------
         function bbox = GetSdgBbox(obj)
             bbox = [];
@@ -150,6 +245,7 @@ function FreeMemory(obj, filename)
         end
 
 
+        
         % ----------------------------------------------------------------------------------
         function varval = GetVar(obj, varname)
             if ismethod(obj,['Get_', varname])
@@ -179,6 +275,7 @@ function FreeMemory(obj, filename)
         end
 
 
+        
         % ----------------------------------------------------------------------------------
         function t = GetTimeCombined(obj)
             % Function combines the time vectors for all data blocks into one time vectors. 
@@ -204,6 +301,7 @@ function FreeMemory(obj, filename)
         end
 
 
+                
         % ----------------------------------------------------------------------------------
         function data = GetStimData(~, ~)
             data = [];
@@ -250,6 +348,20 @@ function FreeMemory(obj, filename)
 
 
 
+        % ----------------------------------------------------------------------------------
+        function fnameTsv = GetStimTsvFilename(obj)
+            fnameTsv = '';
+            [pname, fname] = fileparts(obj.GetFilename());
+            k = strfind(fname, '_nirs');
+            if isempty(k)
+                k = length(fname)+1;
+            end
+            if isempty(fname)
+                return;
+            end
+            fnameTsv = [filesepStandard(pname), fname(1:k-1), '_events.tsv'];
+        end
+                
     end
 
 end

DataTree/AcquiredData/DataFiles/DeleteDataFiles.m

@@ -88,6 +88,7 @@ function DeleteDataFiles(varargin)
     if strcmp(options, 'delete')
         fprintf('Deleting %s\n', [datafiles(ii).rootdir, '/', datafiles(ii).name]);
         delete([datafiles(ii).rootdir, '/', datafiles(ii).name]);
+        delete([datafiles(ii).rootdir, '/*_events.tsv']);
     elseif strcmp(options, 'move')
         fprintf('Moving %s to %s\n', [datafiles(ii).rootdir, '/', datafiles(ii).name], [datafiles(ii).rootdir, '/', datafiles(ii).name, '.old']);
         movefile([datafiles(ii).rootdir, '/', datafiles(ii).name], [datafiles(ii).rootdir, '/', datafiles(ii).name, '.old']);

DataTree/AcquiredData/DataFiles/DeleteTsv.m

@@ -0,0 +1,7 @@
+function DeleteTsv(rootdir)
+if ~exist('rootdir','var')
+    rootdir = pwd;
+end
+rootdir = filesepStandard(rootdir);
+Snirf2Tsv(rootdir, 'remove');
+

DataTree/AcquiredData/DataFiles/Snirf2Tsv.m

@@ -0,0 +1,36 @@
+function Snirf2Tsv(rootdir, options)
+if ~exist('rootdir','var')
+    rootdir = pwd;
+end
+if ~exist('options','var')
+    options = pwd;
+end
+rootdir = filesepStandard(rootdir);
+files = DataFilesClass(rootdir, 'snirf');
+files = files.files;
+for ii = 1:length(files)
+    if files(ii).IsDir()
+        continue
+    end
+    fname = filesepStandard([files(ii).rootdir, files(ii).name]);
+    [pname, fname, ext1] = fileparts(fname);
+    k = strfind(fname, '_nirs');
+    if isempty(k)
+        k = length(fname)+1;
+    end
+    fnameNew = [filesepStandard(pname), fname(1:k-1), '_events.tsv'];
+    src = [filesepStandard(pname), fname, ext1];
+    dst = fnameNew;
+    if optionExists(options, 'delete') || optionExists(options, 'remove')
+        if ispathvalid(dst)
+            fprintf('Deleting  %s\n', dst);
+            delete(dst);
+        end
+    else
+        fprintf('Converting   %s   to   %s\n', src, dst);
+        SnirfFile2Tsv(src, dst, 'removeStim');
+    end
+end
+
+
+

DataTree/AcquiredData/DataFiles/SnirfFile2Tsv.m

@@ -0,0 +1,58 @@
+function tsv = SnirfFile2Tsv(src, dst, options)
+tsv = {};
+
+% Parse args
+if nargin==0
+    return
+end
+if ~isa(src, 'SnirfClass')
+    s = SnirfClass(src);
+else
+    s = src;
+end
+if s.IsEmpty()
+    s.LoadStim(s.GetFilename());
+end
+if ~exist('dst','var')
+    dst = '';
+end
+
+if isempty(dst)
+    dst = s.GetStimTsvFilename();
+end
+if ~exist('options','var')
+    options = '';
+end
+if isempty(s.stim)
+    s0 = StimClass();
+else
+    s0 = s.stim(1);
+end
+tsv = [s0.dataLabels(:)', 'trial_type'];
+data = [];
+for ii = 1:length(s.stim)
+    iS = size(tsv,1)+1;
+    iE = size(tsv,1)+size(s.stim(ii).data,1);
+    tsv(iS:iE,:) = [num2cell(s.stim(ii).data), repmat({s.stim(ii).name}, size(s.stim(ii).data,1),1)]; %#ok<*AGROW>
+    data = [data; s.stim(ii).data];
+end
+if ~isempty(data)
+    [~, order] = sortrows(data,1);
+    tsv(2:end,:) = tsv(order+1,:);
+end
+if ispathvalid(dst)
+    if optionExists(options, 'regenerate')
+        writeTsv(dst, tsv);
+    end
+else
+    writeTsv(dst, tsv);
+end
+
+% Remove stim from
+% if optionExists(options, 'removeStim')
+%     s.Load();
+%     s.stim = StimClass().empty();
+%     s.Save();
+% end
+
+

DataTree/AcquiredData/DataFiles/TsvFile2Snirf.m

@@ -0,0 +1,68 @@
+function snirf = TsvFile2Snirf(src, dst, option)
+snirf = SnirfClass();
+
+% Parse args
+if nargin==0
+    return
+end
+if ~exist('dst','var')
+    dst = '';
+end
+if ~exist('option','var')
+    option = 'nofile';
+end
+
+if ischar(src)
+    tsv = readTsv(src);
+else
+    tsv = src;
+    src = '';
+end
+if isempty(tsv)
+    return;
+end
+
+if isempty(dst) && ispathvalid(src)
+    [pname, fname] = fileparts(src);
+    k = strfind(fname, '_events');
+    if isempty(k)
+        k = length(fname)+1;
+    end
+    dst = [filesepStandard(pname), fname(1:k-1), '_nirs.snirf'];
+end
+
+snirf.SetFilename(dst);
+
+fields = tsv(1,:);
+k = find(strcmp(fields, 'trial_type'));
+if isempty(k)
+    return
+end
+for ii = 2:size(tsv,1)
+    jj = findStim(snirf.stim, tsv{ii,k});
+    if jj == 0
+        snirf.stim(end+1) = StimClass(tsv([1,ii],:));
+    else
+        snirf.stim(jj).AddTsvData(tsv([1,ii],:));
+    end
+end
+if strcmp(option,'nofile')
+    return
+end
+snirf.Save();
+
+
+% -----------------------------------------------------------
+function jj = findStim(stim, tsv)
+jj = 0;
+for ii = 1:length(stim)
+    if isnumeric(tsv)
+        tsv = num2str(tsv);
+    end
+    if strcmp(stim(ii).name, tsv)
+        jj = ii;
+        break;
+    end
+end
+
+