function ds=cosmo_surface_dataset(fn, varargin)
% Returns a dataset structure based on surface mesh data
%
% ds=cosmo_surface_dataset(filename, varargin)
%
% Inputs:
% filename filename of surface data to be loaded. Currently
% supported are '.niml.dset' (AFNI/SUMA NIML),
% 'smp' (BrainVoyager surface maps), and 'gii' (GIFTI).
% Also supported are structs as provided by
% afni_niml_readsimple, or objects provided by xff or
% the MATLAB/Octave GIfTI Library.
% 'targets', t Px1 targets for P samples; these will be stored in
% the output as ds.sa.targets
% 'chunks', c Px1 chunks for P samples; these will be stored in the
% the output as ds.sa.chunks
% Output:
% ds dataset struct
%
% Examples:
% % (this example requires the surfing toolbox)
% cosmo_skip_test_if_no_external('afni');
% %
% % construct AFNI NIML dataset struct
% cosmo_check_external('afni');
% niml=struct();
% niml.data=[1 2; 3 4; 5 6];
% niml.node_indices=[1 20 201];
% niml.stats={'Ttest(10)','Zscore()'};
% %
% % make surface dataset
% % (a filename of a NIML dataset in ASCII format is supported as well)
% ds=cosmo_surface_dataset(niml);
% cosmo_disp(ds)
% %|| .samples
% %|| [ 1 3 5
% %|| 2 4 6 ]
% %|| .sa
% %|| .stats
% %|| { 'Ttest(10)'
% %|| 'Zscore()' }
% %|| .fa
% %|| .node_indices
% %|| [ 1 2 3 ]
% %|| .a
% %|| .fdim
% %|| .labels
% %|| { 'node_indices' }
% %|| .values
% %|| { [ 2 21 202 ] }
%
%
% Notes:
% - this function is intended for datasets with surface data, i.e. with
% one or more values associated with each surface node. It does not
% support anatomical surface meshes that contain node coordinates and
% faces. To read and write such anatomical meshes, consider the surfing
% toolbox, github.com/nno/surfing
% - data can be mapped back to a surface file format using
% cosmo_map2surface
%
% Dependencies:
% - for Brainvoyager files (.smp), it requires the NeuroElf
% toolbox, available from: http://neuroelf.net
% - for AFNI/SUMA NIML files (.niml.dset) it requires the AFNI
% Matlab toolbox, available from: http://afni.nimh.nih.gov/afni/matlab/
% - for GIFTI files (.gii) it requires the MATLAB/Octave GIfTI Library,
% available from https://github.com/gllmflndn/gifti
%
% See also: cosmo_map2surface
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
