datamatrix.multidimensional

This module is typically imported as mdim for brevity:

from datamatrix import multidimensional as mdim

What are multidimensional columns?
function flatten(dm)
function infcount(col)
function nancount(col)
function reduce(col, operation=)

What are multidimensional columns?

A MultiDimensionalColumn is a column that itself has a shape; that is, each cell is itself an array. This allows you to represent multidimensional data, such as images and time series.

function flatten(dm)

Flattens all multidimensional columns of a datamatrix to float columns. The result is a new datamatrix where each row of the original datamatrix is repeated for each value of the multidimensional column. The new datamatrix does not contain any multidimensional columns.

This function requires that all multidimensional columns in dm have the same shape, or that dm doesn't contain any multidimensional columns, in which case a copy of dm is returned.

Version note: Moved to datamatrix.multidimensional in 1.0.0

Version note: New in 0.15.0

Example:

from datamatrix import DataMatrix, MultiDimensionalColumn,              multidimensional as mdim

dm = DataMatrix(length=2)
dm.col = 'a', 'b'
dm.m1 = MultiDimensionalColumn(shape=(3,))
dm.m1[:] = 1,2,3
dm.m2 = MultiDimensionalColumn(shape=(3,))
dm.m2[:] = 3,2,1
flat_dm = mdim.flatten(dm)
print('Original:')
print(dm)
print('Flattened:')
print(flat_dm)

Output:

Original:
+---+-----+------------+------------+
| # | col |     m1     |     m2     |
+---+-----+------------+------------+
| 0 |  a  | [1. 2. 3.] | [3. 2. 1.] |
| 1 |  b  | [1. 2. 3.] | [3. 2. 1.] |
+---+-----+------------+------------+
Flattened:
+---+-----+-----+-----+
| # | col |  m1 |  m2 |
+---+-----+-----+-----+
| 0 |  a  | 1.0 | 3.0 |
| 1 |  a  | 2.0 | 2.0 |
| 2 |  a  | 3.0 | 1.0 |
| 3 |  b  | 1.0 | 3.0 |
| 4 |  b  | 2.0 | 2.0 |
| 5 |  b  | 3.0 | 1.0 |
+---+-----+-----+-----+

Arguments:

dm -- A DataMatrix
- Type: DataMatrix

Returns:

A 'flattened' DataMatrix without multidimensional columns

Type: DataMatrix

function infcount(col)

Counts the number of INF values for each cell in a multidimensional column, and returns this as an int column.

Version note: Moved to datamatrix.multidimensional in 1.0.0

Version note: New in 0.15.0

Example:

from datamatrix import DataMatrix, MultiDimensionalColumn,              multidimensional as mdim, INF

dm = DataMatrix(length=3)
dm.m = MultiDimensionalColumn(shape=(3,))
dm.m[0] = 1, 2, 3
dm.m[1] = 1, 2, INF
dm.m[2] = INF, INF, INF
dm.nr_of_inf = mdim.infcount(dm.m)
print(dm)

Output:

+---+---------------+-----------+
| # |       m       | nr_of_inf |
+---+---------------+-----------+
| 0 |   [1. 2. 3.]  |    0.0    |
| 1 | [ 1.  2. inf] |    1.0    |
| 2 | [inf inf inf] |    3.0    |
+---+---------------+-----------+

Arguments:

col -- A multidimensional column to count the INF values in.
- Type: MultiDimensionalColumn

Returns:

An int column with the number of INF values in each cell.

Type: IntColumn

function nancount(col)

Counts the number of NAN values for each cell in a multidimensional column, and returns this as an int column.

Version note: Moved to datamatrix.multidimensional in 1.0.0

Version note: New in 0.15.0

Example:

from datamatrix import DataMatrix, MultiDimensionalColumn,              multidimensional as mdim, NAN

dm = DataMatrix(length=3)
dm.m = MultiDimensionalColumn(shape=(3,))
dm.m[0] = 1, 2, 3
dm.m[1] = 1, 2, NAN
dm.m[2] = NAN, NAN, NAN
dm.nr_of_nan = mdim.nancount(dm.m)
print(dm)

Output:

+---+---------------+-----------+
| # |       m       | nr_of_nan |
+---+---------------+-----------+
| 0 |   [1. 2. 3.]  |    0.0    |
| 1 | [ 1.  2. nan] |    1.0    |
| 2 | [nan nan nan] |    3.0    |
+---+---------------+-----------+

Arguments:

col -- A column to count the NAN values in.
- Type: MultiDimensionalColumn

Returns:

An int column with the number of NAN values in each cell.

Type: IntColumn

function reduce(col, operation=)

Transforms multidimensional values to single values by applying an operation (typically a mean) to each multidimensional value.

Version note: Moved to datamatrix.multidimensional in 1.0.0

Version note: As of 0.11.0, the function has been renamed to reduce(). The original reduce_() is deprecated.

Example:

import numpy as np
from datamatrix import DataMatrix, MultiDimensionalColumn,              multidimensional as mdim

dm = DataMatrix(length=5)
dm.m = MultiDimensionalColumn(shape=(3, 3))
dm.m = np.random.random((5, 3, 3))
dm.mean_y = mdim.reduce(dm.m)
print(dm)

Output:

+---+--------------------------------------+--------------------+
| # |                  m                   |       mean_y       |
+---+--------------------------------------+--------------------+
| 0 |       [[0.3132 0.4558 0.4946]        | 0.5636305766581098 |
|   |        [0.7616 0.4058 0.2115]        |                    |
|   |        [0.8345 0.7022 0.8935]]       |                    |
| 1 |       [[0.1851 0.7145 0.4717]        | 0.4525976576516136 |
|   |        [0.358  0.3737 0.015 ]        |                    |
|   |        [0.7841 0.4591 0.7122]]       |                    |
| 2 |       [[0.7674 0.9886 0.809 ]        | 0.6100357380806702 |
|   |        [0.3931 0.5293 0.7271]        |                    |
|   |        [0.6564 0.5913 0.0281]]       |                    |
| 3 | [[5.3077e-01 4.1011e-01 7.2701e-01]  | 0.542667760888871  |
|   |  [2.3967e-01 9.7785e-01 9.7205e-05]  |                    |
|   |  [6.6697e-01 9.7097e-01 3.6055e-01]] |                    |
| 4 |       [[0.3373 0.8558 0.3724]        | 0.6205864217460223 |
|   |        [0.9994 0.7979 0.9246]        |                    |
|   |        [0.0621 0.4604 0.7755]]       |                    |
+---+--------------------------------------+--------------------+

Arguments:

col -- The column to reduce.
- Type: MultiDimensionalColumn

Keywords:

operation -- The operation function to use for the reduction. This function should accept col as first argument, and axis=1 as keyword argument.
- Default:

Returns:

A reduction of the signal.

Type: FloatColumn