function senstypes=cosmo_meeg_senstype_collection()
% return supported MEEG acquisition systems and their channel labels
%
% senstypes=cosmo_meeg_senstypes
%
% Output:
% senstypes struct where the fieldnames are the names
% of the supported MEEG acquisition systems.
% each field has fields:
% .label channel labels
% .sens short label for acquisition system
% .type one of 'meg','meg_planar','meg_axial',
% or 'eeg'. '_combined' entries have the
% 'meg' type.
% Each fieldname can have a postfix:
% '_planar_combined' combined planar
% labels; .label is Nx1 for N
% sensor locations
% '_planar' planar pair
% labels; .label is Nx2
% '_mag' magnetometers, .label
% is Nx1. Currently this is only
% provided for neuromag systems
%
% Example:
% % (This example requires FieldTrip)
% cosmo_skip_test_if_no_external('fieldtrip');
% %
% senstypes=cosmo_meeg_senstype_collection();
% %
% % show neuromag306 MEG magnetometers
% cosmo_disp(senstypes.neuromag306alt_mag)
% %|| .label
% %|| { 'MEG0111'
% %|| 'MEG0121'
% %|| 'MEG0131'
% %|| :
% %|| 'MEG2621'
% %|| 'MEG2631'
% %|| 'MEG2641' }@102x1
% %|| .sens
% %|| 'neuromag306'
% %|| .type
% %|| 'meg_axial'
% %
% % show neuromag306 MEG planar gradiometers
% cosmo_disp(senstypes.neuromag306alt_planar)
% %|| .label
% %|| { 'MEG0112' 'MEG0113'
% %|| 'MEG0122' 'MEG0123'
% %|| 'MEG0132' 'MEG0133'
% %|| : :
% %|| 'MEG2622' 'MEG2623'
% %|| 'MEG2632' 'MEG2633'
% %|| 'MEG2642' 'MEG2643' }@102x2
% %|| .sens
% %|| 'neuromag306'
% %|| .type
% %|| 'meg_planar'
% %
% % show neuromag306 MEG combined planar gradiometers
% cosmo_disp(senstypes.neuromag306alt_planar_combined)
% %|| .label
% %|| { 'MEG0112+0113'
% %|| 'MEG0122+0123'
% %|| 'MEG0132+0133'
% %|| :
% %|| 'MEG2622+2623'
% %|| 'MEG2632+2633'
% %|| 'MEG2642+2643' }@102x1
% %|| .sens
% %|| 'neuromag306'
% %|| .type
% %|| 'meg_planar_combined'
% %
% % show BTI 148 planar gradiometers
% cosmo_disp(senstypes.bti148_planar)
% %|| .label
% %|| { 'A1_dH' 'A1_dV'
% %|| 'A2_dH' 'A2_dV'
% %|| 'A3_dH' 'A3_dV'
% %|| : :
% %|| 'A146_dH' 'A146_dV'
% %|| 'A147_dH' 'A147_dV'
% %|| 'A148_dH' 'A148_dV' }@148x2
% %|| .sens
% %|| 'bti148'
% %|| .type
% %|| 'meg_planar'
%
% Note:
% - this function requires FieldTrip, as it uses its collection of
% layouts
% - this function caches previously read layouts, for optimization
% reasons. run "clear functions" to reset the cahce.
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
senstypes=get_senstypes();
function senstypes=get_senstypes()
persistent cached_senstypes;
if isnumeric(cached_senstypes)
cosmo_check_external('fieldtrip');
sens_type_names=get_initial_sens_type_names();
senstypes=get_initial_senstypes(sens_type_names);
% because senslabel treats neuromag systems in a special way,
% fix the output for a more common naming scheme
% also rename 'planar_combined' to 'combined'
processors={@fix_alt_name_senstypes,...
@fix_neuromag306_planar_combinations,...
@fix_neuromag306_combined_with_mag,...
@fix_ctf275_planar_old_fieldtrip,...
@fix_eeg10XX_channels_old_fieldtrip,...
@fix_yokogawa440_planar_old_fieldtrip,...
@fix_egiX_channels_old_fieldtrip,...
@fix_neuromag122_planar_name,...
@fix_eeg10XX_senstype,...
@add_biosemiXXX_abc_names,...
@add_modalities,...
@check_siblings,...
};
nprocessors=numel(processors);
for k=1:nprocessors
processor=processors{k};
senstypes=processor(senstypes);
end
senstypes=orderfields(senstypes);
cached_senstypes=senstypes;
else
senstypes=cached_senstypes;
end
function sens_type_names=get_initial_sens_type_names()
func_name='ft_senslabel';
if isempty(which(func_name))
error('Cannot find ''%s'' in search path:\n %s',...
func_name,cosmo_strjoin(cosmo_wtf('path'),'\n '));
end
h=help(func_name);
match=regexp(cosmo_strsplit(h,'\n'),'\s*''(\w*)''\s*','tokens');
msk=~cellfun(@isempty,match);
d=diff(msk);
first=find(d==1,1)+1;
last=find(d==-1,1);
sens_types_cell=match(first:last);
sens_type_names=cellfun(@(x)x{:},sens_types_cell);
function senstypes=get_initial_senstypes(sens_type_names)
senstypes=struct();
postfixes={'','_combined'};
for k=1:numel(sens_type_names)
sens_type_name=sens_type_names{k};
for j=1:numel(postfixes)
key=[sens_type_name postfixes{j}];
label=[];
try
label=ft_senslabel(key);
catch
end
if isempty(label)
continue;
end
% if the name ends with '_combined' but not with
% '_planar_combined', make it end with '_planar_combined'
% (necessary for neuromag)
sp=cosmo_strsplit(key,'_');
if numel(sp)>1 && strcmp(sp{end},'combined') && ...
~strcmp(sp{end-1},'planar')
sp{end}=['planar_' sp{end}];
key=cosmo_strjoin(sp,'_');
end
sens_type_name=remove_alt_postfix(sens_type_name);
senstypes.(key).label=label;
senstypes.(key).sens=cosmo_strsplit(sens_type_name,'_',1);
end
end
function s=remove_alt_postfix(s)
sp=cosmo_strsplit(s,'alt');
if numel(sp)>1 && isempty(sp{end});
s=cosmo_strjoin(sp(1:(end-1)),'alt');
end
function s=sort_cellstr_rows(s)
% helper function: sorts each row in a cell with strings
% used to get the planar channels in order even when old FT
% returns a weird random order
n=size(s,1);
for k=1:n
s(k,:)=sort(s(k,:));
end
function senstypes=fix_alt_name_senstypes(senstypes)
% fixer for neuromag, newer fieldtrip versions only
% ft_senslabel returns the label for this system in two
% varietes, with and without spaces (e.g. 'MEG 2442' and 'MEG2442')
% this function adds *alt
keys=fieldnames(senstypes);
n=numel(keys);
for k=1:n
key=keys{k};
label=senstypes.(key).label;
% first half of the label rows are without spaces,
% second half are with spaces
% detect whether that's the case here
nrows=size(label,1);
if mod(nrows,2)~=0
continue;
end
half_nrows=nrows/2;
with_spaces=label(1:half_nrows,:);
without_spaces=label(half_nrows+(1:half_nrows),:);
% transform e.g. 'MEG 2442' to 'MEG2442'
spaces_removed=cellfun(@(x) strrep(x,' ',''),...
with_spaces,'UniformOutput',false);
if isequal(without_spaces,spaces_removed)
% insert 'alt' infix
orig_senstype=senstypes.(key);
sp=cosmo_strsplit(key,'_');
sp{1}=[sp{1} 'alt'];
alt_key=cosmo_strjoin(sp,'_');
% add new senstype for alternative name
senstypes.(alt_key)=orig_senstype;
senstypes.(alt_key).label=without_spaces;
% update label for original name
senstypes.(key)=orig_senstype;
senstypes.(key).label=with_spaces;
end
end
function senstypes=fix_neuromag122_planar_name(senstypes)
% add '_planar' suffix to neuromag122
[keys,sens]=get_keys_sens(senstypes);
idxs=find(cosmo_match(sens,'neuromag122'));
for k=1:numel(idxs)
key=keys{idxs(k)};
label=senstypes.(key).label;
if size(label,2)==2
new_key=[key '_planar'];
assert(~isfield(senstypes,new_key));
senstypes.(new_key)=senstypes.(key);
senstypes=rmfield(senstypes,key);
end
end
function senstypes=add_biosemiXXX_abc_names(senstypes)
% adds the 10/20 labels for biosemi16, 32, 64
for nch=[16 32 64]
chs=struct();
switch nch
case 16
chs.C={ '3' '4' 'z' };
chs.F={ '3' '4' 'z' };
chs.Fp={ '1' '2' };
chs.O={ '1' '2' 'z' };
chs.P={ '3' '4' 'z' };
chs.T={ '7' '8' };
case 32
chs.AF={ '3' '4' };
chs.C={ '3' '4' 'z' };
chs.CP={ '1' '2' '5' '6' };
chs.F={ '3' '4' '7' '8' 'z' };
chs.FC={ '1' '2' '5' '6' };
chs.Fp={ '1' '2' };
chs.O={ '1' '2' 'z' };
chs.P={ '3' '4' '7' '8' 'z' };
chs.PO={ '3' '4' };
chs.T={ '7' '8' };
case 64
chs.AF={ '3' '4' '7' '8' 'z' };
chs.C={ '1' '2' '3' '4' '5' '6' 'z' };
chs.CP={ '1' '2' '3' '4' '5' '6' 'z' };
chs.F={ '1' '2' '3' '4' '5' '6' '7' '8' 'z' };
chs.FC={ '1' '2' '3' '4' '5' '6' 'z' };
chs.FT={ '7' '8' };
chs.Fp={ '1' '2' 'z' };
chs.I={ 'z' };
chs.O={ '1' '2' 'z' };
chs.P={ '1' '10' '2' '3' '4' '5' '6' '7' '8' '9' 'z' };
chs.PO={ '3' '4' '7' '8' 'z' };
chs.T={ '7' '8' };
chs.TP={ '7' '8' };
end
key=sprintf('biosemi%d', nch);
if ~isfield(senstypes,key) || cosmo_overlap(...
{senstypes.(key).label},{{'A1','A2','A3'}})==1
prefixes=fieldnames(chs);
nprefix=numel(prefixes);
label_cell=cell(nprefix,1);
for k=1:nprefix
prefix=prefixes{k};
postfixes=chs.(prefix);
npostfix=numel(postfixes);
prefix_labels=cell(npostfix,1);
for j=1:npostfix
postfix=postfixes{j};
prefix_labels{j}=[prefix postfix];
end
label_cell{k}=prefix_labels;
end
labels=cat(1,label_cell{:});
alt_key=sprintf('biosemi%dalt',nch);
senstype=struct();
senstype.type='eeg';
senstype.sens=key;
senstype.label=labels;
senstypes.(alt_key)=senstype;
end
end
function senstypes=fix_neuromag306_planar_combinations(senstypes)
% fixer for neuromag306
% ft_senslabel does not have the name X_planar,
% but instead has the name X with label in an Nx3 cell
% with the first two columns for planar and the third for mag channels.
% This function takes the first two columns and stores them as
% a proper X_planar senstype, and takes the last column and stores them
% as an X_mag senstype.
keys=fieldnames(senstypes);
n=numel(keys);
for k=1:n
key=keys{k};
label=senstypes.(key).label;
if size(label,2)==3
planar_label=label(:,1:2);
mag_label=label(:,3);
planar_key=[key '_planar'];
mag_key=[key '_mag'];
planar_combined_key=[planar_key '_combined'];
if ~isfield(senstypes,planar_combined_key)
senstypes=old_fieldtrip_add_combined_planar(senstypes,key);
end
assert(isfield(senstypes,planar_combined_key));
% add planar and mag keys
senstypes.(planar_key)=senstypes.(key);
senstypes.(planar_key).label=sort_cellstr_rows(planar_label);
senstypes.(mag_key)=senstypes.(key);
senstypes.(mag_key).label=mag_label;
% remove original key
senstypes=rmfield(senstypes,key);
end
end
function senstypes=fix_neuromag306_combined_with_mag(senstypes)
% since the following commit, ft_senstype supports
% ft_senslabel('neuromag306_combined')
% but its output is different than was expected in
% cosmo_meeg_senstype_collection. In particular the recent commit
% includes the magnetometers, whereas the meeg_senstype
% does not include those. This test is added as check for
% such regressions
% FieldTrip (https://github.com/fieldtrip/fieldtrip.git)
% commit 882dba3426db583f7f4f9ac0cdf4eb3c26aaefc1
% Author: Robert Oostenveld <r.oostenveld@gmail.com>
% Date: Wed Jun 22 12:47:47 2016 +0200
%
% ENH - improve combined planar MEG sensor handling, see
% http://bugzilla.fieldtriptoolbox.org/show_bug.cgi?id=3144
prefix='neuromag306';
suffix='_planar_combined';
keys=fieldnames(senstypes);
n=numel(keys);
for k=1:n
key=keys{k};
if isempty(regexp(key,['^' prefix '.*' suffix '$'],'once'))
continue;
end
label=senstypes.(key).label;
if size(label,2)==2
is_non_combined_channel_mask=cellfun(@isempty,...
regexp(label,'\+'));
keep_mask=[false,true];
illegal_label_mask=bsxfun(@xor,~keep_mask,...
is_non_combined_channel_mask);
if any(illegal_label_mask(:))
error(['unexpected channel order, cannot fix. Please '...
'contact the CoSMoMVPA developers']);
end
senstypes.(key).label=label(:,keep_mask);
end
end
function senstypes=fix_ctf275_planar_old_fieldtrip(senstypes)
% fixes missing channel in old fieldtrip versions
key='ctf275_planar';
if isfield(senstypes,key)
label=senstypes.(key).label;
% detect missing 'MRP31*' labels
if isequal(size(label),[274 2]) && ...
isequal(label([213 214],1),{'MRP23_dH';'MRP32_dH'})
% allocate space
label{275,1}='';
% move one down
label(215:end,:)=label(214:(end-1),:);
% insert
label(214,:)={'MRP31_dH','MRP31_dV'};
senstypes.(key).label=label;
end
end
function senstypes=fix_yokogawa440_planar_old_fieldtrip(senstypes)
% fixes missing channel in old fieldtrip versions
key='yokogawa440_planar';
if isfield(senstypes,key)
label=senstypes.(key).label;
% detect missing 'MRP31*' labels
if isequal(size(label),[420 1]) && ...
isequal(label([1 end],1),{'AG001_dH';'AG392_dV'})
label=reshape(label,[],2);
senstypes.(key).label=label;
end
end
function senstypes=fix_eeg10XX_senstype(senstypes)
% set
keys={'eeg1005','eeg1010','eeg1020'};
for j=1:numel(keys)
key=keys{j};
if isfield(senstypes,key)
senstypes.(key).sens='ext1020';
end
end
function senstypes=fix_eeg10XX_channels_old_fieldtrip(senstypes)
% newer versions of fieldtrip add 8 channels to the eeg10XX series
keys={'eeg1005','eeg1010','eeg1020'};
nchans=[335 86 21 875];
last_chan={'OI2','I2','O2'};
for j=1:numel(keys)
key=keys{j};
if isfield(senstypes,key)
label=senstypes.(key).label;
nchan=nchans(j);
if isequal(label(end),last_chan(j)) && numel(label)==nchan
to_add={'A1' 'A2' 'M1' 'M2' 'T3' 'T4' 'T5' 'T6'}';
senstypes.(key).label=[label;to_add];
end
end
end
function senstypes=fix_egiX_channels_old_fieldtrip(senstypes)
% newer versions of fieldtrip add 8 channels to the egiX series
nchans=2.^(5:8)+1;
for j=1:numel(nchans)
nchan=nchans(j);
key=sprintf('egi%d',nchan-1);
if isfield(senstypes,key)
label=senstypes.(key).label;
wrong_last_label=sprintf('E%d',nchan);
% append label to the end
if numel(label)==nchan && strcmp(label{end},wrong_last_label)
correct_last_label='Cz';
label{end+1}=correct_last_label;
senstypes.(key).label=label;
end
end
end
function senstypes=check_siblings(senstypes)
% helper to ensure all sensor types are kosher.
% checks that "siblings" (different elements in senstypes with the same
% 'sens' value) have the same number of sensor locations
skip_test_for={'yokogawa440',... % has different number of
... % channels across its siblings
'ext1020'}; % for eeg1005, eeg1010, eeg1020
[keys,labels]=get_keys_sens(senstypes);
[idxs,unq_labels]=cosmo_index_unique({labels});
nunq=numel(idxs);
for k=1:nunq
if any(cosmo_match(skip_test_for,unq_labels{1}(k)))
continue
end
idx=idxs{k};
first_key=keys{idx(1)};
first_size=size(senstypes.(first_key).label);
for j=1:numel(idx)
key=keys{idx(j)};
label_size=size(senstypes.(key).label);
% planar systems have two columns for channel labels,
% all others have one
if endswith(key,'_planar')
ncol=2;
else
ncol=1;
end
if label_size(2)~=ncol
disp(senstypes.(key));
error('%s must have %d columns in .label, found %d',...
key,ncol,label_size(2));
end
% veryify that number of channel positions matches across
% all siblings
if ~isequal(first_size(1),label_size(1))
error(['size mismatch between %s and %s: number of '...
'channel positions mismatches (%d ~= %d)'],...
first_key,key,first_size(1),label_size(1));
end
end
end
function [keys,sens]=get_keys_sens(senstypes)
keys=fieldnames(senstypes);
sens=cellfun(@(label)senstypes.(label).sens,keys,...
'UniformOutput',false);
function tf=endswith(s,pf)
tf=isempty(cosmo_strsplit(s,pf,-1));
function senstypes=add_modalities(senstypes)
keys=get_keys_sens(senstypes);
n=numel(keys);
candidates={'meg_planar','meg_axial','meg','eeg',};
ncandidates=numel(candidates);
for k=1:n
key=keys{k};
type=[];
if endswith(key,'_mag')
type='meg_axial';
elseif endswith(key,'_planar')
type='meg_planar';
elseif endswith(key,'_planar_combined')
type='meg_planar_combined';
else
label=senstypes.(key).label;
for j=1:ncandidates
candidate=candidates{j};
if ft_senstype(label,candidate)
type=candidate;
break
end
end
end
if isempty(type)
warning('Could not find modality for %s', key);
senstypes=rmfield(senstypes,key);
continue;
end
senstypes.(key).type=type;
end
function senstypes=old_fieldtrip_add_combined_planar(senstypes, key)
% helper function to deal with old fieldtrip functions.
% it's ugly because it resorts to cd-ing into FT's private directory to
% run planarchannelset
p=pwd();
cleaner=onCleanup(@()cd(p));
ft_dir=fileparts(which('ft_defaults'));
ft_priv_dir=fullfile(ft_dir,'private');
% prepare data
label=senstypes.(key).label;
label_planar=label(:,1:2);
hdr=struct();
hdr.Fs=[];
hdr.label=label_planar(:);
try
% go into FT's private directory
cd(ft_priv_dir);
% try to get the planar channel set
% (using private function; ugly)
planar_channel_set=planarchannelset(hdr);
planar_combined_key=[key '_planar_combined'];
senstypes.(planar_combined_key)=senstypes.(key);
senstypes.(planar_combined_key).label=planar_channel_set(:,3);
catch
caught_error=lasterror();
if cosmo_wtf('is_matlab')
ft_me=MException(caught_error.identifier,caught_error.message);
base_me=MException('CoSMoMVPA:planarchannelset',...
'unable to get planar channel set with old Fieldtrip');
both_me=addCause(base_me, ft_me);
throw(both_me);
else
rethrow(caught_error);
end
end
