# datamatrix.multidimensional

This module is typically imported as `mdim` for brevity:

``````from datamatrix import multidimensional as mdim
``````

## 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 = 1, 2, 3
dm.m = 1, 2, INF
dm.m = 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 = 1, 2, 3
dm.m = 1, 2, NAN
dm.m = 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.2899 0.7163 0.8966]  |  0.5412710893857516 |
|   |  [0.8233 0.4222 0.0457]  |                     |
|   |  [0.3872 0.819  0.4712]] |                     |
| 1 | [[0.5012 0.6533 0.4136]  | 0.37142088312520327 |
|   |  [0.4019 0.3372 0.4721]  |                     |
|   |  [0.0091 0.1529 0.4015]] |                     |
| 2 | [[0.8437 0.3456 0.4625]  |  0.649211427308975  |
|   |  [0.9416 0.7843 0.1001]  |                     |
|   |  [0.9396 0.8167 0.6087]] |                     |
| 3 | [[0.6815 0.0713 0.4834]  |  0.5445335807644811 |
|   |  [0.2327 0.1442 0.7274]  |                     |
|   |  [0.9059 0.8158 0.8385]] |                     |
| 4 | [[0.1115 0.1662 0.7345]  | 0.45516585911691254 |
|   |  [0.294  0.6356 0.3887]  |                     |
|   |  [0.5317 0.9522 0.2821]] |                     |
+---+--------------------------+---------------------+
``````

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