function is_ok=cosmo_check_dataset(ds, ds_type, error_if_not_ok)
% Check consistency of a dataset.
%
%
% is_ok=cosmo_dataset_check(ds, [ds_type,][,error_if_not_ok])
%
% Inputs:
% ds dataset struct.
% ds_type string indicating the specific type of dataset.
% Currently supports 'fmri' and 'meeg'.
% error_if_not_ok if true (the default) or a string, an error is
% raised if the dataset is not kosher (see below).
% If a string, then it is prefixed in the error
% message. If false, then no error is raised.
%
% Returns:
% is_ok boolean indicating kosherness of ds.
% It is consider ok if:
% - it has a field .samples with a PxQ array.
% - if it has a field .features [.samples], then
% it should be a struct, and each field in it
% should have P [Q] elements along the first
% [second] dimension or be empty.
% - .sa.{targets,chunks} are numeric vectors with
% integers (if present)
% - if ds_type is provided, then some more tests
% (depending on ds_type) are performed.
%
% Examples:
% cosmo_check_dataset([])
% %|| error('dataset not a struct')
%
% cosmo_check_dataset(struct())
% %|| error('dataset has no field .samples')
%
% % this (very minimal) dataset is kosher
% cosmo_check_dataset(struct('samples',zeros(2)))
% %|| true
%
% % error can be silenced
% cosmo_check_dataset('this is not ok',false)
% %|| false
%
% % run some more tests
% ds=cosmo_synthetic_dataset('type','fmri');
% cosmo_check_dataset(ds)
% %|| true
% ds.sa.chunks=[2;3]; % wrong size
% cosmo_check_dataset(ds)
% %|| error('sa.chunks has 2 values in dimension 1, expected 6')
% ds.sa.chunks={'a','b','c','a','b','c'}';
% cosmo_check_dataset(ds)
% %|| error('.sa.chunks must be numeric vector with integers')
%
% % set illegal dimension values
% ds=cosmo_synthetic_dataset('type','fmri');
% ds.a.fdim.values{1}=[1 2];
% cosmo_check_dataset(ds)
% %|| error('.fa.i must be vector with integers in range 1..2')
%
% % check for specific type of dataset
% ds=cosmo_synthetic_dataset('type','fmri');
% cosmo_check_dataset(ds,'meeg')
% %|| error('missing field .a.meeg for meeg-dataset');
%
% % destroy crucial information in fmri dataset
% % this error is only caught if explicit checking for fmri dataset is
% % enabled, because the dataset remains valid when considered as a
% % non-fmri dataset
% ds=cosmo_synthetic_dataset('type','fmri');
% % destroy volume information
% ds.a=rmfield(ds.a,'vol');
% cosmo_check_dataset(ds)
% %|| true % error not caught
% cosmo_check_dataset(ds,'fmri')
% %|| error('missing field .a.vol for fmri-dataset')
%
% % check meeg dataset
% ds=cosmo_synthetic_dataset('type','meeg');
% cosmo_check_dataset(ds,'meeg')
% %|| true
% ds.fa.chan=ds.fa.chan+6; % outside range
% cosmo_check_dataset(ds)
% %|| error('.fa.chan must be vector with integers in range 1..3')
%
% Notes:
% - if the second argument is a boolean then its value is used for
% error_if_not_ok, and ds_type is not used
% - this function throws one error at most, even if it is inconsistent for
% several reasons.
% - it is good practice to use this function when a new dataset is created
% to ensure consistency of the data
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
% deal with input arguments
if nargin<3
error_if_not_ok=true;
end
if nargin>=2
if islogical(ds_type)
error_if_not_ok=ds_type;
ds_type=[];
end
else
ds_type=[];
error_if_not_ok=true;
end
if ischar(error_if_not_ok)
error_prefix=error_if_not_ok;
error_if_not_ok=true;
else
error_prefix='';
end
% list check functions
checkers={@check_fields,...
@check_samples,...
@check_targets,...
@check_chunks,...
@check_attributes,...
@check_dim_legacy,...
@check_dim,...
[]}; % space for check_with_type
if ~isempty(ds_type)
% add checker for specific type (fmri, meeg, surface)
checkers{end}=@(x) check_with_type(x,ds_type);
end
msg=run_checkers(checkers,ds);
is_ok=isempty(msg);
if ~is_ok && error_if_not_ok
error('%s: %s', error_prefix, msg);
end
function msg=run_checkers(checkers,ds)
n=numel(checkers);
msg='';
for k=1:n
checker=checkers{k};
if isempty(checker)
continue;
end
msg=checker(ds);
if ~isempty(msg)
return
end
end
function msg=check_with_type(ds, ds_type)
% additional checks for fmri, surface or meeg dataset
% note: check_dim should have already checked that
% all fields are present in .fa
msg='';
switch ds_type
case 'fmri'
required_dim_labels={'i','j','k'};
a_fields={'vol'};
case 'surface'
required_dim_labels={'node_indices'};
a_fields={};
case 'meeg'
required_dim_labels={};
a_fields={'meeg'};
otherwise
error('Unsupported ds_type=%s', ds_type);
end
% check present of .a.fdim field
if ~cosmo_isfield(ds, 'a.fdim', false);
msg='missing field .a.fdim';
return;
end
m=cosmo_match(required_dim_labels,ds.a.fdim.labels);
if any(~m)
i=find(~m,1);
msg=sprintf('missing value %s in .a.fdim.values for %s-dataset',...
required_dim_labels{i}, ds_type);
return
end
a_fns=fieldnames(ds.a);
m=cosmo_match(a_fields,a_fns);
if any(~m)
i=find(~m,1);
msg=sprintf('missing field .a.%s for %s-dataset',...
a_fields{i}, ds_type);
return
end
function tf=is_int_vector(x)
tf=isnumeric(x) && isvector(x) && all(round(x)==x | isnan(x));
function msg=check_dim_legacy(ds)
msg='';
if cosmo_isfield(ds,'a.dim')
msg=sprintf(['***CoSMoMVPA legacy***\n'...
'Feature dimension information is now stored '...
'in .a.fdim, whereas earlier versions used .a.dim. '...
'To adapt a existing dataset struct ''ds'', run:\n'...
' ds.a.fdim=ds.a.dim;\n'...
' ds.a=rmfield(ds.a,''dim'')\n']);
return;
end
function msg=check_fields(ds)
msg='';
if ~isstruct(ds)
msg='input must be a struct';
return;
end
delta=setdiff(fieldnames(ds),{'samples','fa','sa','a'});
if ~isempty(delta)
msg=sprintf('illegal field .%s', delta{1});
return
end
function msg=check_targets(ds)
msg='';
if cosmo_isfield(ds,'sa.targets') && ~is_int_vector(ds.sa.targets)
msg=['.sa.targets must be numeric vector with integers '...
'(.sa.labels can be used to store string labels)'];
end
function msg=check_chunks(ds)
msg='';
if cosmo_isfield(ds,'sa.chunks') && ~isnumeric(ds.sa.chunks)
msg='.sa.chunks must be numeric vector with integers';
end
function msg=check_samples(ds)
msg='';
if ~isfield(ds,'samples')
msg='dataset has no field .samples';
return
end
% has samples, so check the rest
ds_size=size(ds.samples);
if numel(ds_size) ~=2,
msg=sprintf('.samples should be 2D, found %dD', numel(ds_size));
return
end
function msg=check_attributes(ds)
msg='';
attrs_fns={'sa','fa'};
ds_size=size(ds.samples);
% check sample and feature attributes
for dim=1:2
attrs_fn=attrs_fns{dim};
if isfield(ds, attrs_fn);
% get feature/sample attributes
attrs=ds.(attrs_fn);
fns=fieldnames(attrs);
n=numel(fns);
% check each one
for j=1:n
fn=fns{j};
attr=attrs.(fn);
if isempty(attr)
continue;
end
attr_size=size(attr);
if numel(attr_size) ~= 2
msg=sprintf('%s.%s should be 2D', attrs_fn, fn);
return
end
if attr_size(dim) ~= ds_size(dim)
msg=sprintf(['%s.%s has %d values in dimension '...
'%d, expected %d'], attrs_fn, fn,...
attr_size(dim), dim, ds_size(dim));
if attr_size(3-dim) == ds_size(dim)
msg=[msg ' (maybe the data was intended '...
'to be transposed?)'];
end
return
end
end
end
end
function msg=check_dim(ds)
% helper function to check dataset with dimensions
% (i.e., .a.{s,f}dim is present)
msg='';
suffixes='sf';
for dim=1:2
suffix=suffixes(dim);
dim_attrs_str=sprintf('a.%sdim',suffix);
if ~cosmo_isfield(ds,dim_attrs_str)
continue;
end
attrs_str=[suffix 'a'];
if ~isfield(ds, attrs_str)
msg=sprintf('Missing field .%s',attrs_str);
return
end
attrs=ds.(attrs_str);
dim_attrs=ds.a.([suffix 'dim']);
msg=check_dim_helper(attrs, dim_attrs, attrs_str, dim_attrs_str);
if ~isempty(msg)
return
end
end
function msg=check_dim_helper(attrs, dim_attrs, attrs_str, dim_attrs_str)
msg='';
% attrs is from .sa or .fa; dim_attrs from .a.sdim or .a.fdim
% the *_str arguments contain a string representation
if ~all(cosmo_isfield(dim_attrs,{'labels','values'}))
msg=sprintf('Missing field .%s.{labels,values}',dim_attrs_str);
return;
end
labels=dim_attrs.labels;
values=dim_attrs.values;
if ~iscellstr(labels)
msg=sprintf('.%s.labels must be a cell', dim_attrs_str);
return
end
if ~iscell(values)
msg=sprintf('.%s.values must be a cell', dim_attrs_str);
return
end
ndim=numel(labels);
if numel(values)~=ndim
msg=sprintf('size mismatch between .%s.labels and .%s.values',...
dim_attrs_str,dim_attrs_str);
return
end
for dim=1:ndim
label=labels{dim};
if ~isfield(attrs, label)
msg=sprintf('Missing field .%s.%s', attrs_str, label);
return
end
v=attrs.(label);
% empty vectors are allowed (in empty datasets)
if isempty(v)
continue
end
vmax=numel(values{dim});
all_int=is_int_vector(v);
if ~all_int || min(v)<1 || max(v)>vmax
msg=sprintf(['.%s.%s must be vector with integers in '...
'range 1..%d'],attrs_str,label,vmax);
if all_int && min(v)==0
% could be mistaken base-0 indexing
msg=sprintf(['%s\nThe lowest index is 0, which may '...
'indicate base-0 indexing (the first '...
'element is indexed by 0). Note that '...
'Matlab (and CoSMoMVPA) use base-1 '...
'indexing.\n'...
'- Manual conversion from base-0 to '...
'base-1 can be achieved by increasing '...
'the values in .%s.%s by 1.\n'...
'- If this dataset was exported from '...
'PyMVPA and contains fMRI volumetric '...
'or surface-based data, consider using '...
'cosmo_fmri_dataset or '...
'cosmo_surface_dataset (respectively) '...
'to convert PyMVPA''s base-0 indexing to '...
'CoSMoMVPA''s base-1 indexing'],...
msg,attrs_str,label);
end
return
end
end
