function ds=cosmo_fmri_reorient(ds, new_orient)
% Change the orientation of an fmri dataset
%
% ds_reorient=cosmo_fmri_reorient(ds, new_orient)
%
% Inputs
% ds fmri-dataset
% new_orient new orientation for the dataset (see below for a
% full list)
%
% Example:
% ds=cosmo_synthetic_dataset();
% cosmo_disp(ds.a);
% %|| .fdim
% %|| .labels
% %|| { 'i' 'j' 'k' }
% %|| .values
% %|| { [ 1 2 3 ] [ 1 2 ] [ 1 ] }
% %|| .vol
% %|| .mat
% %|| [ 2 0 0 -3
% %|| 0 2 0 -3
% %|| 0 0 2 -3
% %|| 0 0 0 1 ]
% %|| .dim
% %|| [ 3 2 1 ]
% %|| .xform
% %|| 'scanner_anat'
% cosmo_disp(ds.fa);
% %|| .i
% %|| [ 1 2 3 1 2 3 ]
% %|| .j
% %|| [ 1 1 1 2 2 2 ]
% %|| .k
% %|| [ 1 1 1 1 1 1 ]
% ds_reorient=cosmo_fmri_reorient(ds,'AIR');
% cosmo_disp(ds_reorient.a);
% %|| .fdim
% %|| .labels
% %|| { 'i' 'j' 'k' }
% %|| .values
% %|| { [ 1 2 ] [ 1 ] [ 1 2 3 ] }
% %|| .vol
% %|| .mat
% %|| [ 0 0 -2 5
% %|| -2 0 0 3
% %|| 0 2 0 -3
% %|| 0 0 0 1 ]
% %|| .dim
% %|| [ 2 1 3 ]
% %|| .xform
% %|| 'scanner_anat'
% cosmo_disp(ds_reorient.fa);
% %|| .i
% %|| [ 1 2 1 2 1 2 ]
% %|| .j
% %|| [ 1 1 1 1 1 1 ]
% %|| .k
% %|| [ 1 1 2 2 3 3 ]
%
% % Many orientations are invalid, for example
% ds=cosmo_synthetic_dataset();
% cosmo_reorient(ds,'ALR');
% error('illegal orientation');
%
% Notes:
% - there are 3!*3^2 valid orientations, these are:
% 'SAR' 'SAL' 'SPR' 'SPL' 'IAR' 'IAL' 'IPR' 'IPL'
% 'SRA' 'SLA' 'SRP' 'SLP' 'IRA' 'ILA' 'IRP' 'ILP'
% 'ASR' 'ASL' 'PSR' 'PSL' 'AIR' 'AIL' 'PIR' 'PIL'
% 'ARS' 'ALS' 'PRS' 'PLS' 'ARI' 'ALI' 'PRI' 'PLI'
% 'RAS' 'LAS' 'RPS' 'LPS' 'RAI' 'LAI' 'RPI' 'LPI'
% 'RSA' 'LSA' 'RSP' 'LSP' 'RIA' 'LIA' 'RIP' 'LIP'
% For example, 'LPI' (used in Talairach/MNI) means that
% * the first dimension goes from left to right
% * the second dimension goes from posterior to anterior
% * the third dimension goes from inferior to superior
% - this function chances the orientation information by adjusting
% information in .fa and .a.fdim; contents of .samples remains
% unchanged.
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
