cosmo cartprod hdr

function p=cosmo_cartprod(xs, convert_to_numeric)
% returns the cartesian product with all combinations of the input
%
% p=cosmo_cartprod(xs[, convert_to_numeric])
%
% Inputs:
%   xs                   Px1 cell array with values for which the product
%                        is to be returned. Each element xs{k} should be
%                        - a cell with Qk values
%                        - a numeric array [xk_1,...,xk_Qk], which is
%                          interpreted as the cell {xk_1,...,xk_Qk}.
%                        - or a string s, which is interpreted as {s}.
%                        Alternatively xs can be a struct with P fieldnames
%                        where each value is a cell with Qk values.
%
%   convert_to_numeric   Optional; if true (default), then when the output
%                        contains numeric values only a numerical matrix is
%                        returned; otherwise a cell is returned.
% Output:
%   p                    QxP cartesian product of xs (where Q=Q1*...*Qk)
%                        containing all combinations of values in xs.
%                        - If xs is a cell, then p is represented by either
%                          a matrix (if all values in xs are numeric and
%                          convert_to_numeric==true) or a cell (in all
%                          other cases).
%                        - If xs is a struct, then p is a Qx1 cell. Each
%                          element in p is a struct with the same
%                          fieldnames as xs.
%
% Examples:
%     cosmo_cartprod({{1,2},{'a','b','c'}})'
%     %|| {1,2,1,2,1,2;
%     %|| 'a','a' ,'b','b','c','c'}
%
%     cosmo_cartprod({[1,2],[5,6,7]})'
%     %|| [1,2,1,2,1,2;
%     %||  5,5,6,6,7,7]
%
%     cosmo_cartprod(repmat({1:2},1,4))'
%     %|| [1 2 1 2 1 2 1 2 1 2 1 2 1 2 1 2;
%     %||  1 1 2 2 1 1 2 2 1 1 2 2 1 1 2 2;
%     %||  1 1 1 1 2 2 2 2 1 1 1 1 2 2 2 2;
%     %||  1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2]
%
%     s=struct();
%     s.roi={'v1','loc'};
%     s.hemi={'L','R'};
%     s.subj=[1 3 9];
%     s.ana='vis';
%     s.beta=4;
%     p=cosmo_cartprod(s)';
%     cosmo_disp(p);
%     %|| { .roi     .roi     .roi    ... .roi     .roi     .roi
%     %||     'v1'     'loc'    'v1'        'loc'    'v1'     'loc'
%     %||   .hemi    .hemi    .hemi       .hemi    .hemi    .hemi
%     %||     'L'      'L'      'R'         'L'      'R'      'R'
%     %||   .subj    .subj    .subj       .subj    .subj    .subj
%     %||     [ 1 ]    [ 1 ]    [ 1 ]       [ 9 ]    [ 9 ]    [ 9 ]
%     %||   .ana     .ana     .ana        .ana     .ana     .ana
%     %||     'vis'    'vis'    'vis'       'vis'    'vis'    'vis'
%     %||   .beta    .beta    .beta       .beta    .beta    .beta
%     %||     [ 4 ]    [ 4 ]    [ 4 ]       [ 4 ]    [ 4 ]    [ 4 ] }@1x12
%     %
%
% #   For CoSMoMVPA's copyright information and license terms,   #
% #   see the COPYING file distributed with CoSMoMVPA.           #