flatten

flatten(X, [depthFirst=true])

Flattens a matrix, dictionary, tuple, or a series of vectors.

If X is a matrix, dictionary or a series of vectors, it is converted into a 1d vector.

If X is a dictionary, flatten converts its values into a 1d vector, while omitting the keys. The values in the dictionary must be scalars, vectors, or matrices; otherwise, the function raises an exception.

If X is a tuple:

• If the tuple contains only one element, return the element.

• For a tuple containing dictionaries: If all elements are dictionaries and have identical key-value types, they are flattened into a single dictionary. Otherwise, the function raises an exception.

• For a tuple containing tables: If all elements are tables and have identical column names and data types, they are flattened into a single table. Otherwise, it treats each table as a tuple of multiple dictionaries (rows).

If X is a tuple containing tuple elements, flatten iterates through each element.

• For tuple elements:

  • When depthFirst is set to true, only the innermost element of each tuple element is flattened.

  • When depthFirst is set to false, only the outermost element of each tuple element is flattened.

• Non-tuple elements remain unchanged.

Multiple calls to flatten are required to completely flatten a deeply-nested tuple into a vector. Alternatively, you can call flatten with reduce for recursive operations.

Xis a vector, tuple, matrix or dictionary.

depthFirst (optional) is a Boolean value indicating whether to use depth-first (default) or breadth-first method as the flattening strategy. It only takes effect when X is a tuple.

• If X is a vector, matrix, or dictionary, return a vector.

• If X is a tuple of homogeneous dictionaries, return a dictionary.

• If X is a tuple of homogeneous tables, return a table.

• If a tuple is not fully flattened, return a tuple.

Convert a matrix into a vector.

m=1..10$5:2;
flatten(m);
// output: [1,2,3,4,5,6,7,8,9,10]

Convert a list of vectors into a vector.

a=1..10;
b = a cut 2;
b;
// output: ([1,2],[3,4],[5,6],[7,8],[9,10])

flatten(b);
// output: [1,2,3,4,5,6,7,8,9,10]

x=flatten([1, [2,3]]);
x;
// output: [1,2,3]

Convert a tuple with tuple elements into a 1d vector, which involves several times of flatten operations:

list = (1, (2, (3, 4, 5)), (6, 7), 8, [9])
x1 = flatten(list)
x1
//(3, 4, 5) and (6, 7) are converted to 1D vectors
// output:(1,(2,[3,4,5]),[6,7],8,[9])

x2= flatten(x1)
x2
//(2,[3,4,5]) is converted to 1D vectors
// output:(1,[2,3,4,5],[6,7],8,[9])

x3= flatten(x2)
x3
// flatten to 1D vector
// output:[1,2,3,4,5,6,7,8,9]

Or use flatten with reduce to get the result after iteration:

reduce(flatten, init=list)
// output:[1,2,3,4,5,6,7,8,9]

Convert a dictionary into a vector.

d = {"a":1, "b":2}
res = flatten(d)
// output: [1,2]

Flatten a tuple of homogeneous dictionaries and return a dictionary.

a = [dict(1 2 3,10 20 30),dict(1 2 3,`aaa`bbb`ccc)]
res = flatten(a)
typestr(res)
// output: INT->ANY DICTIONARY

Flatten a tuple of homogeneous tables and return a table.

res = flatten([table(1..3 as sym, 11..13 as price), table(21..23 as sym, 31..33 as price)])

If the tables in the tuple do not have identical field names and types, return a tuple.

a = [table(1..3 as sym, 11..13 as price), table(21..23 as a, 31..33 as b)]
res = flatten(a)
typestr(res)
// output: ANY VECTOR

If the tuple contains tables and other types, return a tuple.

a=[table(1..6 as sym, 11..16 as price), 1..4$2:2]
res = flatten(a)
typestr(res)
// output: ANY VECTOR