function layout=cosmo_meeg_find_layout(ds, varargin)
% finds an MEEG channel layout associated with a dataset
%
% layout=cosmo_meeg_find_layout(ds, varargin)
%
% Inputs:
% 'chantype', ct string indicating the channel type (if the dataset
% has channel labels that allow for different types of
% channels. Depending on the dataset, possible options
% are:
% - 'meg_planar' pairs of planar MEG
% - 'meg_axial' axial MEG
% - 'meg_planar_combined' combined planar MEG
% - 'meg_combined_from_planar' pairs of planar MEG [*]
% - 'eeg' eeg channels
%
% Output:
% layout MEG channel layout with 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
% [*] when chantype is set to
% 'meg_combined_from_planar', layout also contains a
% field .parent which is a layout in itself for the
% 'meg_planar_combined channels'. In that case,
% layout.parent has the .pos, .width, .height, .label
% and .name fields (all of size Mx1 or Mx2 for M
% planar-combined channels, and in addition a cell
% .child_label (of size Mx1) which contains the
% channel labels in layout.name.
%
% Examples:
% % (This example requires FieldTrip)
% cosmo_skip_test_if_no_external('fieldtrip');
% %
% % generate neuromag306 dataset
% ds=cosmo_synthetic_dataset('type','meeg','sens','neuromag306_all');
% % get layout for the planar channels
% pl_layout=cosmo_meeg_find_layout(ds,'chantype','meg_planar');
% cosmo_disp(pl_layout.label)
% %|| { 'MEG0113'
% %|| 'MEG0112'
% %|| 'MEG0122'
% %|| :
% %|| 'MEG2643'
% %|| 'COMNT'
% %|| 'SCALE' }@206x1
% cosmo_disp([pl_layout.pos pl_layout.width pl_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
% pl_layout.name
% %|| 'neuromag306planar.lay'
% %
% % get layout for axial (magnetometer) channels
% mag_layout=cosmo_meeg_find_layout(ds,'chantype','meg_axial');
% cosmo_disp(mag_layout.label);
% %|| { 'MEG0111'
% %|| 'MEG0121'
% %|| 'MEG0131'
% %|| :
% %|| 'MEG2641'
% %|| 'COMNT'
% %|| 'SCALE' }@104x1
% %
% % get layout for planar channels, but add a 'parent' layout which has the
% % combined_planar channels
% combined_from_planar_layout=cosmo_meeg_find_layout(ds,'chantype',...
% 'meg_combined_from_planar');
% cosmo_disp(combined_from_planar_layout.label);
% %|| { 'MEG0113'
% %|| 'MEG0112'
% %|| 'MEG0122'
% %|| :
% %|| 'MEG2643'
% %|| 'COMNT'
% %|| 'SCALE' }@206x1
% cosmo_disp(combined_from_planar_layout.parent.label);
% %|| { 'MEG0112+0113'
% %|| 'MEG0122+0123'
% %|| 'MEG0132+0133'
% %|| :
% %|| 'MEG2642+2643'
% %|| 'COMNT'
% %|| 'SCALE' }@104x1
% cosmo_disp(combined_from_planar_layout.parent.child_label);
% %|| { { 'MEG0112'
% %|| 'MEG0113' }
% %|| { 'MEG0122'
% %|| 'MEG0123' }
% %|| { 'MEG0132'
% %|| 'MEG0133' }
% %|| :
% %|| { 'MEG2642'
% %|| 'MEG2643' }
% %|| { }
% %|| { } }@104x1
%
% See also: ft_prepare_neighbors, cosmo_meeg_chan_neighbors,
% cosmo_meeg_chan_neighborhood
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
defaults.chantype=[];
defaults.min_coverage=.2;
opt=cosmo_structjoin(defaults, varargin);
% get the sensor labels and channel types applicable to this dataset
chantype2senstype=get_dataset_senstypes(ds,opt);
% get the single channel type based on the input and available channels
ds_chantype=get_base_chantype(chantype2senstype,opt);
% get the sensor type corresponding with the channel type
senstype=chantype2senstype.(ds_chantype);
% use the mapping from senstype to layout to get the layout
senstype2layout=cosmo_meeg_senstype2layout_mapping();
layout=senstype2layout.(senstype);
% ensure that enough labels are covered in the dataset
ds_label=get_dataset_channel_label(ds);
coverage=label_coverage(ds_label(:),layout.label(:));
% no coverage, throw an error
if coverage<opt.min_coverage
error(['channel coverage %.1f%% < 100%% for %s. This means '...
'that the channel layout was not recognized based '...
'on the channel labels. Your options are:\n '...
'1) if this is a custom layout, define a neighbor '...
'struct with fields .label and neighblabel (similar '....
'to CoSMoMVPA''s ft_meeg_chan_neighbors and '...
'FieldTrip''s ft_prepare_neighbors), and provide this '...
'as the only input to cosmo_meeg_chan_neighborhood\n'...
'2) if this is a common MEG or EEG layout, please get '...
'in touch with the CoSMoMVPA developers to see if '...
'support for this layout can be added'], ...
100*coverage, ds_chantype);
end
% in case of planar channels with senstype set to
% meg_combined_from_planar, add a parent layout that maps to the
% original layout
is_planar_layout=isempty(cosmo_strsplit(ds_chantype,'_planar',-1));
if is_planar_layout && strcmp(opt.chantype,'meg_combined_from_planar')
parent_senstype=chantype2senstype.meg_combined_from_planar;
parent_layout=senstype2layout.(parent_senstype);
sens_label=get_senstype_label(senstype);
parent_sens_label=get_senstype_label(parent_senstype);
nlabels=numel(parent_layout.label);
parent_layout.child_label=cell(nlabels,1);
all_child_labels=cell(nlabels,1);
for k=1:nlabels
i=find(cosmo_match(parent_sens_label,parent_layout.label(k)));
if numel(i)~=1
parent_layout.child_label{k}=cell(0,1);
end
child_label=sort(sens_label(i,:));
all_child_labels{k}=child_label(:);
parent_layout.child_label{k}=child_label(:);
end
% sanity check
assert(cosmo_overlap({sens_label(:)},...
{cat(1,all_child_labels{:})})==1);
layout.parent=parent_layout;
end
function label=get_senstype_label(senstype)
sc=cosmo_meeg_senstype_collection();
label=sc.(senstype).label;
function senstype_mapping=get_dataset_senstypes(ds,opt)
% helper function to get supported senstypes
[unused,senstype_mapping]=cosmo_meeg_chantype(ds,opt);
keys=fieldnames(senstype_mapping);
if cosmo_match({'meg_planar'},keys)
planar_senstype=senstype_mapping.meg_planar;
planar_combined_senstype=[planar_senstype '_combined'];
sc=cosmo_meeg_senstype_collection();
if isfield(sc,planar_combined_senstype)
senstype_mapping.meg_combined_from_planar=...
planar_combined_senstype;
end
end
function c=label_coverage(x,y)
% helper function to compute coverage of labels by a layout
c=mean(cosmo_match(x(:),y(:)));
function chan_labels=get_dataset_channel_label(ds)
% helper function to get labels from dataset
if iscellstr(ds)
chan_labels=ds;
else
[dim, index, attr_name, dim_name]=cosmo_dim_find(ds,'chan',true);
chan_labels=ds.a.(dim_name).values{index};
end
function chantype=get_base_chantype(chantype2senstype, opt)
% helper function to get the base (i.e. the one
% returned in layout) channel type.
% (this is not the parent type)
has_chantype=ischar(opt.chantype) && ~isempty(opt.chantype);
chantypes=fieldnames(chantype2senstype);
has_key=@(key)cosmo_match({key},chantypes);
error_msg='';
if has_chantype
if strcmp(opt.chantype,'meg_combined_from_planar')
if has_key('meg_planar')
chantype='meg_planar';
else
error_msg=sprintf(['Cannot use senstype ''%s'' because '...
'meg_planar not available'],...
opt.chantype);
end
elseif ~has_key(opt.chantype);
error_msg=sprintf('chantype ''%s'' is not supported',...
opt.chantype);
else
chantype=opt.chantype;
end
else
if numel(chantypes)>1
error_msg=['''chantype'' argument is not provided, but '...
'multiple types are available'];
else
chantype=chantypes{1};
end
end
if ~isempty(error_msg)
error('%s. Set the ''chantype'' argument to one of: ''%s''.',...
error_msg,cosmo_strjoin(chantypes, ''', '''));
end
