function ds=cosmo_slice(ds, to_select, dim, type_or_check)
% Slice a dataset by samples (the default) or features
%
% sliced_ds=cosmo_slice(ds, elements_to_select[, dim][check|'struct'])
%
% Inputs:
%   ds                    One of:
%                         - dataset struct to be sliced, with PxQ field
%                           .samples and optionally fields .fa, .sa and .a.
%                         - PxQ cell
%                         - PxQ logical or numeric array
%   elements_to_select    either a binary mask or a list of indices of
%                         the samples (if dim==1) or features (if dim==2)
%                         to select. If a binary mask then the number of
%                         elements should match the size of ds in the
%                         dim-th dimension.
%   dim                   Slicing dimension: along samples (dim==1) or
%                         features (dim==2). (default: 1).
%   check                 Boolean that indicates that if ds is a dataset,
%                         whether it should be checked for proper
%                         structure. (default: true).
%   'struct'              If provided and ds is a struct, then
%                         all fields of ds, which are assumed to be cell
%                         or arrays,  are sliced.
%
% Output:
%   sliced_ds             - If ds is a cell or array then sliced_ds is
%                           the result of slicing ds along the dim-th
%                           dimension. The result is of size NxQ (if
%                           dim==1) or PxN (if dim==2), where N is the
%                           number of non-zero values in
%                           elements_to_select.
%                         - If ds is a dataset struct then
%                           sliced_ds.samples is the result of slicing
%                           ds.samples.
%                           If present, fields .sa (if dim==1) or
%                           .fa (dim==2) are sliced as well.
%                         - when ds is a struct and the 'struct' option was
%                           given, then all fields in ds are sliced.
%
% Examples:
%     % make a simple dataset
%     ds=struct();
%     ds.samples=reshape(1:12,4,3); % 4 samples, 3 features
%     % sample attributes
%     ds.sa.chunks=[1 1 2 2]';
%     ds.sa.targets=[1 2 1 2]';
%     % feature attributes
%     ds.fa.i=[3 8 13];
%     ds.fa.roi={'vt','loc','v1'};
%     % dataset attributes
%     ds.a.note='an example';
%     % display dataset
%     cosmo_disp(ds);
%     %|| .samples
%     %||   [ 1         5         9
%     %||     2         6        10
%     %||     3         7        11
%     %||     4         8        12 ]
%     %|| .sa
%     %||   .chunks
%     %||     [ 1
%     %||       1
%     %||       2
%     %||       2 ]
%     %||   .targets
%     %||     [ 1
%     %||       2
%     %||       1
%     %||       2 ]
%     %|| .fa
%     %||   .i
%     %||     [ 3         8        13 ]
%     %||   .roi
%     %||     { 'vt'  'loc'  'v1' }
%     %|| .a
%     %||   .note
%     %||     'an example'
%     %
%     % (snippet) select samples (row) in a dataset
%     % ds is a dataset struct
%     sample_ids=[3 2];
%     % select third and second sample (in that order)
%     sliced_ds=cosmo_slice(ds,sample_ids,1);
%     %
%     cosmo_disp(sliced_ds);
%     %|| .samples
%     %||   [ 3         7        11
%     %||     2         6        10 ]
%     %|| .sa
%     %||   .chunks
%     %||     [ 2
%     %||       1 ]
%     %||   .targets
%     %||     [ 1
%     %||       2 ]
%     %|| .fa
%     %||   .i
%     %||     [ 3         8        13 ]
%     %||   .roi
%     %||     { 'vt'  'loc'  'v1' }
%     %|| .a
%     %||   .note
%     %||     'an example'
%     %
%     % select third and second feature (in that order)
%     sliced_ds=cosmo_slice(ds, [3 2], 2);
%     cosmo_disp(sliced_ds);
%     %|| .samples
%     %||   [  9         5
%     %||     10         6
%     %||     11         7
%     %||     12         8 ]
%     %|| .sa
%     %||   .chunks
%     %||     [ 1
%     %||       1
%     %||       2
%     %||       2 ]
%     %||   .targets
%     %||     [ 1
%     %||       2
%     %||       1
%     %||       2 ]
%     %|| .fa
%     %||   .i
%     %||     [ 13         8 ]
%     %||   .roi
%     %||     { 'v1'  'loc' }
%     %|| .a
%     %||   .note
%     %||     'an example'
%     %
%     % using a logical mask, select features with odd value for .i
%     msk=mod(ds.fa.i,2)==1;
%     disp(msk)
%     %|| [1 0 1]
%     sliced_ds=cosmo_slice(ds, msk, 2);
%     cosmo_disp(sliced_ds);
%     %|| .samples
%     %||   [ 1         9
%     %||     2        10
%     %||     3        11
%     %||     4        12 ]
%     %|| .sa
%     %||   .chunks
%     %||     [ 1
%     %||       1
%     %||       2
%     %||       2 ]
%     %||   .targets
%     %||     [ 1
%     %||       2
%     %||       1
%     %||       2 ]
%     %|| .fa
%     %||   .i
%     %||     [ 3        13 ]
%     %||   .roi
%     %||     { 'vt'  'v1' }
%     %|| .a
%     %||   .note
%     %||     'an example'
%
%     % slice all fields in a struct
%     s=struct();
%     s.a_field=[1 2 3; 4 5 6];
%     s.another_field={'this','is','fun'};
%     cosmo_disp(s);
%     %|| .a_field
%     %||   [ 1         2         3
%     %||     4         5         6 ]
%     %|| .another_field
%     %||   { 'this'  'is'  'fun' }
%     %
%     % select first, third, third, and second column (dim=2)
%     t=cosmo_slice(s, [1 3 3 2], 2, 'struct');
%     cosmo_disp(t);
%     %|| .a_field
%     %||   [ 1         3         3         2
%     %||     4         6         6         5 ]
%     %|| .another_field
%     %||   { 'this'  'fun'  'fun'  'is' }
%
%
% Notes:
%   - do_check=false may be preferred for slice-intensive operations such
%     as when used in searchlights
%   - this function does not support arrays with more than two dimensions.
%
% #   For CoSMoMVPA's copyright information and license terms,   #
% #   see the COPYING file distributed with CoSMoMVPA.           #

    % deal with 2, 3, or 4 input arguments
    if nargin<3 || isempty(dim), dim=1; end
    if nargin<4 || isempty(type_or_check), type_or_check=true; end

    if iscell(ds) || isnumeric(ds) || islogical(ds)
        ds=slice_array(ds, to_select, dim, type_or_check);
    elseif isstruct(ds)
        if strcmp(type_or_check,'struct')
            ds=slice_struct(ds, to_select, dim, type_or_check);
        else
            if ~isfield(ds,'samples')
                error(['Expected dataset struct. To slice ordinary '...
                        'structs use "struct" as last argument']);
            end

            if type_or_check
                % check kosherness
                cosmo_check_dataset(ds);
            end

            dim_size=size(ds.samples,dim);

            % slice the samples
            ds.samples=slice_array(ds.samples,to_select,dim,type_or_check);

            % now deal with either feature or sample attributes
            attr_fns={'sa','fa'};
            attr_fn=attr_fns{dim}; % fieldname of attribute to slice

            if isfield(ds, attr_fn)
                ds.(attr_fn)=slice_struct(ds.(attr_fn),to_select,...
                                               dim,type_or_check,dim_size);
            end
        end
    else
        error('Illegal input: expected cell, array or struct');
    end


    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    % helper functions
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    function y=slice_struct(x, to_select, dim, do_check, expected_size)
        if nargin<5, expected_size=NaN; end

        y=struct();
        fns=fieldnames(x);
        for k=1:numel(fns)
            fn=fns{k};
            v=x.(fn);

            v_size=size(v,dim);

            % ensure all input sizes are the same
            if isnan(expected_size)
                expected_size=v_size;
            elseif v_size~=expected_size
                error(['Size mismatch for %s: expected %d but found %d',...
                        ' elements in dimension %d'],...
                                fn, v_size, expected_size, dim);
            end

            y.(fn)=slice_array(v, to_select, dim, do_check);
        end


    function y=slice_array(x, to_select, dim, do_check)
        if do_check
            check_size(x, to_select, dim);
            if ~isscalar(dim) || ~isnumeric(dim)
                error('dim must be 1 or 2');
            end
        end

        if dim==1
            y=x(to_select,:);
        elseif dim==2
            y=x(:,to_select);
        else
            error('dim must be 1 or 2');
        end


    function check_size(x, to_select, dim)
        if islogical(to_select) && ...
                    size(x, dim)~=numel(to_select)
            % be a bit more strict than matlab - binary array must have
            % exactly the correct size
            error('Logical mask should have %d elements, found %d', ...
                    size(x, dim), numel(to_select));
        end

        if numel(size(x))~=2
            error('Only 2D arrays are allowed');
        end

        if sum(size(to_select)>1)>1
            error('elements to select should be in vector');
        end

