function senstype2layout=cosmo_meeg_senstype2layout_mapping(varargin)
% return mapping from MEEG sensor types to sensor layouts
%
% senstype2layout=cosmo_meeg_senstype2layout_mapping()
%
% Output:
% senstype2layout struct where the fieldnames (keys) are senstypes
% (acquisition systems with a possible suffix
% indicating a type of channel)
% If a senstype does not have an associated layout
% then the corresponding value is set to [].
% Otherwise each value has fields:
% .pos Nx2 x and y coordinates (for N channels)
% .width Nx1 channel widths
% .height Nx1 channel heights
% .label Nx1 cell with channel labels
% .name string with name of layout
%
% Examples:
% % (This example requires FieldTrip)
% cosmo_skip_test_if_no_external('fieldtrip');
% %
% senstype2layout=cosmo_meeg_senstype2layout_mapping();
% % get layout for neuromag306 MEG planar (gradiometers)
% layout=senstype2layout.neuromag306alt_planar;
% cosmo_disp(layout.label)
% %|| { 'MEG0113'
% %|| 'MEG0112'
% %|| 'MEG0122'
% %|| :
% %|| 'MEG2643'
% %|| 'COMNT'
% %|| 'SCALE' }@206x1
% cosmo_disp([layout.pos layout.width layout.height])
% %|| [ -0.408 0.253 0.0358 0.0369
% %|| -0.408 0.284 0.0358 0.0369
% %|| -0.328 0.285 0.0358 0.0369
% %|| : : : :
% %|| 0.373 -0.0821 0.0358 0.0369
% %|| -0.547 -0.5 0.0358 0.0369
% %|| 0.547 -0.5 0.0358 0.0369 ]@206x4
% layout.name
% %|| 'neuromag306planar.lay'
%
% % (This example requires FieldTrip)
% cosmo_skip_test_if_no_external('fieldtrip');
% %
% senstype2layout=cosmo_meeg_senstype2layout_mapping();
% % get layout for neuromag306 MEG combined planar
% % (combined gradiometers)
% layout=senstype2layout.neuromag306alt_planar_combined;
% cosmo_disp(layout.label)
% %|| { 'MEG0112+0113'
% %|| 'MEG0122+0123'
% %|| 'MEG0132+0133'
% %|| :
% %|| 'MEG2642+2643'
% %|| 'COMNT'
% %|| 'SCALE' }@104x1
% cosmo_disp([layout.pos layout.width layout.height])
% %|| [ -0.408 0.273 0.0717 0.0791
% %|| -0.328 0.306 0.0717 0.0791
% %|| -0.377 0.179 0.0717 0.0791
% %|| : : : :
% %|| 0.373 -0.104 0.0717 0.0791
% %|| -0.547 -0.5 0.0717 0.0791
% %|| 0.547 -0.5 0.0717 0.0791 ]@104x4
% layout.name
% %|| 'neuromag306cmb.lay'
%
% % (This example requires FieldTrip)
% cosmo_skip_test_if_no_external('fieldtrip');
% %
% senstype2layout=cosmo_meeg_senstype2layout_mapping();
% % get layout for EEG elec1020
% layout=senstype2layout.eeg1020;
% cosmo_disp(layout.label)
% %|| { 'Fp1'
% %|| 'Fpz'
% %|| 'Fp2'
% %|| :
% %|| 'O2'
% %|| 'COMNT'
% %|| 'SCALE' }@23x1
% cosmo_disp([layout.pos layout.width layout.height])
% %|| [ -0.139 0.428 0.139 0.104
% %|| 0 0.45 0.139 0.104
% %|| 0.139 0.428 0.139 0.104
% %|| : : : :
% %|| 0.139 -0.428 0.139 0.104
% %|| -0.547 -0.5 0.139 0.104
% %|| 0.547 -0.5 0.139 0.104 ]@23x4
% layout.name
% %|| 'EEG1020.lay'
%
% Notes:
% - this function requires FieldTrip, as it uses its collection of
% layouts
% - the output from this function is similar to FieldTrip's
% ft_prepare_layout, but positions are not scaled as in FieldTrip
% - this function caches previously read layouts, for optimization
% reasons. run "clear functions" to reset the cache.
% - this function uses cosmo_meeg_layout_collection and
% cosmo_meeg_senstype_collection to match sensor types with layouts
% - this function does not provide layouts for all sensor types; if you
% find a layout of interest is missing, please get in touch with the
% developers
%
% See also: cosmo_meeg_layout_collection, cosmo_meeg_senstype_collection
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
% 'secret' options with thresholds to find best matching layout
defaults=struct();
defaults.thr_layout=.7;
defaults.thr_senstype=.8;
opt=cosmo_structjoin(defaults,varargin);
senstype2layout=get_mapping(opt);
function senstype2layout=get_mapping(opt)
% helper function to actually compute the mapping
persistent cached_opt;
persistent cached_senstype2layout;
if ~isequal(opt,cached_opt) || isempty(cached_senstype2layout)
sc=cosmo_meeg_senstype_collection();
names=fieldnames(sc);
n=numel(names);
senstype2layout=struct();
for k=1:n
name=names{k};
lay=find_layout(name,opt);
senstype2layout.(name)=lay;
end
cached_opt=opt;
cached_senstype2layout=senstype2layout;
end
senstype2layout=cached_senstype2layout;
function pairs=senstypes_alt_names()
% return pairs of sensor types with and without the 'alt' name, e.g.
% neuromag306alt_planar and neuromag306_planar
sc=cosmo_meeg_senstype_collection();
names=fieldnames(sc);
names_without_alt=strrep(names,'alt','');
msk_with_alt=~cosmo_match(names, names_without_alt);
idxs_with_alt=find(msk_with_alt);
ncandidates=numel(idxs_with_alt);
pairs=cell(ncandidates,2);
pos=0;
for k=1:ncandidates
idx_with_alt=idxs_with_alt(k);
name_without_alt=names_without_alt{idx_with_alt};
idx_all=find(cosmo_match(names_without_alt,name_without_alt));
idx_without_alt=setdiff(idx_all,idx_with_alt);
switch numel(idx_without_alt)
case 0
continue
case 1
pos=pos+1;
name_with_alt=names{idx_with_alt};
pairs(pos,:)={name_without_alt,name_with_alt};
otherwise
assert(false);
end
end
pairs=pairs(1:pos,:);
function alt_name=find_alt_name(name)
alt_name=[];
pairs=senstypes_alt_names();
for col=1:2
msk=cosmo_match(pairs(:,col),name);
if any(msk)
assert(sum(msk)==1)
alt_name=pairs{msk,3-col};
return
end
end
function lay=find_layout(name,opt)
% find layout based on sensname
% if no layout is found, lay is returned as []
lay=find_layout_helper(name,opt);
if ~isempty(lay)
return
end
% not found, try to use the alternative name
alt_name=find_alt_name(name);
if ~isempty(alt_name)
lay=find_layout_helper(alt_name,opt);
end
function lay=find_layout_helper(name,opt)
% helper function: first tries to get the layout directly, if that does
% not work, try to infer planar channels from the combined channels
sc=cosmo_meeg_senstype_collection();
label=sc.(name).label;
lay=find_layout_from_label(label,opt);
if ~isempty(lay)
return
end
lay=infer_planar_layout_from_combined(name,opt);
function planar_lay=infer_planar_layout_from_combined(planar_name,opt)
% helper function in case no planar layout is found (e.g. ctf151)
planar_lay=[];
combined_name=[planar_name '_combined'];
sc=cosmo_meeg_senstype_collection();
if all(cosmo_isfield(sc,{planar_name,combined_name}))
planar_label=sc.(planar_name).label;
combined_label=sc.(combined_name).label;
combined_lay=find_layout_from_label(combined_label,opt);
if isempty(combined_lay)
return;
end
% get rid of COMNT and SCALE labels
keep=cosmo_match(combined_lay.label,combined_label);
combined_lay=slice_layout(combined_lay,keep);
if ~isequal(combined_lay.label,combined_label)
return
end
% ensure mapping between number of labels
nlabels=size(combined_lay.pos,1);
combined2planar_idxs=reshape(repmat(1:nlabels,2,1),[],1);
planar_lay=slice_layout(combined_lay,combined2planar_idxs);
planar_lay.label=reshape(planar_label',[],1);
planar_lay.name=[];
end
function lay=slice_layout(lay, to_select)
% helper function to select a subset of channels
nrows=size(lay.pos,1);
keys=fieldnames(lay);
for k=1:numel(keys)
key=keys{k};
value=lay.(key);
if size(value,1)==nrows
lay.(key)=value(to_select,:);
end
end
function lay=find_layout_from_label(label,opt)
% use labels from the layout to identify it
lay_coll=cosmo_meeg_layout_collection();
lay_label=cellfun(@(x)x.label,lay_coll,'UniformOutput',false);
[in_lay, in_label]=cosmo_overlap(lay_label,{label});
[coverage,i]=max(mean([in_lay, in_label],2));
% try to be smart and use decent thresholds
if in_lay(i)<opt.thr_layout || coverage<opt.thr_senstype
lay=[];
else
lay=lay_coll{i};
end
