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. #
