Initial import of BIDS-MATLAB source code and tests

Add core BIDS-MATLAB source files, internal utilities, transformers, documentation, templates, and a comprehensive test suite. This initial commit establishes the project structure, including internal/private APIs, user-facing functions, example notebooks, and developer documentation.

Author: markmikkelsen

bids-matlab/+bids/+internal/README.md

@@ -0,0 +1,7 @@
+# BIDS-MATLAB +internal package
+
+This package contains functions for BIDS-MATLAB's internal use only.
+
+Do not call these functions directly from your code! They are undocumented and
+subject to change at any time.
+If you call these functions from your code, your code may break or produce incorrect results!

bids-matlab/+bids/+internal/add_missing_field.m

@@ -0,0 +1,13 @@
+function structure = add_missing_field(structure, field)
+  %
+  % USAGE::
+  %
+  %   structure = add_missing_field(structure, field)
+  %
+
+  % (C) Copyright 2021 BIDS-MATLAB developers
+
+  if ~isfield(structure, field)
+    structure(1).(field) = '';
+  end
+end

bids-matlab/+bids/+internal/append_to_layout.m

@@ -0,0 +1,183 @@
+function [subject, status, previous] = append_to_layout(file, subject, modality, schema, previous)
+  %
+  % appends a file to the BIDS layout by parsing it according to the provided schema
+  %
+  % USAGE::
+  %
+  %   subject = append_to_layout(file, subject, modality, schema == [])
+  %
+  % :param file:
+  % :type  file: char
+  %
+  % :param subject: subject sub-structure from the BIDS layout
+  % :type  subject: structure
+  %
+  % :param modality:
+  % :type  modality: char
+  %
+  % :param schema:
+  % :type  schema: structure
+  %
+  %
+
+  % (C) Copyright 2021 BIDS-MATLAB developers
+
+  pth = [subject.path, filesep, modality];
+
+  % We speed up indexing by checking that the current file has the same basename
+  % as the previous one.
+  % In this case we can copy most of the info from the previous file
+  if same_data(file, previous)
+
+    % Skip file in case we are using the schema and faced with a file that
+    % does have the same basename as the previous file
+    % but not a recognized extension
+    % - <match>_events.tsv
+    % - <match>_events.mat
+    %
+    if ~isempty(schema.content) && ...
+            ~any(ismember(file(previous.data.len:end), ...
+                          previous.allowed_ext))
+      [msg, id] = error_message('unknownExtension', file, file(previous.data.len:end));
+      bids.internal.error_handling(mfilename, id, msg, true, schema.verbose);
+      status = 0;
+      return
+    end
+
+    subject.(modality)(end + 1, 1) = subject.(modality)(end, 1);
+    subject.(modality)(end, 1).ext = file(previous.data.len:end);
+    subject.(modality)(end, 1).filename = file;
+
+    dep_fname = fullfile(pth, subject.(modality)(end - 1, 1).filename);
+    subject.(modality)(end).dependencies.data{end + 1, 1} = dep_fname;
+    status = 1;
+    return
+
+  else
+
+    % Parse file fist to identify the suffix group in the template.
+    % Then reparse the file using the entity-label pairs defined in the schema.
+    p = bids.internal.parse_filename(file);
+    if isempty(p)
+      status = 0;
+      return
+    end
+
+    if ~isempty(schema.content)
+
+      suffix_group = schema.find_suffix_group(modality, p.suffix);
+
+      if isempty(suffix_group) || strcmp(suffix_group, '')
+        [msg, id] = error_message('unknownSuffix', file, p.suffix);
+        bids.internal.error_handling(mfilename, id, msg, true, schema.verbose);
+        status = 0;
+        return
+      end
+
+      datatypes = schema.get_datatypes();
+
+      this_suffix_group = datatypes.(modality).(suffix_group);
+
+      allowed_extensions = this_suffix_group.extensions;
+
+      schema_entities = schema.return_entities_for_suffix_group(this_suffix_group);
+      required_entities = schema.required_entities_for_suffix_group(this_suffix_group);
+
+      present_entities = fieldnames(p.entities);
+      missing_entities = ~ismember(required_entities, present_entities);
+      unknown_entity = present_entities(~ismember(present_entities, schema_entities));
+
+      extension = p.ext;
+      % in case we are dealing with a folder
+      % (can be the case for some MEG formats: .ds)
+      if exist(fullfile(pth, p.filename), 'dir')
+        extension = [extension '/'];
+      end
+
+      %% Checks that this file is BIDS compliant
+      if ~ismember('*', allowed_extensions) && ...
+              ~ismember(extension, allowed_extensions)
+        [msg, id] = error_message('unknownExtension', file, extension);
+      end
+
+      if ~isempty(unknown_entity)
+        [msg, id] = error_message('unknownEntity', file, ...
+                                  strjoin(cellstr(unknown_entity), ' '));
+      end
+
+      if any(missing_entities)
+        missing_entities = required_entities(missing_entities);
+        [msg, id] = error_message('missingRequiredEntity', file, ...
+                                  strjoin(cellstr(missing_entities), ' '));
+      end
+
+      if exist('id', 'var')
+        bids.internal.error_handling(mfilename, id, msg, true, schema.verbose);
+        status = 0;
+        return
+      end
+
+      p = bids.internal.parse_filename(file, schema_entities);
+      if isempty(p)
+        status = 0;
+        return
+      end
+
+      previous.allowed_ext = allowed_extensions;
+
+    end
+
+    p.metafile = bids.internal.get_meta_list(fullfile(subject.path, modality, file));
+
+    p.dependencies.explicit = {};
+    p.dependencies.data = {};
+    p.dependencies.group = {};
+
+    if ~isempty(subject.(modality))
+      [subject.(modality), p] = bids.internal.match_structure_fields(subject.(modality), p);
+
+    end
+
+    if isempty(subject.(modality))
+      subject.(modality) = p;
+
+    else
+      subject.(modality)(end + 1, 1) = p;
+
+    end
+
+    status = 1;
+
+  end
+
+end
+
+function status = same_data(file, previous)
+
+  status = strncmp(previous.data.base, file, previous.data.len);
+
+end
+
+function [msg, msg_id] = error_message(msg_id, file, extra)
+
+  msg = sprintf('Skipping file: %s.\n', bids.internal.format_path(file));
+
+  switch msg_id
+
+    case 'unknownExtension'
+      msg = sprintf('%s Unknown extension: ''%s''', msg, extra);
+
+    case 'missingRequiredEntity'
+      msg = sprintf('%s Missing REQUIRED entity: ''%s''', msg, extra);
+
+    case 'unknownEntity'
+      msg = sprintf('%s Unknown entities: ''%s''', msg, extra);
+
+    case 'unknownSuffix'
+      msg = sprintf('%s Unknown suffix: ''%s''', msg, extra);
+
+  end
+
+  msg = sprintf('%s\nTry using the parameter: " ''use_schema'', false "\n', msg);
+
+end

