function [dim, index, attr_name, dim_name, values]=cosmo_dim_find(ds, dim_label, raise)
% find dimension attribute in dataset
%
% [dim, index, attr_name, dim_name]=cosmo_dim_find(ds, dim_label[, raise])
%
% Inputs:
% ds dataset struct
% dim_label dimension label
% raise if true, raise an error if the dimension is not found.
% Default: false
%
% Outputs:
% dim dimension where dim_label was found, 1=sample
% dimension, 2=feature dimension
% index position where dim_label was found, so that:
% ds.a.(dim_name).values{index}==dim_label
% attr_name 'sa' if dim==1, 'fa' if dim==2
% dim_name 'sdim' if dim==1, 'fdim' if dim==2
% values the values associated with the dimension
%
% Examples:
% % fMRI dataset, find first voxel dimension
% ds=cosmo_synthetic_dataset('type','fmri');
% [dim, index, attr_name, dim_name, values]=cosmo_dim_find(ds,'i');
% disp(dim)
% %|| 2
% disp(index)
% %|| 1
% disp(attr_name)
% %|| fa
% disp(dim_name)
% %|| fdim
% cosmo_disp(values)
% %|| [ 1 2 3 ]
%
% % MEEG time-frequency dataset, find 'time' dimension
% ds=cosmo_synthetic_dataset('type','timefreq','size','big');
% [dim, index, attr_name, dim_name, values]=cosmo_dim_find(ds,'time');
% disp(dim)
% %|| 2
% disp(index)
% %|| 3
% disp(attr_name)
% %|| fa
% disp(dim_name)
% %|| fdim
% cosmo_disp(values)
% %|| [ -0.2000 -0.1500 -0.1000 -0.0500 0 ]
% %
% % move 'time' from feature to sample dimension
% dst=cosmo_dim_transpose(ds,'time',1);
% [dim, index, attr_name, dim_name, values]=cosmo_dim_find(dst,'time');
% disp(dim)
% %|| 1
% disp(index)
% %|| 1
% disp(attr_name)
% %|| sa
% disp(dim_name)
% %|| sdim
% cosmo_disp(values)
% %|| [ -0.2000 ; -0.1500 ; -0.1000 ; -0.0500 ; 0 ]
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
