cosmo check neighborhoodΒΆ

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