bml_roi_table

 BML_ROI_TABLE transforms a table into an ROI table [internal]

 Use as
   annot=bml_roi_table(x)
   annot=bml_roi_table(x, description)
   annot=bml_roi_table(x, [], x_var_name)

 ROI or Regions Of Interest are annotations with file coordinates.

 x - table: should contains 'starts','ends','folder','name','nSamples','Fs' 
 description - string: description of the ROI table
 x_var_name - string: name of the variable used for the ROI table, as
     returned by inputname(). Useful for anidated calls.

 returns a table with variables:
   id: integer identification number of the synchronized file chunk
   starts: start time in seconds from midnight of the represented signal
   ends: end time in seconds from midnight of the represented signal
   duration: duration in seconds as calculated by ends - starts
   s1: first sample number of synchronization coordinate
   t1: midpoint time of sample s1. Note that if s1==1 => t1=starts+0.5/Fs
   s2: last sample number of synchronization coordinate
   t2: midpoint time of sample s2. Note that if s2==end => t2=ends-0.5/Fs
   folder: path to folder with file
   name: file name. Note that several each file can have several file
         chunks, i.e. several rows in this table 
   nSamples: integer total number of samples of the file
   filetype: 
   chantype:

0001 function roi=bml_roi_table(x, description, x_var_name)
0002 
0003 % BML_ROI_TABLE transforms a table into an ROI table [internal]
0004 %
0005 % Use as
0006 %   annot=bml_roi_table(x)
0007 %   annot=bml_roi_table(x, description)
0008 %   annot=bml_roi_table(x, [], x_var_name)
0009 %
0010 % ROI or Regions Of Interest are annotations with file coordinates.
0011 %
0012 % x - table: should contains 'starts','ends','folder','name','nSamples','Fs'
0013 % description - string: description of the ROI table
0014 % x_var_name - string: name of the variable used for the ROI table, as
0015 %     returned by inputname(). Useful for anidated calls.
0016 %
0017 % returns a table with variables:
0018 %   id: integer identification number of the synchronized file chunk
0019 %   starts: start time in seconds from midnight of the represented signal
0020 %   ends: end time in seconds from midnight of the represented signal
0021 %   duration: duration in seconds as calculated by ends - starts
0022 %   s1: first sample number of synchronization coordinate
0023 %   t1: midpoint time of sample s1. Note that if s1==1 => t1=starts+0.5/Fs
0024 %   s2: last sample number of synchronization coordinate
0025 %   t2: midpoint time of sample s2. Note that if s2==end => t2=ends-0.5/Fs
0026 %   folder: path to folder with file
0027 %   name: file name. Note that several each file can have several file
0028 %         chunks, i.e. several rows in this table
0029 %   nSamples: integer total number of samples of the file
0030 %   filetype:
0031 %   chantype:
0032 
0033 REQUIRED_VARS = {'folder','name','nSamples','Fs'};
0034 RETURNED_VARS = {'id','starts','ends','duration','s1','t1','s2','t2',...
0035                 'folder','name','nSamples','Fs','filetype','chantype'};
0036 
0037 assert(istable(x),"Table required as first argument");              
0038               
0039 if ~exist('description','var') || isempty(description)
0040   if isempty(x.Properties.Description)
0041     if exist('x_var_name','var')
0042       description=x_var_name;
0043     else
0044       description=inputname(1);
0045     end
0046   else
0047     description=x.Properties.Description;
0048   end
0049 end
0050 
0051 roi=bml_annot_table(x,description);
0052 
0053 if ~all(ismember(REQUIRED_VARS, roi.Properties.VariableNames))
0054   error(['table ''x'' requires variables ' strjoin(REQUIRED_VARS,', ')])
0055 end
0056 
0057 if ~all(ismember({'s1','t1'}, roi.Properties.VariableNames))
0058   roi.s1=ones(height(roi),1);
0059   roi.t1=roi.starts + 0.5 ./ roi.Fs;
0060 end
0061 if ~all(ismember({'s2','t2'}, roi.Properties.VariableNames))
0062   roi.s2=roi.nSamples;
0063   roi.t2=roi.ends - 0.5 ./ roi.Fs;
0064 end
0065 
0066 if ~ismember('chantype', roi.Properties.VariableNames)
0067   roi.chantype=repmat({'all'},height(roi),1);
0068 end
0069 
0070 if ~ismember('filetype', roi.Properties.VariableNames)
0071   %ToDo should probably identify filetype from filename
0072   roi.chantype=repmat({'unknown'},height(roi),1);
0073 end
0074 roi = bml_annot_reorder_vars(roi, RETURNED_VARS);