larray.stack

larray.stack(elements=None, axis=None, title='', **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.

axis : str or Axis, optional

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

title : str, optional

Title.

Returns:

LArray

A single array combining arrays.

Examples

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

In the case the axis to create has already been defined in a variable

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

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

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

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

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

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

>>> stack((arr1, arr2))
nat\{1}*    0    1
      BE  1.0  0.0
      FO  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(F=arr2, M=arr1, axis=sex)
nat\sex    M    F
     BE  1.0  0.0
     FO  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(M=arr1, F=arr2, axis='sex')   
nat\sex    M    F
     BE  1.0  0.0
     FO  1.0  0.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
nat\sessions  baseline  variant
          BE       1.0      1.5
          FO       1.0      1.5
>>> stacked.arr2
nat\sessions  baseline  variant
          BE       0.0      0.5
          FO       0.0      0.5