Home > vbmeg > functions > device > meg > vb_megfile_load_data_external.m

vb_megfile_load_data_external

PURPOSE ^

load specified data from MEG-MAT file which has data externally (binary)

SYNOPSIS ^

function [data, channel_info] = vb_megfile_load_data_external(megfile, loadspec, new_file, return_swt, verbose_swt)

DESCRIPTION ^

 load specified data from MEG-MAT file which has data externally (binary)

 [usage]
   [data, channel_info] = vb_megfile_load_data_external( ...
     megfile, loadspec, new_file, return_swt, verbose_swt)

 [input]
       megfile : <required> <<file>> MEG-MAT file

      loadspec : <required> <<struct>> loading instruction
      .ChannelName : <optional> channel name list [Nch x 1] []
                   :  name(string) list of  target channel
                   :  The way to be used this depends on the
                   :  "ChannelSwitch" field
                   :  e.g.
                   :   {'1';'2';'3';'4'}
                   :  If this is empty, all the channels are
                   :  specified
    .ChannelSwitch : <optiolal> <<boolean>> [true] | false
                   :   Which is "ChannelName", to be read, or not?
                   :   [true] : to be read
                   :    false : to be omitted
      .ChannelType : <optional> <<string>> channel type
                   :  [(depend on vb_loadspec_check.m)]
                   :  'MEG'       : MEG channel data
                   :  'EXTRA'     : extra channel data
                   :  'REFERENCE' : reference channel data
                   :  'AXIAL'     : AxialGradioMeter
                   :  'PLANAR'    : PlanarGradioMeter
                   :  'ALL'       : 'MEG'+'EXTRA'+'REFERENCE'
                   :  - case insensitive
          .Trigger : <optional> trigger sample number list []
                   :   [Ntrigger(Ntrial) x 1]
                   :   e.g. [1000;2000;3000]
       .Pretrigger : <optional> number of sample of pre-trigger
                   :  [0]
      .Posttrigger : <optional> number of sample of post-trigger
                   :  [Nsample - 1]
      .TrialNumber : <optional> trial number list [] [Ntrial x 1]
                   :   "1" start
                   :    e.g. [1;2;3]
                   :    if this is empty, all the trials are specified
    .ActiveChannel : <optional> <<boolean>> [false]
                   :  active channel filter switch
                   :    true) active channels
                   :   false) all the channels
      .ActiveTrial : <optional> <<boolean>> [false]
                   :  active trial filter switch
                   :  valid only when data type is Evoked_Raw
                   :    true) active trials
                   :   false) all the trials
          .saveman : <optional> <<struct>>
                   :  if you want to store data externally, this field is
                   :  necessary.
                   :  if this field is not given or is empty, sampling data
                   :  will store internally.
                   :   .data_dir : directory (relative path) for external file
                   :   .precision : usually 'float64'

      new_file : <optional> new MEG-MAT file name which is stored picked up
               :  data and changed information []
               :  if this is empty, new file will not be created
    return_swt : <optional> <<boolean>> 
               :  switch whether return loaded data or not
               :  [true] | false
   verbose_swt : <optional> <<boolean>> 
               :  switch whether output verbose message or not
               :  [true] | false

 [output]
          data : read data [Nchannel x Nsample x Ntrial]
  channel_info : <<struct>> channel information of loaded data
               :  .Active [Nchannel x 1]
               :  .Name   [Nchannel x 1]
               :  .Type   [Nchannel x 1]
               :  .ID     [Nchannel x 1]

 [note]
   vb_megfile_load_data was divided into two functions, according to how to
   store data. internally or externally.

   See also
     vb_megfile_load_data
     vb_megfile_load_data_internal
     vb_megfile_make_new_megfile

 [history]
   2008-04-17 (Sako) initial version
   2008-04-30 (Sako) deleted unused inner function
   2008-06-05 (Sako) modified interface spec - ChannelType, channel_info
   2010-06-30 (Sako) supported storing data externally
   2010-07-01 (Sako) modified how to pick up trial data

 Copyright (C) 2011, ATR All Rights Reserved.
 License : New BSD License(see VBMEG_LICENSE.txt)

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

