larray.stack

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

Combine several arrays or sessions along an axis.

Parameters

elementstuple, list, dict or Session.

Elements to stack. Elements can be scalars, arrays, sessions, (label, value) pairs or a {label: value} mapping.

Stacking a single session will stack all its arrays in a single array. Stacking several sessions will take the corresponding arrays in all the sessions and stack them, returning a new session. An array missing in a session will be replaced by NaN.

axesstr, Axis, Group or sequence of Axis, optional

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

titlestr, optional

Deprecated. See ‘meta’ below.

metalist of pairs or dict 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.

dtypetype, optional

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

res_axesAxisCollection, optional

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

Returns

Array or Session

A single Array combining input values, or a single Session combining input Sessions. 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)

>>> stack(BE=arr1, FO=arr2, axes='nat')   
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