larray.stack

larray.stack(elements=None, axes=None, title=None, meta=None, dtype=None, res_axes=None, **kwargs)

Combines several arrays or sessions along an axis.

Parameters:

elements : tuple, list or dict.

Elements to stack. Elements can be scalars, arrays, sessions, (label, value) pairs or a {label: value} mapping. In the later case, axis must be defined and cannot be a name only, because we need to have labels order, which the mapping does not provide.

Stacking sessions will return a new session containing the arrays of all sessions stacked together. An array missing in a session will be replaced by NaN.

axes : str, Axis, Group or sequence of Axis, optional

Axes to create. If None, defaults to a range() axis.

title : str, optional

Deprecated. See ‘meta’ below.

meta : list of pairs or dict or OrderedDict or Metadata, optional

Metadata (title, description, author, creation_date, …) associated with the array. Keys must be strings. Values must be of type string, int, float, date, time or datetime.

dtype : type, optional

Output dtype. Defaults to None (inspect all output values to infer it automatically).

res_axes : AxisCollection, optional

Axes of the output. Defaults to None (union of axes of all values and the stacking axes).

Returns:

Array

A single array combining arrays. The new (stacked) axes will be the last axes of the new array.

Examples

>>> nat = Axis('nat=BE,FO')
>>> sex = Axis('sex=M,F')
>>> arr1 = ones(sex)
>>> arr1
sex    M    F
     1.0  1.0
>>> arr2 = zeros(sex)
>>> arr2
sex    M    F
     0.0  0.0

In case the axis to create has already been defined in a variable (Axis or Group)

>>> stack({'BE': arr1, 'FO': arr2}, nat)
sex\nat   BE   FO
      M  1.0  0.0
      F  1.0  0.0

Otherwise (when one wants to create an axis from scratch), any of these syntaxes works:

>>> stack([arr1, arr2], 'nat=BE,FO')
sex\nat   BE   FO
      M  1.0  0.0
      F  1.0  0.0
>>> stack({'BE': arr1, 'FO': arr2}, 'nat=BE,FO')
sex\nat   BE   FO
      M  1.0  0.0
      F  1.0  0.0
>>> stack([('BE', arr1), ('FO', arr2)], 'nat=BE,FO')
sex\nat   BE   FO
      M  1.0  0.0
      F  1.0  0.0

When stacking arrays with different axes, the result has the union of all axes present:

>>> stack({'BE': arr1, 'FO': 0}, nat)
sex\nat   BE   FO
      M  1.0  0.0
      F  1.0  0.0

Creating an axis without name nor labels can be done using:

>>> stack((arr1, arr2))
sex\{1}*    0    1
       M  1.0  0.0
       F  1.0  0.0

When labels are “simple” strings (ie no integers, no string starting with integers, etc.), using keyword arguments can be an attractive alternative.

>>> stack(FO=arr2, BE=arr1, axes=nat)
sex\nat   BE   FO
      M  1.0  0.0
      F  1.0  0.0

Without passing an explicit order for labels (or an axis object like above), it should only be used on Python 3.6 or later because keyword arguments are NOT ordered on earlier Python versions.

>>> # use this only on Python 3.6 and later
>>> stack(BE=arr1, FO=arr2, axes='nat')   # doctest: +SKIP
sex\nat   BE   FO
      M  1.0  0.0
      F  1.0  0.0

One can also stack along several axes

>>> test = Axis('test=T1,T2')
>>> stack({('BE', 'T1'): arr1,
...        ('BE', 'T2'): arr2,
...        ('FO', 'T1'): arr2,
...        ('FO', 'T2'): arr1},
...       (nat, test))
sex  nat\test   T1   T2
  M        BE  1.0  0.0
  M        FO  0.0  1.0
  F        BE  1.0  0.0
  F        FO  0.0  1.0

To stack sessions, let us first create two test sessions. For example suppose we have a session storing the results of a baseline simulation:

>>> from larray import Session
>>> baseline = Session([('arr1', arr1), ('arr2', arr2)])

and another session with a variant (here we simply added 0.5 to each array)

>>> variant = Session([('arr1', arr1 + 0.5), ('arr2', arr2 + 0.5)])

then we stack them together

>>> stacked = stack([('baseline', baseline), ('variant', variant)], 'sessions')
>>> stacked
Session(arr1, arr2)
>>> stacked.arr1
sex\sessions  baseline  variant
           M       1.0      1.5
           F       1.0      1.5
>>> stacked.arr2
sex\sessions  baseline  variant
           M       0.0      0.5
           F       0.0      0.5