0001 function [data, channel_info] = vb_megfile_load_data_external( ...
0002   megfile, loadspec, new_file, return_swt, verbose_swt)
0003 % load specified data from MEG-MAT file which has data externally (binary)
0004 %
0005 % [usage]
0006 %   [data, channel_info] = vb_megfile_load_data_external( ...
0007 %     megfile, loadspec, new_file, return_swt, verbose_swt)
0008 %
0009 % [input]
0010 %       megfile : <required> <<file>> MEG-MAT file
0011 %
0012 %      loadspec : <required> <<struct>> loading instruction
0013 %      .ChannelName : <optional> channel name list [Nch x 1] []
0014 %                   :  name(string) list of  target channel
0015 %                   :  The way to be used this depends on the
0016 %                   :  "ChannelSwitch" field
0017 %                   :  e.g.
0018 %                   :   {'1';'2';'3';'4'}
0019 %                   :  If this is empty, all the channels are
0020 %                   :  specified
0021 %    .ChannelSwitch : <optiolal> <<boolean>> [true] | false
0022 %                   :   Which is "ChannelName", to be read, or not?
0023 %                   :   [true] : to be read
0024 %                   :    false : to be omitted
0025 %      .ChannelType : <optional> <<string>> channel type
0026 %                   :  [(depend on vb_loadspec_check.m)]
0027 %                   :  'MEG'       : MEG channel data
0028 %                   :  'EXTRA'     : extra channel data
0029 %                   :  'REFERENCE' : reference channel data
0030 %                   :  'AXIAL'     : AxialGradioMeter
0031 %                   :  'PLANAR'    : PlanarGradioMeter
0032 %                   :  'ALL'       : 'MEG'+'EXTRA'+'REFERENCE'
0033 %                   :  - case insensitive
0034 %          .Trigger : <optional> trigger sample number list []
0035 %                   :   [Ntrigger(Ntrial) x 1]
0036 %                   :   e.g. [1000;2000;3000]
0037 %       .Pretrigger : <optional> number of sample of pre-trigger
0038 %                   :  [0]
0039 %      .Posttrigger : <optional> number of sample of post-trigger
0040 %                   :  [Nsample - 1]
0041 %      .TrialNumber : <optional> trial number list [] [Ntrial x 1]
0042 %                   :   "1" start
0043 %                   :    e.g. [1;2;3]
0044 %                   :    if this is empty, all the trials are specified
0045 %    .ActiveChannel : <optional> <<boolean>> [false]
0046 %                   :  active channel filter switch
0047 %                   :    true) active channels
0048 %                   :   false) all the channels
0049 %      .ActiveTrial : <optional> <<boolean>> [false]
0050 %                   :  active trial filter switch
0051 %                   :  valid only when data type is Evoked_Raw
0052 %                   :    true) active trials
0053 %                   :   false) all the trials
0054 %          .saveman : <optional> <<struct>>
0055 %                   :  if you want to store data externally, this field is
0056 %                   :  necessary.
0057 %                   :  if this field is not given or is empty, sampling data
0058 %                   :  will store internally.
0059 %                   :   .data_dir : directory (relative path) for external file
0060 %                   :   .precision : usually 'float64'
0061 %
0062 %      new_file : <optional> new MEG-MAT file name which is stored picked up
0063 %               :  data and changed information []
0064 %               :  if this is empty, new file will not be created
0065 %    return_swt : <optional> <<boolean>>
0066 %               :  switch whether return loaded data or not
0067 %               :  [true] | false
0068 %   verbose_swt : <optional> <<boolean>>
0069 %               :  switch whether output verbose message or not
0070 %               :  [true] | false
0071 %
0072 % [output]
0073 %          data : read data [Nchannel x Nsample x Ntrial]
0074 %  channel_info : <<struct>> channel information of loaded data
0075 %               :  .Active [Nchannel x 1]
0076 %               :  .Name   [Nchannel x 1]
0077 %               :  .Type   [Nchannel x 1]
0078 %               :  .ID     [Nchannel x 1]
0079 %
0080 % [note]
0081 %   vb_megfile_load_data was divided into two functions, according to how to
0082 %   store data. internally or externally.
0083 %
0084 %   See also
0085 %     vb_megfile_load_data
0086 %     vb_megfile_load_data_internal
0087 %     vb_megfile_make_new_megfile
0088 %
0089 % [history]
0090 %   2008-04-17 (Sako) initial version
0091 %   2008-04-30 (Sako) deleted unused inner function
0092 %   2008-06-05 (Sako) modified interface spec - ChannelType, channel_info
0093 %   2010-06-30 (Sako) supported storing data externally
0094 %   2010-07-01 (Sako) modified how to pick up trial data
0095 %
0096 % Copyright (C) 2011, ATR All Rights Reserved.
0097 % License : New BSD License(see VBMEG_LICENSE.txt)
0098 
0099 % --- CHECK ARGUMENTS --- %
0100 if ~exist('megfile', 'var'), megfile = []; end
0101 if ~exist('loadspec', 'var'), loadspec = []; end
0102 if ~exist('new_file', 'var'), new_file = []; end
0103 if ~exist('return_swt', 'var'), return_swt = []; end
0104 if ~exist('verbose_swt', 'var'), verbose_swt = []; end
0105 [meginfo, ch_list, target_sample, tr_list, ...
0106   new_file, return_swt, root_dir, loadspec, VERBOSE] = ...
0107   inner_check_arguments(megfile, loadspec, new_file, return_swt, verbose_swt);
0108 
0109 % --- MAIN PROCEDURE --------------------------------------------------------- %
0110 %
0111 if VERBOSE >= 5 % temporarily <notice> level
0112   fprintf('  --- now loading ...\n');
0113 end
0114 
0115 %
0116 % --- get channel labels
0117 %
0118 meg_labels = vb_meginfo_get_channel_label_meg(meginfo);
0119 ext_labels = vb_meginfo_get_channel_label_extra(meginfo);
0120 ref_labels = vb_meginfo_get_channel_label_refmg(meginfo);
0121 
0122 %
0123 % --- EXTRA CHANNEL DATA
0124 %
0125 if ~isempty(ext_labels)
0126   [ext_ch_idx] = vb_util_get_index(ext_labels, ch_list);
0127   if ~isempty(ext_ch_idx)
0128     ext_ch_idx = vb_util_arrange_list(ext_ch_idx, 0);
0129   end
0130 
0131 else
0132   ext_ch_idx = [];
0133 end
0134 
0135 %
0136 % --- MEG CHANNEL DATA
0137 %
0138 if ~isempty(meg_labels)
0139   [meg_ch_idx] = vb_util_get_index(meg_labels, ch_list);
0140   if ~isempty(meg_ch_idx)
0141     meg_ch_idx = vb_util_arrange_list(meg_ch_idx, 0);
0142   end
0143 else
0144   meg_ch_idx = [];
0145 end
0146 
0147 %
0148 % --- REFERENCE MAGNETOMETER CHANNEL DATA
0149 %
0150 if ~isempty(ref_labels)
0151   [ref_ch_idx] = vb_util_get_index(ref_labels, ch_list);
0152   if ~isempty(ref_ch_idx)
0153     ref_ch_idx = vb_util_arrange_list(ref_ch_idx, 0);
0154   end
0155 else
0156   ref_ch_idx = [];
0157 end
0158 
0159 %
0160 % --- get read channels' label
0161 %
0162 read_meg_ch = meg_labels(meg_ch_idx);
0163 read_ext_ch = ext_labels(ext_ch_idx);
0164 read_ref_ch = ref_labels(ref_ch_idx);
0165 
0166 % --- MEG
0167 if ~isempty(read_meg_ch)
0168   bexp = vb_meginfo_read_data_file( ...
0169     meginfo, read_meg_ch, target_sample, [], tr_list, root_dir);
0170 else
0171   bexp = [];
0172 end
0173 
0174 % --- EXTRA
0175 if ~isempty(read_ext_ch)
0176     exdata = vb_meginfo_read_data_file( ...
0177     meginfo, read_ext_ch, target_sample, [], tr_list, root_dir);
0178 else
0179   exdata = [];
0180 end
0181 
0182 % --- REFMG
0183 if ~isempty(read_ref_ch)
0184   refdata = vb_meginfo_read_data_file( ...
0185     meginfo, read_ref_ch, target_sample, [], tr_list, root_dir);
0186 else
0187   refdata = [];
0188 end
0189 
0190 % --- actions after loading
0191 
0192 % ----- save new meg-mat file
0193 if ~isempty(new_file)
0194   new_acqtype = vb_meginfo_get_next_acq_type(meginfo, '', loadspec);
0195 
0196   vb_megfile_make_new_megfile(megfile, new_file, loadspec, ...
0197     read_meg_ch, read_ext_ch, read_ref_ch, ...
0198     bexp, exdata, refdata, new_acqtype, target_sample);
0199 end
0200 
0201 
0202 %
0203 % --- return values
0204 %
0205 % ----- arrange data
0206 data = [bexp;exdata;refdata];
0207 
0208 % ------- ChannelInfo
0209 %   .Active
0210 %   .Name
0211 %   .Type
0212 %   .ID
0213 channel_info = vb_megfile_make_channel_info(megfile, ...
0214   read_meg_ch, read_ext_ch, read_ref_ch);
0215 
0216 % ----- decide return value
0217 if ~return_swt
0218   data = [];
0219 end
0220 return;
0221 %
0222 % --- END OF MAIN PROCEDURE -------------------------------------------------- %
0223 
0224 % --- INNER FUNCTIONS -------------------------------------------------------- %
0225 %
0226 % --- inner_check_arguments()
0227 %
0228 function [meginfo, read_ch_list, target_samples, trial_idx, ...
0229     new_file, return_swt, root_dir, loadspec, verbose_level] = ...
0230   inner_check_arguments(megfile, loadspec, new_file, return_swt, verbose_level)
0231 
0232 func_ = mfilename;
0233 
0234 if isempty(megfile)
0235   error('(%s)megfile is a required parameter', func_);
0236 end
0237 
0238 if exist(megfile, 'file') ~= 2
0239   error('(%s)cannot find megfile : %s', func_, megfile);
0240 end
0241 
0242 meginfo = vb_megfile_load_meginfo(megfile);
0243 
0244 % ----- megfile directory
0245 root_dir = vb_get_file_parts(megfile);
0246 
0247 if isempty(loadspec)
0248   loadspec = vb_loadspec_check(loadspec, eegfile);
0249 end
0250 
0251 read_ch_list = loadspec.ChannelName;
0252 % read_ch_list is [N x 1]
0253 
0254 % ----- target samples [Ntrial x 2]
0255 target_samples = vb_loadspec_make_trial_sample(loadspec);
0256 if isempty(target_samples)
0257   n_sample = vb_info_get_sample_number(meginfo);
0258   target_samples = [1 n_sample];
0259 end
0260 
0261 % ----- check TrialNumber
0262 N_trial = vb_info_get_Nrepeat(meginfo);
0263 if N_trial == 1
0264   trial_idx = [];
0265 else
0266   org_info = vb_load_measurement_info(megfile);
0267   org_trial = org_info.Trial;
0268   org_trial_idx = [org_trial.number];
0269 
0270   % --- trigger info
0271   if size(target_samples, 1) > 1
0272     fprintf('(%s) loadspec.Trigger may be wrong\n', mfilename);
0273     target_samples = target_samples(1,:);
0274   end
0275   
0276   if isempty(loadspec.TrialNumber)
0277     cur_trial = vb_info_get_trial_data(meginfo);
0278     trial_idx = 1:length(cur_trial);
0279   else
0280     cur_trial = vb_info_get_trial_data(meginfo, loadspec.TrialNumber);
0281     dst_trial_idx = [cur_trial.number];
0282     [result, trial_idx] = ...
0283       vb_util_check_numerical_lists(org_trial_idx, dst_trial_idx);
0284   end
0285 
0286   if loadspec.ActiveTrial && isequal(org_trial_idx(:), loadspec.TrialNumber(:));
0287     % loadspec.TrialNumber not specified, by vb_load_meg_data,
0288     % load only active trial data.
0289     active_list = vb_info_get_active_trial(meginfo);
0290     if isempty(active_list)
0291         active_list = [cur_trial.Active];
0292     end
0293     trial_idx = trial_idx(active_list==true);
0294   end
0295 end
0296 loadspec.TrialNumber = trial_idx;
0297 
0298 if isempty(new_file)
0299   % require no action
0300 end
0301 
0302 if isempty(return_swt)
0303   return_swt = true;
0304 end
0305 
0306 if isempty(new_file) && ~return_swt
0307   error('(%s)wrong combination - empty output file and no return', func_);
0308 end
0309 
0310 if isempty(verbose_level)
0311   verbose_level = 1;
0312 end
0313 
0314 return;
0315 %
0316 % --- end of inner_check_arguments()
0317 %
0318 % --- END OF INNER FUNCTIONS ------------------------------------------------- %
0319 
0320 % --- END OF FILE --- %

Generated on Mon 22-May-2023 06:53:56 by m2html © 2005