function is_ok=cosmo_check_neighborhood(nbrhood,varargin)
% check that a neighborhood is kosher
%
% is_ok=cosmo_check_neighborhood(nbrhood,[raise])
%
% Inputs:
% nbrhood neighborhood struct, for example from
% cosmo_spherical_neighborhood,
% cosmo_surficial_neighborhood,
% surfing_interval_neighborhood, or
% cosmo_meeg_chan_neighborhood
% raise (optional) if set to true (the default), an
% error is thrown if nbrhood is not kosher
% 'show_warning',w If true (the default), then a warning is shown
% if nbrhood has no origin
%
% Output:
% is_ok true if nbrhood is kosher, false otherwise
%
%
% Examples:
% ds=cosmo_synthetic_dataset();
% nbrhood=cosmo_spherical_neighborhood(ds,'radius',1,'progress',false);
% cosmo_check_neighborhood(nbrhood)
% %|| true
% %
% cosmo_check_neighborhood(2)
% %|| error('neighborhood is not a struct')
% %
% % error can be silenced
% cosmo_check_neighborhood(2,false)
% %|| false
% %
% fa=nbrhood.fa;
% nbrhood=rmfield(nbrhood,'fa');
% cosmo_check_neighborhood(nbrhood)
% %|| error('field ''fa'' missing in neighborhood')
% %
% nbrhood.fa=fa;
% nbrhood.neighbors{2}=-1;
% cosmo_check_neighborhood(nbrhood)
% %|| error('.neighbors{2} is not a row vector with integers')
% %
% nbrhood.neighbors{2}=[1];
% nbrhood.fa.chan=[3 2 1];
% cosmo_check_neighborhood(nbrhood)
% %|| error('fa.chan has 3 values in dimension 2, expected 6')
%
% See also: cosmo_spherical_neighborhood, surfing_interval_neighborhood
% cosmo_surficial_neighborhood, cosmo_meeg_chan_neighborhood
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
[raise, ds, show_warning]=process_input(varargin{:});
is_ok=false;
checkers={@check_basis,...
@check_neighbors,...
@check_origin_matches};
for j=1:numel(checkers)
checker=checkers{j};
msg=checker(nbrhood, ds, show_warning);
if ~isempty(msg)
if raise
error([func2str(checker) ': ' msg]);
end
return
end
end
% treat like dataset
nfeatures=numel(nbrhood.neighbors);
nbrhood=rmfield(nbrhood,'neighbors');
if isfield(nbrhood,'fa')
nbrhood.samples=zeros(0,nfeatures);
else
nbrhood.samples=zeros(nfeatures,0);
end
if isfield(nbrhood,'origin')
nbrhood=rmfield(nbrhood,'origin');
end
is_ok=cosmo_check_dataset(nbrhood,raise);
function [infix, absent_infix]=get_attr_infix(nbrhood)
m=cosmo_match({'sa','fa'},fieldnames(nbrhood));
if sum(m)~=1
error('exactly one of .sa or .fa must be present');
end
if m(1)
infix='s';
absent_infix='f';
else
infix='f';
absent_infix='s';
end
function msg=check_basis(nbrhood, ds, show_warning)
msg='';
if ~isstruct(nbrhood)
msg='neighborhood is not a struct';
return
end
keys={'neighbors','a','fa','sa','origin'};
delta=setdiff(fieldnames(nbrhood),keys);
if ~isempty(delta)
first=delta{1};
msg=sprintf('field ''%s'' not allowed in neighborhood',first);
return
end
if ~isfield(nbrhood,'neighbors')
error('missing field .neighbors');
end
function tf=is_positive_int_row_vector(x)
tf=isempty(x) || ...
(size(x,1)==1 && min(x)>=1 && all(round(x)==x));
function msg=check_neighbors(nbrhood, ds, show_warning)
msg='';
nbrs=nbrhood.neighbors;
if ~iscell(nbrs)
msg='.neighbors is not a cell';
return;
end
if size(nbrs,2)~=1
msg='.neighbors is not of size Kx1';
return;
end
has_dataset=~isempty(ds);
if has_dataset
infix=get_attr_infix(nbrhood);
switch infix
case 's'
dim=1;
case 'f'
dim=2;
end
max_feature=size(ds.samples,dim);
else
max_feature=Inf;
end
for j=1:numel(nbrs)
nbr=nbrs{j};
if any(nbr>max_feature)
msg=sprintf(['.neighbors{%d} exceeds the number '...
'of features (%d) in the dataset']',...
j, max_feature);
return
end
if ~is_positive_int_row_vector(nbr)
msg=sprintf('.neighbors{%d} is not an integer row vector',j);
return;
end
end
function msg=check_origin_matches(nbrhood, ds, show_warning)
msg='';
% legacy neighborhood, do not throw an exception
if show_warning && ~isfield(nbrhood,'origin')
cosmo_warning(['Legacy warning: newer versions of CoSMoMVPA '...
'require a field .origin in the neighborhood '...
'struct']);
return;
end
if isempty(ds)
% no dataset, so no further checks
return;
end
origin=nbrhood.origin;
[infix, absent_infix]=get_attr_infix(nbrhood);
dim_name=[infix 'dim'];
if isfield(origin, 'a')
origin_a=origin.a;
if isfield(ds,'a')
ds_a=ds.a;
if isfield(ds_a,dim_name)
if isfield(origin_a,dim_name)
msg=check_xdim_matches(origin_a.(dim_name), ...
ds_a.(dim_name), ...
dim_name);
if ~isempty(msg)
return;
end
msg=check_xa_matches(origin,ds,infix);
if ~isempty(msg)
return;
end
origin_a=rmfield(origin_a,dim_name);
end
ds_a=rmfield(ds_a,dim_name);
end
if ~cosmo_isequaln(origin_a, ds_a)
error('.a mismatch between dataset and neighborhood');
end
end
end
function msg=check_xa_matches(origin,ds,infix)
msg='';
attr_name=[infix 'a'];
dim_name=[infix 'dim'];
keys=origin.a.(dim_name).labels;
for k=1:numel(keys)
key=keys{k};
if ~cosmo_isfield(origin,[attr_name '.' key]) || ...
~cosmo_isequaln(ds.(attr_name).(key),...
origin.(attr_name).(key))
msg=sprintf(['.%sa.%s mismatch between dataset and '...
'neighborhood'],infix,key);
return
end
end
function msg=check_xdim_matches(origin_xdim, ds_xdim, dim_name)
msg='';
keys=fieldnames(ds_xdim);
if ~isequal(sort(keys),sort(fieldnames(origin_xdim)))
msg=sprintf(['.a.%s key mismatch between dataset '...
'and neighborhood'], dim_name);
return;
end
for k=1:numel(keys)
key=keys{k};
origin_v=origin_xdim.(key);
ds_v=ds_xdim.(key);
if ~(iscell(origin_v) && iscell(ds_v))
msg=sprintf('.a.%s ''%s'' must be a cell',...
dim_name, key);
return
end
if numel(origin_v)~=numel(ds_v)
msg=sprintf(['.a.%s size mismatch between ',...
'dataset and neighborhood'],...
dim_name, key);
return
end
for j=1:numel(origin_v)
if ~(cosmo_isequaln(origin_v{j},ds_v{j}) || ...
cosmo_isequaln(origin_v{j},ds_v{j}'))
msg=sprintf(['.a.%s ''%s'' value mismatch '...
'between dataset and neighborhood'], ...
dim_name, key);
return
end
end
end
function [raise, ds, show_warning]=process_input(varargin)
raise=true;
ds=[];
show_warning=true;
narg=numel(varargin);
k=0;
while k<narg
k=k+1;
arg=varargin{k};
if islogical(arg)
raise=arg;
elseif isstruct(arg)
ds=arg;
cosmo_check_dataset(ds);
elseif ischar(arg)
if k==narg
error('missing argument after ''show_warning''');
end
switch arg
case 'show_warning'
k=k+1;
show_warning=varargin{k};
otherwise
error('illegal argument at position %d', k);
end
end
end
