function cosmo_plot_slices(data, dim, slice_step, slice_start, slice_stop)
% Plots a set of slices from a dataset, nifti image, or 3D data array
%
% cosmo_plot_slices(data[, dim][, slice_step][, slice_start][, slice_stop])
%
% Inputs:
% data an fmri dataset (e.g., from cosmo_fmri_dataset), or a 3D
% array with data. data should contain samples from a single
% volume (sample) only.
% dim dimension according to which slices are plotted
% (default: 3). Values between 1 and 3 allows using a
% saggital, axial or coronal view; but the mapping between
% the 3 numbers and 3 views depends on the particular
% orientation of the data.
% slice_step step between slices (default: 1). If negative then
% -slice_step indicates the number of slices
% slice_start the index of the first slice to plot (default: 1).
% slice_stop the index of the last slice to plot (default: the number of
% slices in the dim-th dimension).
%
% Examples:
% % plot an fMRI dataset struct with default options
% cosmo_plot_slices(ds)
%
% % plot an fMRI dataset struct along the second spatial dimension
% cosmo_plot_slices(ds, 2)
%
% % plot a random gaussian 3D array along the first dimension
% cosmo_plot_slices(randn([40,50,20]),1)
%
% % plot an fMRI dataset struct along the default spatial dimension
% % every 5-th slice
% cosmo_plot_slices(ds, [], 5)
%
% % plot an fMRI dataset struct along the third spatial dimension
% % with about 12 slices
% cosmo_plot_slices(ds, 3, -12)
%
% % plot an fMRI dataset struct along the third spatial dimension
% % with about 12 slices, starting at slice 10 and stopping at slice 25
% cosmo_plot_slices(ds, 3, -12, 10, 25)
%
% Notes:
% - Using this function only really makes sense for fMRI-like data.
% - This function does not provide a consistent orientation for slices,
% as this depends on the voxel-to-world transformation matrix, which is
% completely ignored in this function. Thus left-right and top-down
% swaps can occur. Different datasets may provide different views, for
% example dim=1 may give a saggital view if the dataset comes from one
% program and an axial view if it comes from another program.
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
