cosmo convert neighborhood hdrΒΆ

function conv_nbrhood=cosmo_convert_neighborhood(nbrhood, output_type)
% Converts between cell, matrix and struct representations of neighborhoods
%
% conv_nbrhood=cosmo_convert_neighborhood(nbrhood[, output_type])
%
% Inputs:
%     nbrhood               Either a cell, struct, or matrix with
%                           neighborhood information:
%                           - cell:    Nx1 with nbrhood{k} the indices of
%                                      the k-th neighborhood
%                           - struct:  with field .neighbors, which must
%                                      be a cell
%                           - matrix:  MxN with nbrhood(:,k) the indices of
%                                      the k-th neighborhood (non-positive
%                                      values indicating no index), with M
%                                      the maximum number of features in a
%                                      single neighborhood
%     output_type           Optional, one of 'cell', 'matrix', or
%                           'struct'.
%                           If empty or omitted, then output_type is set to
%                           'matrix', unless nbrhood is a matrix, in
%                           which case it is set to 'cell'.
% Output:
%     conv_nbrhood          Neighborhood information converted to cell,
%                           struct, or matrix (see above)
%
% Example:
%     ds=cosmo_synthetic_dataset();
%     nbrhood=cosmo_spherical_neighborhood(ds,'radius',1,'progress',false);
%     % show the neighbor indices
%     cosmo_disp(nbrhood.neighbors)
%     %|| { [ 1         4         2 ]
%     %||   [ 2         1         5         3 ]
%     %||   [ 3         2         6 ]
%     %||   [ 4         1         5 ]
%     %||   [ 5         4         2         6 ]
%     %||   [ 6         5         3 ]           }
%     %
%     % convert to matrix representation
%     mx=cosmo_convert_neighborhood(nbrhood,'matrix');
%     cosmo_disp(mx)
%     %|| [ 1         2         3         4         5         6
%     %||   4         1         2         1         4         5
%     %||   2         5         6         5         2         3
%     %||   0         3         0         0         6         0 ]
%     %
%     % convert to cell representation
%     neighbors=cosmo_convert_neighborhood(nbrhood,'cell');
%     cosmo_disp(neighbors)
%     %|| { [ 1         4         2 ]
%     %||   [ 2         1         5         3 ]
%     %||   [ 3         2         6 ]
%     %||   [ 4         1         5 ]
%     %||   [ 5         4         2         6 ]
%     %||   [ 6         5         3 ]           }
%
% Notes:
%    - the rationale of this function is that cell or struct
%      representations are more intuitive and possible more space
%      efficient, but also slower to access than matrix representations.
%      This function provides conversion between different representations.
%
% #   For CoSMoMVPA's copyright information and license terms,   #
% #   see the COPYING file distributed with CoSMoMVPA.           #