function [indices_cell, ds_intersect_cell]=cosmo_mask_dim_intersect(ds_cell,dim,varargin)
% find intersection mask across a set of datasets
%
% [indices, ds_intersect_cell]=cosmo_mask_dim_intersect(ds_cell[,dim])
%
% Inputs:
% ds_cell Kx1 cell with datasets with feature
% [sample] dimensions (for dim==1 [dim==2]),
% with no feature [sample] location repeated
% dim (optional) dimension along which to form
% the mask (default: 2)
%
% Output:
% indices_cell Kx1 cell containing maximal sets of indices
% of features [or samples] that can be
% (if dim==1) from ds_cell so that all
% features [or samples] of the respective
% input datasets are shared
% across all input datasets.
% ds_intersect_cell The result of slicing each of the input
% dataset, i.e.
% ds_intersect_cell{k}=
% cosmo_slice(ds_cell{k},dim)
%
% Example:
% %generate full (but tiny) fMRI dataset
% ds_full=cosmo_synthetic_dataset('seed',1);
% %
% % make two datasets with different subsets of voxels
% ds1=cosmo_slice(ds_full,[2 5 3 1],2);
% ds2=cosmo_slice(ds_full,[5 1 4 6 2],2);
% %
% % trying to stack these along the sample dimension gives an error,
% % because the feature attributes do not match
% result=cosmo_stack({ds1,ds2},1);
% %|| error('size mismatch along dimension 2 ...')
% %
% % find indices for common mask
% [idx_cell,ds_int_cell]=cosmo_mask_dim_intersect({ds1,ds2});
% %
% % show slice-arg indices required for each of the two datasets
% % to select features (voxels) common across the two datasets;
% % in this case there are 3 voxels in common
% cosmo_disp(idx_cell);
% %|| { [ 4 1 2 ]
% %|| [ 2 5 1 ] }
% %
% % when slicing using the indices, the dimension feature attributes
% % (here: voxel coordinates) are identical
% % note: ds_int_cell is equivalent to ds1_sel and ds2_cell
% ds1_sel=cosmo_slice(ds1,idx_cell{1},2);
% ds2_sel=cosmo_slice(ds2,idx_cell{2},2);
% % show voxel coordinates for the two datasets
% cosmo_disp({ds1_sel.fa,ds2_sel.fa});
% %|| { .i .i
% %|| [ 1 2 2 ] [ 1 2 2 ]
% %|| .j .j
% %|| [ 1 1 2 ] [ 1 1 2 ]
% %|| .k .k
% %|| [ 1 1 1 ] [ 1 1 1 ] }
% %
% % because the feature attribtues match, they can now be stacked
% result=cosmo_stack(ds_int_cell,1);
% disp(size(result.samples))
% %|| [12,3]
%
%
% Notes:
% - A typical use case is finding an intersection mask between
% volumetric fMRI datasets that have most, but not all, voxels in
% common - for example, through using individual brain masks.
%
% See also: cosmo_slice
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