bids-matlab/+bids/+internal/camel_case.m

@@ -0,0 +1,29 @@
+function str = camel_case(str)
+  %
+  % Removes non alphanumeric characters and uppercase first letter of all
+  % words but the first
+  %
+  % USAGE::
+  %
+  %   str = camel_case(str)
+  %
+  % :param str:
+  % :type str: char
+  %
+  % :returns:
+  %           :str: (char) returns the input with an upper case for first letter
+  %                  for all words but the first one (``camelCase``) and
+  %                  removes invalid characters (like spaces).
+  %
+
+  % (C) Copyright 2018 BIDS-MATLAB developers
+
+  % camel case: upper case for first letter for all words but the first one
+  spaceIdx = regexp(str, '[a-zA-Z0-9+]*', 'start');
+  str(spaceIdx(2:end)) = upper(str(spaceIdx(2:end)));
+
+  % remove invalid characters
+  [unvalidCharacters] = regexp(str, '[^a-zA-Z0-9+]');
+  str(unvalidCharacters) = [];
+
+end

bids-matlab/+bids/+internal/create_unordered_list.m

@@ -0,0 +1,61 @@
+function list = create_unordered_list(list)
+  %
+  % turns a cell string or a structure into a string
+  % that is an unordered list to print to the screen
+  %
+  % USAGE::
+  %
+  %  list = bids.internal.create_unordered_list(list)
+  %
+  % :param list: obligatory argument.
+  % :type list: cell string or structure
+  %
+  %
+
+  % (C) Copyright 2022 Remi Gau
+
+  if bids.internal.is_octave
+    warning('off', 'Octave:mixed-string-concat');
+  end
+
+  prefix = '\n\t- ';
+
+  if ischar(list)
+    list = cellstr(list);
+  end
+
+  if iscell(list)
+
+    for i = 1:numel(list)
+      if isnumeric(list{i})
+        list{i} = num2str(list{i});
+      end
+    end
+
+    list = sprintf([prefix, strjoin(list, prefix), '\n']);
+
+  elseif isstruct(list)
+
+    output = '';
+    fields = fieldnames(list);
+
+    for i = 1:numel(fields)
+      content = list.(fields{i});
+      if ~iscell(content)
+        content = {content};
+      end
+
+      for j = 1:numel(content)
+        if isnumeric(content{j})
+          content{j} = num2str(content{j});
+        end
+      end
+
+      output = [output prefix fields{i} ': {' strjoin(content, ', ') '}'];
+    end
+
+    list = sprintf(output);
+
+  end
+
+end

