function s=cosmo_map2surface(ds, fn, varargin)
% maps a dataset structure to AFNI/SUMA NIML dset or BV SMP file
%
% s=cosmo_map2surface(ds, output, ...)
%
% Inputs:
% ds dataset struct with surface-based data
% output String, indicating either the output format or the
% filename.
% - If output starts with a '-', then it must be one
% of:
% '-niml_dset' AFNI NIML
% '-bv_smp' BrainVoyager surface map
% '-gii' GIFTI
% - otherwise it must be a string indicating a file
% name, and end with one of
% '.niml.dset' AFNI NIML
% '.smp' BrainVoyager surface map
% '.gii' GIFTI
% 'encoding', e Optional encoding for AFNI NIML or GIFTI. Depending
% on the output format, supported values for e are:
% - NIML: 'ascii', 'binary',
% 'binary.lsbfirst', 'binary.msbfirst'
% (the 'binary' option uses the machine's native
% format with either the least or most significant
% byte first)
% - GIFTI: 'ASCII', 'Base64Binary',
% 'GZipBase64Binary'
% The encoding argument is ignored for BrainVoyager
% output.
% 'format', f Optional format to be used for output, if the
% output argument empty; one of 'niml_dset', 'bv_smp'
% or 'gii'.
%
% Output:
% s Structure containing the surface based data based
% on the output format; either a struct with
% NIML data, an xff object, or a GIFTI object.
%
% Examples:
% % (this example requires the AFNI Matlab toolbox)
% cosmo_skip_test_if_no_external('afni');
% %
% ds=cosmo_synthetic_dataset('type','surface');
% %
% % convert to AFNIML NIML format
% % (to store a file to disc, use a filename as the second argument)
% niml=cosmo_map2surface(ds,'-niml_dset');
% cosmo_disp(niml);
% %|| .node_indices
% %|| [ 0 1 2 3 4 5 ]
% %|| .data
% %|| [ 2.03 0.584 -1.44 -0.518 1.19 -1.33
% %|| -0.892 1.84 -0.262 2.34 -0.204 2.72
% %|| -0.826 1.17 -1.92 0.441 -0.209 0.148
% %|| 1.16 -0.848 3.09 1.86 1.76 0.502
% %|| 1.16 3.49 -1.37 0.479 -0.955 3.41
% %|| -1.29 -0.199 1.73 0.0832 0.501 -0.48 ]
%
% 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
% - To load surface datasets, use cosmo_surface_dataset
%
% 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: https://github.com/afni/AFNI
%
% See also: cosmo_surface_dataset
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
if ~ischar(fn)
error('second argument must be a string');
end
defaults=struct();
opt=cosmo_structjoin(defaults,varargin);
cosmo_check_dataset(ds,'surface');
formats=get_formats();
sp=cosmo_strsplit(fn,'-');
save_to_file=~isempty(sp{1});
if isfield(opt,'format')
fmt=opt.format;
elseif save_to_file
fmt=get_format(formats, fn);
else
if numel(sp)~=2
error('expected -{FORMAT}');
end
fmt=sp{2};
end
if ~isfield(formats,fmt)
error('Unsupported format %s', fmt);
end
format=formats.(fmt);
externals=format.externals;
cosmo_check_external(externals);
builder=format.builder;
s=builder(ds);
if nargout==0
cleaner=onCleanup(get_cleaner(format,s));
end
if save_to_file
writer=format.writer;
writer(fn, s, opt);
end
function f=get_cleaner(format,obj)
if isfield(format,'cleaner')
f=@()format.cleaner(obj);
else
f=@do_nothing;
end
function do_nothing()
% do nothing
function format=get_format(formats,fn)
endswith=@(s,e) isempty(cosmo_strsplit(s,e,-1));
names=fieldnames(formats);
for k=1:numel(names)
name=names{k};
exts=formats.(name).exts;
for j=1:numel(exts)
if endswith(fn,exts{j})
format=name;
return
end
end
end
error('Unsupported extension in %s', fn);
function formats=get_formats()
formats=struct();
formats.niml_dset.exts={'.niml.dset'};
formats.niml_dset.builder=@build_niml_dset;
formats.niml_dset.writer=@write_niml_dset;
formats.niml_dset.externals={'afni'};
formats.bv_smp.exts={'.smp'};
formats.bv_smp.builder=@build_bv_smp;
formats.bv_smp.writer=@write_bv_smp;
formats.bv_smp.cleaner=@(x)x.ClearObject();
formats.bv_smp.externals={'neuroelf'};
formats.gii.exts={'.gii'};
formats.gii.builder=@build_gifti;
formats.gii.writer=@write_gifti;
formats.gii.externals={'gifti'};
formats.pymvpa.exts={};
formats.pymvpa.builder=@build_pymvpa;
formats.pymvpa.writer=@write_pymvpa_struct;
formats.pymvpa.externals={};
function [data, node_indices]=get_surface_data_and_node_indices(ds)
[data, dim_labels, dim_values]=cosmo_unflatten(ds);
if ~isequal(dim_labels,{'node_indices'})
error('.a.fdim.labels must be {''node_indices''}');
end
node_indices=dim_values{1}(:)';
function p=build_pymvpa(ds)
p=ds;
% remove samples field
p=rmfield(p,'samples');
[data, node_indices]=get_surface_data_and_node_indices(ds);
p.samples=data;
node_indices_base0=int64(node_indices-1);
p.fa.node_indices=node_indices_base0;
p.a=rmfield(p.a,'fdim');
function write_pymvpa_struct(fn,m,opt)
save(fn,'-struct','m');
function g=build_gifti(ds)
s=struct();
[data, node_indices]=get_surface_data_and_node_indices(ds);
s.indices=node_indices(:);
s.cdata=data';
g=gifti(s);
function write_gifti(fn,g,opt)
if isfield(opt,'encoding')
args={opt.encoding};
else
args={};
end
save(g,fn,args{:});
function s=build_niml_dset(ds)
[data, node_indices]=get_surface_data_and_node_indices(ds);
s=struct();
s.node_indices=node_indices-1; % base 1 -> base 0
s.data=data';
if isfield(ds,'sa')
if isfield(ds.sa,'labels');
s.labels=ds.sa.labels;
end
if isfield(ds.sa,'stats');
s.stats=ds.sa.stats;
end
end
function write_niml_dset(fn,s,opt)
if isfield(opt, 'encoding')
args={opt.encoding};
else
args={};
end
afni_niml_writesimple(s, fn, args{:});
function s=build_bv_smp(ds)
[nsamples,nfeatures]=size(ds.samples);
[data, node_indices]=get_surface_data_and_node_indices(ds);
if ~isequal(node_indices,1:nfeatures)
error(['BrainVoyager smp only support data with all node '...
'present and with .a.fdim.values{1}=1:N, where N '...
'is the number of nodes']);
end
stats=cosmo_statcode(ds,'bv');
maps=cell(1,nsamples);
for k=1:nsamples
t=xff('new:smp');
map=t.Map;
t.ClearObject();
map.SMPData=data(k,:);
if k==1
% store the number of features
% note: unlike the niml_dset implementation, data is stored
% for all nodes, even if some node indices did not have a value
% originally
nfeatures=numel(map.SMPData);
end
if isfield(ds,'sa')
if isfield(ds.sa,'labels')
map.Name=ds.sa.labels{k};
end
if ~isempty(stats) && ~isempty(stats{k})
map=cosmo_structjoin(map, stats{k});
end
end
if ~isempty(stats) && ~isempty(stats{k})
map=cosmo_structjoin(map, stats{k});
end
map.BonferroniValue=nfeatures;
maps{k}=map;
end
s=xff('new:smp');
s.Map=cat(2,maps{:});
s.NrOfMaps=nsamples;
s.NrOfVertices=nfeatures;
neuroelf_bless_wrapper(s);
function write_bv_smp(fn,s,opt)
s.SaveAs(fn);
function result=neuroelf_bless_wrapper(arg)
% deals with recent neuroelf (>v1.1), where bless is deprecated
s=warning('off','neuroelf:xff:deprecated');
resetter=onCleanup(@()warning(s));
result=bless(arg);
