add function to return filename of given contrast image

Author: Remi-Gau

src/messages/printAvailableContrasts.m

@@ -1,8 +1,40 @@
-function printAvailableContrasts(SPM, opt)
+function printAvailableContrasts(varargin)
+  %
+  % USAGE::
+  %
+  %     printAvailableContrasts(SPM, opt)
+  %
+  % :param SPM: fullpath to SPM.mat file or content of SPM.mat file
+  % :type  SPM: structure or path
+  %
+  % :param opt: Options chosen.
+  % :type  opt:  structure
+  %
+  % See also: returnContrastImageFile, getContrastNb
   %
 
   % (C) Copyright 2019 bidspm developers
+
+  defaultOpt = struct('verbosity', 2);
+
+  isStructOrFile = @(x) isstruct(x) || exist(x, 'file') == 2;
+
+  args = inputParser;
+
+  addRequired(args, 'SPM', isStructOrFile);
+  addOptional(args, 'opt', defaultOpt, @isstruct);
+
+  parse(args, varargin{:});
+
+  SPM = args.Results.SPM;
+  if ~isstruct(SPM)
+    load(SPM, 'SPM');
+  end
+
+  opt = args.Results.opt;
+
   printToScreen('List of contrast in this SPM file\n', opt);
   printToScreen(createUnorderedList({SPM.xCon.name}), opt);
   printToScreen('\n', opt);
+
 end

src/messages/printToScreen.m

@@ -9,12 +9,12 @@ function printToScreen(varargin)
 
   args = inputParser;
 
-  default_opt = struct('verbosity', 2);
-  default_format = 'blue';
+  defaultOpt = struct('verbosity', 2);
+  defaultFormat = 'blue';
 
   addRequired(args, 'msg', @ischar);
-  addOptional(args, 'opt', default_opt, @isstruct);
-  addParameter(args, 'format', default_format, @ischar);
+  addOptional(args, 'opt', defaultOpt, @isstruct);
+  addParameter(args, 'format', defaultFormat, @ischar);
 
   parse(args, varargin{:});
 

src/stats/utils/getContrastNb.m

@@ -10,6 +10,18 @@
   %     contrastNb = getContrastNb(result, opt, SPM)
   %
   %
+  % :param SPM: content of SPM.mat file
+  % :type  SPM: structure or path
+  %
+  % :param result: structure with at least a ``name`` field
+  %                with a chat with the name of the contrast of interest
+  % :type  result: struct
+  %
+  % :param opt: Options chosen.
+  % :type  opt:  structure
+  %
+  %
+  % See also: printAvailableContrasts, getContrastNb
 
   % (C) Copyright 2019 bidspm developers
 

src/stats/utils/returnContrastImageFile.m

@@ -0,0 +1,50 @@
+function conImageFile = returnContrastImageFile(varargin)
+  %
+  % Return the contrast image file for the contrast name the user asked
+  %
+  % The search is regex based and any string (like 'foo') will be by default
+  % regexified (into '^foo$').
+  %
+  % USAGE::
+  %
+  %     conImageFile = returnContrastImageFile(SPM, name, opt)
+  %
+  % :param SPM: fullpath to SPM.mat file or content of SPM.mat file
+  % :type  SPM: structure or path
+  %
+  % :param name: name of the contrast of interest
+  % :type  name: char
+  %
+  % :param opt: Options chosen.
+  % :type  opt:  structure
+  %
+  % See also: printAvailableContrasts, getContrastNb
+  %
+
+  % (C) Copyright 2022 bidspm developers
+
+  defaultOpt = struct('verbosity', 2);
+
+  isStructOrFile = @(x) isstruct(x) || exist(x, 'file') == 2;
+
+  args = inputParser;
+
+  addRequired(args, 'SPM', isStructOrFile);
+  addRequired(args, 'name', @ischar);
+  addOptional(args, 'opt', defaultOpt, @istruct);
+
+  parse(args, varargin{:});
+
+  SPM = args.Results.SPM;
+  if ~isstruct(SPM)
+    SPM = load(SPM, 'SPM');
+  end
+
+  result.name = args.Results.name;
+  opt = args.Results.opt;
+
+  contrastNb = getContrastNb(result, opt, SPM);
+
+  conImageFile = fullfile(SPM.swd, sprintf('con_%04.0f.nii', contrastNb));
+
+end

tests/tests_stats/utils/test_printAvailableContrasts.m

@@ -0,0 +1,29 @@
+function test_suite = test_printAvailableContrasts %#ok<*STOUT>
+
+  % (C) Copyright 2022 bidspm developers
+  try % assignment of 'localfunctions' is necessary in Matlab >= 2016
+    test_functions = localfunctions(); %#ok<*NASGU>
+  catch % no problem; early Matlab versions can use initTestSuite fine
+  end
+  initTestSuite;
+end
+
+function test_printAvailableContrasts_basic()
+
+  opt = setTestCfg();
+
+  SPM.xCon(1, 1).name = 'foo';
+  SPM.xCon(2, 1).name = 'bar';
+  SPM.xCon(3, 1).name = 'foobar';
+
+  printAvailableContrasts(SPM, opt);
+
+  save(fullfile(pwd, 'SPM.mat'), 'SPM');
+
+  printAvailableContrasts(fullfile(pwd, 'SPM.mat'), opt);
+
+  printAvailableContrasts(SPM);
+
+  delete(fullfile(pwd, 'SPM.mat'));
+
+end

tests/tests_stats/utils/test_returnContrastImageFile.m

@@ -0,0 +1,30 @@
+function test_suite = test_returnContrastImageFile %#ok<*STOUT>
+
+  % (C) Copyright 2022 bidspm developers
+  try % assignment of 'localfunctions' is necessary in Matlab >= 2016
+    test_functions = localfunctions(); %#ok<*NASGU>
+  catch % no problem; early Matlab versions can use initTestSuite fine
+  end
+  initTestSuite;
+end
+
+function test_returnContrastImageFile_basic()
+
+  %% GIVEN
+
+  opt = setTestCfg();
+
+  SPM.swd = pwd;
+  SPM.xCon(1, 1).name = 'foo';
+  SPM.xCon(2, 1).name = 'bar';
+  SPM.xCon(3, 1).name = 'foobar';
+
+  conImageFile = returnContrastImageFile(SPM, 'bar');
+  assertEqual(conImageFile, fullfile(pwd, 'con_0002.nii'));
+
+  save(fullfile(pwd, 'SPM.mat'), 'SPM');
+  conImageFile = returnContrastImageFile(SPM, 'foobar');
+  assertEqual(conImageFile, fullfile(pwd, 'con_0003.nii'));
+  delete(fullfile(pwd, 'SPM.mat'));
+
+end