Array initialization and slicing

`friendly_matrix.ndarray` methods

class friendly_matrix.ndarray(array[, dim_names=None[, *args_dim_arrays[, **kwargs_dim_arrays]]])

A structure for matrix-like data, which stores the data as a classic NumPy ndarray, and provides the option to reference by human-readable values.

This class, plus the other functions exposed in the friendly_matrix package, are designed as substitutes for the NumPy ndarray, with comparable performance benchmarks and familiar, NumPy-style usage patterns.

Labels do not need to be specified for every dimension and index. There are four ways to initialize a friendly_matrix.ndarray instance using the constructor, all of which involve assigning new labels to an existing NumPy ndarray. The other main way to create a new friendly_matrix.ndarray is by calling friendly_matrix.compute_ndarray(). The four ways are demonstrated below. In the examples, we assume the array array consists of two dimensions, for size and n_passengers. Dimension size has length 3, for small, medium, and large, and dimension n_passengers goes from 0 to 4.

1. Casting:

rockets = friendly_matrix.ndarray(array)

Note: This creates an unlabeled friendly_matrix.ndarray instance.

2. Dimension arrays as arguments:

rockets = friendly_matrix.ndarray(
        array,
        ['size', 'n_passengers'],
        ['small', 'medium', 'large'])

3. Dimension arrays as dict:

dim_arrays = {
        'size': ['small', 'medium', 'large']
}
rockets = friendly_matrix.ndarray(
        array,
        ['size', 'n_passengers'],
        dim_arrays)

4. Dimension arrays as keyword arguments:

rockets = friendly_matrix.ndarray(
        array,
        ['size', 'n_passengers'],
        size=['small', 'medium', 'large'])

Parameters

array – NumPy array to wrap
dim_names – label for each dimension
*args_dim_arrays – index labels for each dimension, or single dict mapping each dimension label to its corresponding index labels
**kwargs_dim_arrays – index labels for each dimension (only if specified dimensions are argument- and keyword-friendly)

property ndim

Type: int

Number of dimensions

property shape

Type: tuple

Length of each dimension

property size

Type: int

Total number of elements in the array

property dtype

Type: type

Data type of the array

property itemsize

Type: int

Length of one element of the array in bytes

dim_length(dim) → int

Parameters: dim – dimension label or index
Returns: length of that dimension

take(*args, **kwargs) → friendly_matrix.ndarray

Takes a slice of the array according to the specified labels.

Parameters

*args – index labels to select for each dimension, or single dict mapping each dimension label to its corresponding index labels
**kwargs – index labels for each dimension (only if specified dimensions are argument- and keyword-friendly)

If no labels are specified for a dimension, the entire dimension is selected. If a single label not wrapped in a list is specified for a dimension, that dimension is dropped in the result. If all labels specified are single labels, the result is equivalent to calling get().

A take operation can also be performed by calling a friendly_matrix.ndarray instance directly. It’s recommended to use this shorthand for style.

The three ways of using take() are demonstrated below. In the examples, we assume the array rockets consists of two dimensions, size and n_passengers. Dimension size has indices named small, medium, and large, and dimension n_passengers goes from 0 to 4.

1. Dimension arrays as arguments:

rockets('large', [2, 3])

The value None can be passed in as a shorthand for selecting all indices in a dimension.

2. Dimension arrays as dict:

rockets({
        'size': 'large',
        'n_passengers': [2, 3]
})

3. Dimension arrays as keyword arguments:

rockets(size='large', n_passengers=[2, 3])

Note: In the above examples, the shape of the result is (2,), because passing in the single value 'large' for the first dimension causes the dimension to be dropped from the result. Passing in ['large'] instead would result in a shape of (1, 2).

Returns: A new friendly_matrix.ndarray instance containing the filtered array

take_A(*args, **kwargs) → numpy.ndarray: Same as friendly_matrix.ndarray.take(), except returns only the NumPy array.

get(*args, **kwargs) → object

Gets the single element by its labels.

Parameters

*args – index labels to select for each dimension, or single dict mapping each dimension label to its corresponding index labels
**kwargs – index labels for each dimension (only if specified dimensions are argument- and keyword-friendly)

A get operation can also be performed by calling a friendly_matrix.ndarray directly.

Returns: The element

set(val, *args, **kwargs) → None

Sets the single element by its labels.

Parameters

val – the updated value
*args – index labels to select for each dimension, or single dict mapping each dimension label to its corresponding index labels
**kwargs – index labels for each dimension (only if specified dimensions are argument- and keyword-friendly)