larray.stack¶

larray.stack(elements=None, axes=None, title=None, meta=None, dtype=None, res_axes=None, **kwargs) → larray.core.array.Array[source]¶

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 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)

>>> 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