function cosmo_disp(x, varargin)
% display the input as a string representation
%
% cosmo_disp(x,opt)
%
% Inputs:
% x any type of data element (can be a dataset struct)
% opt Optional struct with fields
% .threshold If the number of values in an array along a dimension
% exceeds threshold, then an array is showed in summary
% style along that dimension. Default: 5
% .edgeitems When an array is shown in summary style, edgeitems sets
% the number of items at the beginning and end of the
% array to be shown (separated by '...' in rows and by ':'
% in columns).
% Default: 3
% .precision Numeric precision, indicating number of decimals after
% the floating point
% Default: 3
% .strlen Maximal string length, if a string is longer the
% beginning and end are shown separated by ' ... '.
% Default: 20
% .depth Maximum recursion depth
% Default: 6
%
% Side effect: Calling this function caused the representation of x
% to be displayed.
%
%
% Examples:
% % display a complicated data structure
% x=struct();
% x.a_cell={[],{'cell within cell',[1 2; 3 4]}};
% x.small_matrix=[10 11 12; 13 14 15];
% x.big_matrix=reshape(1:200,10,20);
% x.huge=2^40;
% x.tiny=2^-40;
% x.a_string='hello world';
% x.a_struct.another_struct.name='me';
% x.a_struct.another_struct.func=@abs;
% cosmo_disp(x);
% %|| .a_cell
% %|| { [ ] { 'cell within cell' [ 1 2
% %|| 3 4 ] } }
% %|| .small_matrix
% %|| [ 10 11 12
% %|| 13 14 15 ]
% %|| .big_matrix
% %|| [ 1 11 21 ... 171 181 191
% %|| 2 12 22 ... 172 182 192
% %|| 3 13 23 ... 173 183 193
% %|| : : : : : :
% %|| 8 18 28 ... 178 188 198
% %|| 9 19 29 ... 179 189 199
% %|| 10 20 30 ... 180 190 200 ]@10x20
% %|| .huge
% %|| [ 1.1e+12 ]
% %|| .tiny
% %|| [ 9.09e-13 ]
% %|| .a_string
% %|| 'hello world'
% %|| .a_struct
% %|| .another_struct
% %|| .name
% %|| 'me'
% %|| .func
% %|| @abs
% %
% cosmo_disp(x.a_cell)
% %|| { [ ] { 'cell within cell' [ 1 2
% %|| 3 4 ] } }
% cosmo_disp(x.a_cell{2}{2})
% %|| [ 1 2
% %|| 3 4 ]
%
% % make a cell in a cell in a cell in a cell ...
% m={{{{{{{{{{{'hello'}}}}}}}}}}};
% cosmo_disp(m)
% %|| { { { { { { <cell> } } } } } }
% cosmo_disp(m,'depth',8)
% %|| { { { { { { { { <cell> } } } } } } } }
% cosmo_disp(m,'depth',Inf)
% %|| { { { { { { { { { { { 'hello' } } } } } } } } } } }
%
% % illustrate 'threshold' and 'edgeitems' arguments
% cosmo_disp(num2cell('a':'k'))
% %|| { 'a' 'b' 'c' ... 'i' 'j' 'k' }@1x11
% cosmo_disp(num2cell('a':'k'),'threshold',Inf)
% %|| { 'a' 'b' 'c' 'd' 'e' 'f' 'g' 'h' 'i' 'j' 'k' }
% cosmo_disp(num2cell('a':'k'),'edgeitems',2)
% %|| { 'a' 'b' ... 'j' 'k' }@1x11
%
% % illustrate 'precision' argument
% cosmo_disp(pi*[1 2],'precision',1);
% %|| [ 3 6 ]
% cosmo_disp(pi*[1 2],'precision',3);
% %|| [ 3.14 6.28 ]
% cosmo_disp(pi*[1 2],'precision',5);
% %|| [ 3.1416 6.2832 ]
% cosmo_disp(pi*[1 2],'precision',7);
% %|| [ 3.141593 6.283185 ]
%
% % illustrate n-dimensional arrays
% x=zeros([2 2 1 2 3]);
% x(:)=2*(1:numel(x));
% cosmo_disp(x)
% %|| <double>@2x2x1x2x3
% %|| (:,:,1,1,1) = [ 2 6
% %|| 4 8 ]
% %|| (:,:,1,2,1) = [ 10 14
% %|| 12 16 ]
% %|| (:,:,1,1,2) = [ 18 22
% %|| 20 24 ]
% %|| (:,:,1,2,2) = [ 26 30
% %|| 28 32 ]
% %|| (:,:,1,1,3) = [ 34 38
% %|| 36 40 ]
% %|| (:,:,1,2,3) = [ 42 46
% %|| 44 48 ]
% cosmo_disp(reshape(char(65:72),[2 2 2]))
% %|| <char>@2x2x2
% %|| (:,:,1) = 'AC
% %|| BD'
% %|| (:,:,2) = 'EG
% %|| FH'
% cosmo_disp(zeros([2 3 5 7 0 2]))
% %|| <double>@2x3x5x7x0x2 (empty)
%
% % illustrate non-singleton structs
% x=struct('x',{1 2; 3 4});
% cosmo_disp(x);
% %|| <struct>@2x2
% %|| (1,1).x
% %|| [ 1 ]
% %|| (2,1).x
% %|| [ 3 ]
% %|| (1,2).x
% %|| [ 2 ]
% %|| (2,2).x
% %|| [ 4 ]
% x3=cat(3,x,x,x);
% cosmo_disp(x3);
% %|| <struct>@2x2x3
% %|| (1,1,1).x
% %|| [ 1 ]
% %|| (2,1,1).x
% %|| [ 3 ]
% %|| (1,2,1).x
% %|| [ 2 ]
% %|| : :
% %|| (2,1,3).x
% %|| [ 3 ]
% %|| (1,2,3).x
% %|| [ 2 ]
% %|| (2,2,3).x
% %|| [ 4 ]
%
% Notes:
% - Unlike the builtin 'disp' function, this function shows the contents
% of the input using recursion. For example if a cell contains a
% struct, then the contents of that struct is shown as well
% - A use case is displaying dataset structs
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
defaults.threshold = 5; % max #items before triggering summary style
defaults.edgeitems = 3; %#items at edges in summary style
defaults.precision = 3; % show floats with 3 decimals
defaults.strlen = 20; % insert '...' with strings more than 20 chars
defaults.depth = 6; % maximal depth
defaults.show_size = false; % whether to show size of matrices
opt = cosmo_structjoin(defaults, varargin);
% get string representation of x
s = disp_helper(x, opt);
% print string representation of x
disp(s);
function s = disp_helper(x, opt)
% general helper function to get a string representation. Unlike the
% main function this function returns a string, which makes it suitable
% for recursion
depth = opt.depth;
if depth <= 0
s = any2summary_str(x, opt);
return
end
opt.depth = depth - 1;
if ~has_size(x)
s = any2summary_str(x, opt);
else
s = nd_any2str(x, opt);
end
function s = any2summary_str(x, unused)
if has_size(x)
sz = size(x);
else
sz = [1 1];
end
s = surround_with(true, '<', class(x), '>', sz);
function tf = has_size(x)
% helper, because some classes have no 'size'
try
size(x);
tf = true;
catch
tf = false;
end
function y = nd_any2str(x, opt)
if isstruct(x)
if numel(x) <= 1
y = struct2str(x, opt);
else
y = multi_any2string(x, 0, opt);
end
elseif numel(size(x)) == 2
if iscell(x)
y = cell2str(x, opt);
elseif isnumeric(x) || islogical(x)
y = matrix2str(x, opt);
elseif ischar(x)
y = string2str(x, opt);
elseif isa(x, 'function_handle')
y = function_handle2str(x, opt);
else
y = any2summary_str(x, opt);
end
else
y = multi_any2string(x, 2, opt);
end
function y = multi_any2string(x, ndim_post, opt)
sz = size(x);
sz_rest = sz((ndim_post + 1):end);
ndim_rest = numel(sz_rest);
n_rest = prod(sz_rest);
parts = cell(ndim_rest, 1);
for k = 1:ndim_rest
parts{k} = num2cell(1:sz_rest(k));
end
p = cosmo_cartprod(parts);
if ndim_post > 0
xflat = reshape(x, [sz(1:ndim_post) n_rest]);
else
xflat = x(:);
end
[pre, post] = get_mx_idxs(xflat, opt.edgeitems, opt.threshold, ndim_post + 1);
header = any2summary_str(x, opt);
s_pre = nd_any2str_helper(xflat, p, pre, opt);
if isempty(post)
s_post = {'', ''};
s_dots = {'', ''};
else
s_post = nd_any2str_helper(xflat, p, post, opt);
s_dots = cell(1, 2);
for k = 1:2
szs = cellfun(@(x)size(x, 2), s_post(:, k));
pos = round(max(szs) / 2);
s_dots{k} = [spaces(1, pos) ':'];
end
end
s_all = cat(1, s_pre, s_dots, s_post);
y = strcat_({header; strcat_(s_all)});
function s = nd_any2str_helper(xflat, p, idxs, opt)
n_rest = numel(idxs);
s = cell(n_rest, 2);
sz = size(xflat);
npre = numel(sz) - 1;
for k = 1:n_rest
idx = idxs(k);
switch npre
case 1
% for struct
v = xflat(idx);
idx_prefix = '';
idx_postfix = '';
case 2
% anything else
v = xflat(:, :, idx);
idx_prefix = ':,:,';
idx_postfix = ' = ';
otherwise
assert(false);
end
v_str = disp_helper(v, opt);
idx_str = sprintf(',%d', p(idx, :));
s{k, 1} = sprintf(' (%s%s)%s', idx_prefix, idx_str(2:end), idx_postfix);
s{k, 2} = v_str;
end
function y = strcat_(xs)
if isempty(xs)
y = '';
return
end
% all elements in xs are char
[nr, nc] = size(xs);
ys = cell(1, nc);
% sizes for each element
width_per_col = max_element_size(xs, 2);
height_per_row = max_element_size(xs, 1);
for k = 1:nc
xcol = cell(nr, 1);
width = width_per_col(k);
row_pos = 0;
for j = 1:nr
height = height_per_row(j);
if height == 0
continue
end
x = xs{j, k};
if ~ischar(x) && isempty(x)
x = '';
end
sx = size(x);
to_add = [height width] - sx;
% pad with spaces
row_pos = row_pos + 1;
xcol{row_pos} = [[x spaces(sx(1), to_add(2))]; ...
spaces(to_add(1), width)];
end
ys{k} = char(xcol{1:row_pos});
end
y = [ys{:}];
function m = max_element_size(x, dim)
% faster than cellfun
n = numel(x);
sizes = zeros(size(x));
for k = 1:n
sizes(k) = size(x{k}, dim);
end
m = max(sizes, [], 3 - dim);
function y = spaces(nx, ny)
% faster than repmat(' ',nx,ny)
if nx > 0 && ny > 0
y(nx, ny) = ' ';
y(:) = ' ';
else
if nx < 0
nx = 0;
end
if ny < 0
ny = 0;
end
y = reshape('', nx, ny);
end
function y = struct2str(x, opt)
if numel(x) == 0
show_size = opt.show_size;
y = [surround_with(show_size, '', 'struct', '', size(x)) ' (empty)'];
return
end
assert(numel(x) == 1);
fns = fieldnames(x);
n = numel(fns);
if n == 0
show_size = opt.show_size;
y = [surround_with(show_size, '', 'struct', '', size(x)) ' (empty)'];
else
r = cell(n * 2, 1);
for k = 1:n
fn = fns{k};
r{k * 2 - 1} = ['.' fn];
d = disp_helper(x.(fn), opt);
r{k * 2} = [spaces(size(d, 1), 2) d];
end
y = strcat_(r);
end
function s = function_handle2str(x, opt)
s_with_quotes = string2str(func2str(x), opt);
s = ['@' s_with_quotes(2:(end - 1))];
function s = string2str(x, opt)
if ~ischar(x)
error('expected a char');
end
[nrows, ncols] = size(x);
if ncols > opt.strlen
infix = ' ... ';
h = floor((opt.strlen - numel(infix)) / 2);
x = strcat_({x(:, 1:h), infix, x(:, ncols + ((1 - h):0))});
end
quote = '''';
pre = quote;
post = [spaces(nrows - 1, 1); quote];
s = strcat_({pre, x, post});
function s = cell2str(x, opt)
% display a cell
edgeitems = opt.edgeitems;
threshold = opt.threshold;
% get indices of rows and columns to show
[r_pre, r_post] = get_mx_idxs(x, edgeitems, threshold, 1);
[c_pre, c_post] = get_mx_idxs(x, edgeitems, threshold, 2);
part_idxs = {{r_pre, r_post}, {c_pre, c_post}};
nrows = numel([r_pre r_post]) + ~isempty(r_post);
ncols = numel([c_pre c_post]) + ~isempty(c_post);
sinfix = cell(nrows, ncols * 2 + 1);
for k = 1:(ncols - 1)
sinfix{1, k * 2 + 2} = ' ';
end
cpos = 1;
for cpart = 1:2
col_idxs = part_idxs{2}{cpart};
nc = numel(col_idxs);
rpos = 0;
for rpart = 1:2
row_idxs = part_idxs{1}{rpart};
nr = numel(row_idxs);
if nr == 0
continue
end
for ci = 1:nc
col_idx = col_idxs(ci);
trgc = cpos + ci * 2;
for ri = 1:nr
row_idx = row_idxs(ri);
sinfix{rpos + ri, trgc} = disp_helper(x{row_idx, ...
col_idx}, opt);
if cpart == 2 && ci == 1 && nc > 0
sinfix{rpos + ri, cpos + ci * 2 - 1} = ' ... ';
end
end
if rpart == 2
max_length = max(cellfun(@numel, sinfix(:, trgc)));
pre_spaces = spaces(1, floor(max_length / 2 - 1));
sinfix{rpos, cpos + ci * 2} = [pre_spaces ':'];
end
end
rpos = rpos + nr + 1;
end
cpos = cpos + nc * 2;
end
show_size = opt.show_size || ~isempty(r_post) || ~isempty(c_post);
s = surround_with(show_size, '{ ', strcat_(sinfix), ' }', size(x));
function pre_infix_post = surround_with(show_size, pre, infix, post, matrix_sz)
% surround infix by pre and post, doing
n = prod(matrix_sz);
if show_size && n ~= 1
size_str = sprintf('x%d', matrix_sz);
size_str(1) = '@';
if n == 0
size_str = [size_str ' (empty)'];
end
else
size_str = '';
end
post = strcat_({spaces(size(infix, 1) - 1, 1); [post size_str]});
pre_infix_post = strcat_({pre, infix, post});
function s = matrix2str(x, opt)
if isempty(x)
show_size = opt.show_size;
s = surround_with(show_size, '[', ' ', ']', size(x));
return
end
% display a matrix
edgeitems = opt.edgeitems;
threshold = opt.threshold;
precision = opt.precision;
% get indices of rows and columns to show
[r_pre, r_post] = get_mx_idxs(x, edgeitems, threshold, 1);
[c_pre, c_post] = get_mx_idxs(x, edgeitems, threshold, 2);
% data to be shown
y = x([r_pre r_post], [c_pre c_post]);
% convert to string
s = num2str(y, precision);
% number of characters in first and second dimension
[nc_row, nc_col] = size(s);
% see where each column is a space; that's a potential split point
sp_col = sum(s == ' ', 1) == nc_row;
% col_index has value k for characters in the k-th column, else zero
col_index = zeros(1, nc_col);
col_count = 1;
in_num = true;
for k = 1:nc_col
if in_num
if sp_col(k)
col_count = col_count + 1;
in_num = false;
else
col_index(k) = col_count;
end
elseif ~sp_col(k)
in_num = true;
col_index(k) = col_count;
end
end
% deal with rows
row_blocks = cell(3, 1);
if isempty(r_post)
row_blocks{1, 1} = s;
else
% insert ':' for each column
line = spaces(1, nc_col);
for k = 1:max(col_index)
idxs = find(col_index == k);
median_pos = round(mean(idxs));
line(median_pos) = ':';
end
row_blocks{1} = s(1:edgeitems, :);
row_blocks{2} = line;
row_blocks{3} = s(edgeitems + (1:edgeitems), :);
end
% deal with columns
row_and_col_blocks = cell(3, 3);
for row = 1:3
if isempty(c_post)
row_and_col_blocks{row} = row_blocks{row};
else
% insert ' ... ' halfway each row
pre_end = find(col_index == edgeitems, 1, 'last') + 1;
post_start = find(col_index == (edgeitems + 1), 1, 'first') - 1;
r = row_blocks{row, 1};
if isempty(r)
continue
end
row_and_col_blocks{row, 1} = r(:, 1:pre_end);
if row ~= 2
row_and_col_blocks{row, 2} = repmat(' ... ', size(r, 1), 1);
end
row_and_col_blocks{row, 3} = r(:, post_start:end);
end
end
show_size = opt.show_size || ~isempty(r_post) || ~isempty(c_post);
s = surround_with(show_size, '[ ', strcat_(row_and_col_blocks), ' ]', ...
size(x));
function [pre, post] = get_mx_idxs(x, edgeitems, threshold, dim)
% returns the first and last indices for showing an array along
% dimension dim. If size(x,dim)<2*edgeitems, then pre has all the
% indices, otherwise pre and post have the first and last edgeitems
% indices, respectively
n = size(x, dim);
if n > max(threshold, 2 * edgeitems) % properly deal with Inf values
pre = 1:edgeitems;
post = n - edgeitems + (1:edgeitems);
else
pre = 1:n;
post = [];
end