bids-matlab/+bids/+internal/download.m

@@ -0,0 +1,73 @@
+function filename = download(URL, output_dir, verbose)
+  %
+  % USAGE::
+  %
+  %   filename = download(URL, output_dir, verbose)
+  %
+
+  % (C) Copyright 2021 BIDS-MATLAB developers
+  if nargin < 2
+    output_dir = pwd;
+  end
+  bids.util.mkdir(output_dir);
+
+  msg = sprintf('Downloading dataset from:\n %s\n\n', URL);
+  print_to_screen(msg, verbose);
+
+  tokens = regexp(URL, '/', 'split');
+  protocol = tokens{1};
+
+  filename = tokens{end};
+  if strcmp(filename, '?zip=')
+    [~, filename] = fileparts(tempname);
+    filename = [filename '.zip'];
+  end
+
+  if exist(filename, 'file')
+    delete(filename);
+  end
+
+  if ismember(protocol, {'http:', 'https:'})
+
+    try
+      urlwrite(URL, filename); %#ok<*URLWR>
+    catch
+      options = '';
+      if ~verbose
+        options = '-q';
+      end
+      system(sprintf('wget %s %s', options, URL));
+    end
+
+    % move file in case it was not downloaded in the root dir
+    if ~exist(fullfile(output_dir, filename), 'file')
+      print_to_screen([bids.internal.format_path(filename), ...
+                       ' --> ', ...
+                       bids.internal.format_path(output_dir)], verbose);
+      movefile(filename, fullfile(output_dir, filename));
+    end
+    filename = fullfile(output_dir, filename);
+
+  else
+
+    ftp_server = tokens{3};
+    ftpobj = ftp(ftp_server);
+
+    filename = strjoin(tokens(4:end), '/');
+    filename = mget(ftpobj, filename, output_dir);
+
+  end
+
+  if iscell(filename)
+    filename = filename{1};
+  end
+
+  print_to_screen(' Done\n\n', verbose);
+
+end
+
+function print_to_screen(msg, verbose)
+  if verbose
+    fprintf(1, msg);
+  end
+end