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
