Merge pull request #193 from Remi-Gau/save_config

[ENH] add a save config function

Author: Remi-Gau

.gitignore

@@ -10,7 +10,6 @@ output
 *test_code_report.txt
 test_report.log
 *coverage*
-test_report.log
 check_my_code_report.txt
 
 *filteredBy*
@@ -19,16 +18,17 @@ tests/*.nii*
 tests/*.json*
 tests/*.tsv*
 
+*_cfg.json
+
 # jupyter notebook checkpoints
 .ipynb_checkpoints
 notebooks/source/*
 notebooks/new_experiment/*
 
 # ignore node js files
-node_modules/*
+node_modules
 package.json
 package-lock.json
-package.json
 
 # visual studio code stuff
 .vscode

docs/source/function_description.rst

@@ -12,8 +12,9 @@ List of functions in the ``src`` folder.
 .. autofunction:: createDatasetDescription
 .. autofunction:: createFilename
 .. autofunction:: createJson
+.. autofunction:: saveCfg
 
-``createJson`` can be used to save in a
+``saveCfg`` can be used to save in a
 human readable format the extra parameters that you used to run your experiment.
 This will most likely make the json file non-bids compliant but it can prove useful,
 to keep this information in your source dataset

lib/bids-matlab

@@ -30,14 +30,44 @@ function createJson(varargin)
     %          - :``*.json``: (jsonfile) The file name corresponds to the run + suffix depending
     %                         on the arguments passed in.
     %
-    % .. TODO:
-    %
-    %    - use input parser for this one
     %
     % (C) Copyright 2020 CPP_BIDS developers
 
-    [cfg, modality, extraInfo] = checkInput(varargin);
+    %% Parse inputs
+    % modality is either given as a string by user or guessed from cfg.fileName
+    % extraInfo must be a structure
+
+    args = inputParser;
+
+    default_modality = '';
+    default_extraInfo = struct([]);
+
+    charOrStruct = @(x) isstruct(x) || ischar(x);
+
+    args.addRequired('input', @isstruct);
+    args.addOptional('modality', default_modality, charOrStruct);
+    args.addOptional('extraInfo', default_extraInfo, @isstruct);
+
+    args.parse(varargin{:});
+
+    cfg = args.Results.input;
+    modality = args.Results.modality;
+    extraInfo = args.Results.extraInfo;
 
+    if ischar(modality) && strcmp(modality, default_modality) && isfield(cfg.fileName, 'modality')
+        modality = cfg.fileName.modality;
+    end
+
+    if isstruct(modality) && isfield(cfg.fileName, 'modality')
+        extraInfo = modality;
+        modality = cfg.fileName.modality;
+    end
+
+    if ~ischar(modality) || all(~strcmpi(modality, {'beh', 'func', 'eeg', 'ieeg', 'meg'}))
+        errorCreateJson('wrongModalityInput', modality);
+    end
+
+    % adapt depending on input
     if strcmp(modality, 'func')
         fileName = strrep(cfg.fileName.events, '_events', '_bold');
         jsonContent = cfg.bids.mri;
@@ -61,66 +91,10 @@ function createJson(varargin)
 
 end
 
-function [cfg, modality, extraInfo] = checkInput(varargin)
-
-    % trying to parse inputs
-    % modality is either given as a string by user or guessed from cfg.fileName
-    % extraInfo must be a structure
-
-    input = varargin{1};
-
-    modality = '';
-    extraInfo = struct();
-
-    switch numel(input)
-
-        case 0
-            errorCreateJson('notEnoughInput');
-
-        case 1
-            cfg = input{1};
-            if isfield(cfg.fileName, 'modality')
-                modality = cfg.fileName.modality;
-            end
-
-        case 2
-            cfg = input{1};
-            if ischar(input{2})
-                modality = input{2};
-            elseif isstruct(input{2})
-                modality = cfg.fileName.modality;
-                extraInfo = input{2};
-            else
-                errorCreateJson('wrongInputType');
-            end
-
-        otherwise
-            cfg = input{1};
-            modality = input{2};
-            extraInfo = input{3};
-
-    end
-
-    if ~ischar(modality) || ...
-            all(~strcmpi(modality, {'beh', 'func', 'eeg', 'ieeg', 'meg'}))
-        errorCreateJson('wrongModalityInput', modality);
-    end
-
-    if ~isstruct(extraInfo)
-        warning('Additional info added to a json file must be a structure.');
-    end
-
-end
-
 function errorCreateJson(identifier, varargin)
 
     switch identifier
-        case 'notEnoughInput'
-            errorStruct.message = 'First input must be a valid cfg structure.';
 
-        case 'wrongInputType'
-            errorStruct.message = ['The second input must be a string (modality)' ...
-                                   'or a structure (extraInfo)'];
         case 'wrongModalityInput'
             errorStruct.message = sprintf(['The given modality is not valid: %s.\n', ...
                                            'Only the following string are accepted: ' ...

src/createJson.m

@@ -0,0 +1,77 @@
+function filename = saveCfg(varargin)
+    %
+    % Saves config as JSON.
+    %
+    % USAGE::
+    %
+    %   saveCfg(cfg [, filename])
+    %
+    % :param cfg: Required. Configuration. See ``checkCFG()``.
+    % :type cfg: structure
+    %
+    % :param filename: Optional. Fullpath filename for the output file.
+    % :type filename: path
+    %
+    % :output: filename
+    %
+    % If a filename is provided, this will be used as an output file (and will
+    % create any required directory).
+    %
+    % If no filename is provided, it will try to create one based on the content
+    % of ``cfg.fileName`` and ``cfg.dir``. This would for example create a
+    % file::
+    %
+    %   ./output/source/sub-01/func/sub-01_task-testTask_run-001_date-202203181752_cfg.json
+    %
+    %
+    % If this fails it will save the file
+    % in the ``pwd`` under ``'date-yyyymmddHHMM_cfg.json'``.
+    %
+    %
+    % (C) Copyright 2022 CPP_BIDS developers
+
+    %% Parse inputs
+    % modality is either given as a string by user or guessed from cfg.fileName
+    % extraInfo must be a structure
+
+    args = inputParser;
+
+    default_filename = '';
+
+    args.addRequired('cfg', @isstruct);
+    args.addOptional('filename', default_filename, @ischar);
+
+    args.parse(varargin{:});
+
+    cfg = args.Results.cfg;
+    filename = args.Results.filename;
+
+    % if no name, get name from config
+    if strcmp(filename, '')
+
+        if isfield(cfg, 'fileName') && isfield(cfg.fileName, 'events')
+            filename = strrep(cfg.fileName.events, '_events.tsv', '_cfg.json');
+            filename = getFullFilename(filename, cfg);
+        end
+
+    end
+
+    % if this did not work we make one up
+    if strcmp(filename, '')
+        tmp = checkCFG();
+        bf = struct('suffix', 'cfg', ...
+                    'ext', '.json', ...
+                    'entities', struct('date', datestr(now, tmp.fileName.dateFormat)));
+        bf = bids.File(bf);
+        filename = fullfile(pwd, bf.filename);
+    end
+
+    if ~isdir(fileparts(filename))
+        bids.util.mkdir(fileparts(filename));
+    end
+
+    %% save
+    jsonContent = cfg;
+    bids.util.jsonencode(filename, jsonContent);
+
+end

src/saveCfg.m

@@ -13,9 +13,16 @@
     %
     % (C) Copyright 2020 CPP_BIDS developers
 
-    fullFilename = fullfile( ...
-                            cfg.dir.outputSubject, ...
-                            cfg.fileName.modality, ...
-                            fileName);
+    if isfield(cfg, 'dir') && isfield(cfg.dir, 'outputSubject') && ...
+        isfield(cfg, 'fileName') && isfield(cfg.fileName, 'modality')
+
+        fullFilename = fullfile(cfg.dir.outputSubject, ...
+                                cfg.fileName.modality, ...
+                                fileName);
+    else
+        warning('Not enough information to build a fullpath filename');
+        fullFilename = fileName;
+
+    end
 
 end

src/utils/getFullFilename.m

@@ -0,0 +1,60 @@
+% (C) Copyright 2020 CPP_BIDS developers
+
+function test_suite = test_saveCfg %#ok<*STOUT>
+    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_saveCfg_basic()
+
+    cfg = setUp();
+
+    filename = saveCfg(cfg);
+
+    expected = fullfile(cfg.dir.outputSubject, ...
+                        cfg.fileName.modality, ...
+                        strrep(cfg.fileName.events, '_events.tsv', '_cfg.json'));
+
+    assertEqual(filename, expected);
+
+    content = bids.util.jsondecode(filename);
+
+    delete(expected);
+
+end
+
+function test_saveCfg_bare_bone()
+
+    cfg.testingDevice = 'mri';
+
+    filename = saveCfg(cfg);
+
+    expected = fullfile(pwd, ['date-'  datestr(now,  'yyyymmddHHMM') '_cfg.json']);
+
+    assertEqual(filename, expected);
+
+    content = bids.util.jsondecode(filename);
+
+    assertEqual(content, struct('testingDevice', 'mri'));
+
+    delete(expected);
+
+end
+
+function test_saveCfg_filename_provided()
+
+    cfg.testingDevice = 'mri';
+
+    filename = saveCfg(cfg, fullfile(pwd, 'cfg', 'cfg.json'));
+
+    expected = fullfile(pwd, 'cfg', 'cfg.json');
+
+    assertEqual(filename, expected);
+
+    delete(expected);
+    rmdir(fullfile(pwd, 'cfg'));
+
+end