Incorporating json into bids.File (issues #596 #371)

+bids/+util/update_struct.m

@@ -0,0 +1,91 @@
+function js = update_struct(js, varargin)
+  %
+  % Updates structure with new values.
+  % Can add new fields, replace field values, remove fields,
+  %  and append  new values to a cellarray.
+  %
+  % Designed for manipulating json structures and will not work
+  % on structarrays.
+  %
+  % USAGE::
+  %
+  %  js = update_struct(key1, value1, key2, value2);
+  %  js = update_struct(struct(key1, value1, ...
+  %                            key2, value2));
+  %
+  % Examples:
+  % ---------
+  % Adding and replacing existing fields:
+  %   update_struct(struct('a', 'val_a'),...
+  %                 'a', 'new_val', 'b', 'val_b')
+  %   struct with fields:
+  %      a: 'new_val'
+  %      b: 'val_b'
+  % Removing field from structure:
+  %   update_struct(struct('a', 'val_a', 'b', 'val_b'),
+  %                 'b', [])
+  %   struct with fields:
+  %      a: 'val_a'
+  % Appending values to existing field:
+  %   update_struct(struct('a', 'val_a', 'b', 'val_b'),
+  %                 'b-add', 'val_b2')
+  %   struct with fields:
+  %      a: 'val_a'
+  %      b: {'val_b'; 'val_b2'}
+  %
+
+  % (C) Copyright 2023 BIDS-MATLAB developers
+
+  if numel(varargin) == 0
+    % Nothing to do
+    return
+  end
+
+  if numel(varargin) > 1
+    key_list = varargin(1:2:end);
+    val_list = varargin(2:2:end);
+  elseif isstruct(varargin{1})
+    key_list = fieldnames(varargin{1});
+    val_list = cell(size(key_list));
+    for i = 1:numel(key_list)
+      val_list{i} = varargin{1}.(key_list{i});
+    end
+  else
+    id = bids.internal.camel_case('invalidInput');
+    msg = 'Not list of parameters or structure';
+    bids.internal.error_handling(mfilename(), id, msg, false, true);
+  end
+
+  for ii = 1:numel(key_list)
+    par_key = key_list{ii};
+    try
+      par_value = val_list{ii};
+
+      % Removing field from json structure
+      % Should use only empty double ([]) or any empth object?
+      if isempty(par_value) && isnumeric(par_value)
+        if isfield(js, par_key)
+          js = rmfield(js, par_key);
+        end
+        continue
+      end
+
+      if bids.internal.ends_with(par_key, '-add')
+        par_key = par_key(1:end - 4);
+        if isfield(js, par_key)
+          if ischar(js.(par_key))
+            par_value = {js.(par_key); par_value}; %#ok<AGROW>
+          else
+            par_value = [js.(par_key); par_value]; %#ok<AGROW>
+          end
+        end
+      end
+      js(1).(par_key) = par_value;
+
+    catch ME
+      id = bids.internal.camel_case('structError');
+      msg = sprintf('''%s'' (%d) -- %s', par_key, ii, ME.message);
+      bids.internal.error_handling(mfilename(), id, msg, false, true);
+    end
+  end
+end

+bids/File.m

@@ -65,6 +65,38 @@
   %
   %   file = bids.File(name_spec, 'use_schema', true);
   %
+  % Load metadata (supporting inheritance).
+  %
+  % .. code-block:: matlab
+  %
+  %   f = bids.File('tests/data/synthetic/sub-01/anat/sub-01_T1w.nii.gz');
+  %   f = f.set_metadata();
+  %
+  % Acess metadata
+  %
+  % .. code-block:: matlab
+  %
+  %   f.metadata()
+  %     struct with fields:
+  %       Manufacturer: 'Siemens'
+  %       FlipAngle: 10
+  %
+  % Modify metadata
+  %
+  % .. code-block:: matlab
+  %
+  %   f = f.metadata_update('Description', 'Source file');
+  %   f.metadata()
+  %     struct with fields:
+  %       Manufacturer: 'Siemens'
+  %       FlipAngle: 10
+  %       Description: 'Source file'
+  %
+  % Export metadata as json:
+  %
+  % .. code-block:: matlab
+  %
+  %   f.metadata_export()
 
   % (C) Copyright 2021 BIDS-MATLAB developers
 
@@ -90,7 +122,7 @@
 
     metadata_files = {} % list of metadata files related
 
-    metadata  % list of metadata for this file
+    metadata  = [] % list of metadata for this file
 
     entity_required = {}  % Required entities
 
@@ -165,7 +197,7 @@
         obj = obj.use_schema();
       end
 
-      obj = obj.set_metadata();
+      % obj = obj.set_metadata();
 
       obj = obj.update();
     end
@@ -707,6 +739,47 @@ function check_required_entities(obj)
 
     end
 
+    % Functions related to metadata manipulation
+
+    function obj = metadata_update(obj, varargin)
+      % Update stored metadata with new values passed in varargin,
+      % which can be either a structure, or pairs of key-values.
+      %
+      % See also
+      %    bids.util.update_struct
+      %
+      % USAGE::
+      %
+      %  f = f.metadata_update(key1, value1, key2, value2);
+      %  f = f.metadata_update(struct(key1, value1, ...
+      %                        key2, value2));
+
+      obj.metadata = bids.util.update_struct(obj.metadata, varargin{:});
+    end
+
+    function metadata_export(obj, varargin)
+      % Export current content of metadata to sidecar json with
+      % same name as current file. Metadata fields can be modified
+      % with new values passed in varargin, which can be either a structure,
+      % or pairs of key-values. These modifications do not affect
+      % current File object, and only exported into file. Use
+      % bids.File.metadata_update to update currect metadata.
+      %
+      % See also
+      %    bids.util.update_struct
+      %
+      % USAGE::
+      %
+      %  f.metadata_export(key1, value1, key2, value2);
+      %  f.metadata_export(struct(key1, value1, ...
+      %                    key2, value2));
+      [path, ~, ~] = fileparts(obj.path);
+      out_file = fullfile(path, obj.json_filename);
+
+      der_json = bids.util.update_struct(obj.metadata, varargin{:});
+      bids.util.jsonencode(out_file, der_json, 'indent', '  ');
+    end
+
     %% Things that might go private
 
     function bids_file_error(obj, id, msg)

tests/tests_utils/test_update_struct.m

@@ -0,0 +1,49 @@
+function test_suite = test_update_struct %#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_main_func()
+
+  % testing with parameters
+  js = struct([]);
+  js = bids.util.update_struct(js, 'key_a', 'val_a', 'key_b', 'val_b');
+  assertTrue(isfield(js, 'key_a'));
+  assertTrue(isfield(js, 'key_b'));
+  assertEqual(js.key_a, 'val_a');
+  assertEqual(js.key_b, 'val_b');
+
+  % testing with struct
+  test_struct.key_c = 'val_c';
+
+  js = bids.util.update_struct(js, test_struct);
+  assertTrue(isfield(js, 'key_c'));
+  assertEqual(js.key_c, 'val_c');
+
+  % testing update and removal of field
+  js = bids.util.update_struct(js, 'key_c', [], 'key_a', 'val_a2');
+  assertFalse(isfield(js, 'key_c'));
+  assertEqual(js.key_a, 'val_a2');
+
+  % testing concatenating as string cell
+  js = bids.util.update_struct(js, 'key_b-add', 'val_b2');
+  assertEqual(js.key_b, {'val_b'; 'val_b2'});
+
+  % testing concatenating numericals
+  js = bids.util.update_struct(js, 'key_b-add', 3);
+  assertEqual(js.key_b, {'val_b'; 'val_b2'; 3});
+end
+
+function test_exceptions()
+  % Invalid input
+  assertExceptionThrown(@() bids.util.update_struct(struct([]), 'key_b-add'), ...
+                        'update_struct:invalidInput');
+  assertExceptionThrown(@() bids.util.update_struct(struct([]), ...
+                                                    'key_b-add', [], ...
+                                                    'key_c'), ...
+                        'update_struct:structError');
+end