mattress package

mattress.includes()

Provides access to the mattress.h C++ header.

Return type:

str

Returns:

Path to a directory containing the header.

Submodules

mattress.InitializedMatrix module

class mattress.InitializedMatrix.InitializedMatrix(ptr)

Bases: object

Pointer to an object containing a tatami::Matrix, typically generated by initialize() for use in C++ code. Instances of this class should only be created by developers and used within package functions; this is done by passing the ptr address to C++ and casting it to a pointer to a mattress::BoundMatrix (see the mattress.h header). All InitializedMatrix instances are expected to be transient within a Python session; they should not be serialized, nor should they be visible to end users. Each instance will automatically free the C++-allocated memory upon garbage collection.

__init__(ptr)

Parameters:

ptr (int) – Address of a mattress::BoundMatrix instance.

column(c)

Access a column from the tatami matrix. This method is primarily intended for troubleshooting and should not be used to iterate over the matrix in production code. (Do that in C++ instead.)

Parameters:

c (int) – Column to access.

Return type:

ndarray

Returns:

Column from the matrix. This is always in double-precision, regardless of the underlying representation.

column_maxs(num_threads=1)

Convenience method to compute column maxima.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of column maxima.

column_medians(num_threads=1)

Convenience method to compute column medians.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of column medians.

column_medians_by_group(group, num_threads=1)

Convenience method to compute the column-wise median for each group of row.

Parameters:

• group (Sequence) – Sequence of length equal to the number of row of the matrix, containing the group assignment for each row.

• num_threads (int) – Number of threads.

Return type:

Tuple[ndarray, list]

Returns:

Tuple containing a 2-dimensional array where each row represents a group and contains the column-wise medians for that group, across all columns of the matrix; and a list containing the unique levels of group represented by each row.

column_mins(num_threads=1)

Convenience method to compute column minima.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of column minima.

column_nan_counts(num_threads=1)

Convenience method to count the number of NaNs on each column.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of column NaN counts.

column_ranges(num_threads=1)

Convenience method to compute column ranges.

Parameters:

num_threads (int) – Number of threads.

Return type:

Tuple[ndarray, ndarray]

Returns:

Tuple containing the column minima and maxima.

column_sums(num_threads=1)

Convenience method to compute column sums.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of column sums.

column_sums_by_group(group, num_threads=1)

Convenience method to compute the column-wise sum for each group of row.

Parameters:

• group (Sequence) – Sequence of length equal to the number of row of the matrix, containing the group assignment for each row.

• num_threads (int) – Number of threads.

Return type:

Tuple[ndarray, list]

Returns:

Tuple containing a 2-dimensional array where each row represents a group and contains the column-wise sums for that group, across all columns of the matrix; and a list containing the unique levels of group represented by each row.

column_variances(num_threads=1)

Convenience method to compute column variances.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of column variances.

column_variances_by_group(group, num_threads=1)

Convenience method to compute the column-wise variance for each group of row.

Parameters:

• group (Sequence) – Sequence of length equal to the number of row of the matrix, containing the group assignment for each row.

• num_threads (int) – Number of threads.

Return type:

Tuple[ndarray, list]

Returns:

Tuple containing a 2-dimensional array where each row represents a group and contains the column-wise variances for that group, across all columns of the matrix; and a list containing the unique levels of group represented by each row.

property dtype: dtype

Type of the matrix, to masquerade as a NumPy-like object.

ncol()

Get number of columns.

Return type:

int

Returns:

Number of columns.

nrow()

Get number of rows.

Return type:

int

Returns:

Number of rows.

property ptr: int

Address to a mattress::BoundMatrix instance, to be passed as a uintptr_t to C++ - see the mattress.h header.

row(r)

Access a row from the tatami matrix. This method is primarily intended for troubleshooting and should not be used to iterate over the matrix in production code. (Do that in C++ instead.)

Parameters:

r (int) – Row to access.

Return type:

ndarray

Returns:

Row from the matrix. This is always in double-precision, regardless of the underlying representation.

row_maxs(num_threads=1)

Convenience method to compute row maxima.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of row maxima.

row_medians(num_threads=1)

Convenience method to compute row medians.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of row medians.

row_medians_by_group(group, num_threads=1)

Convenience method to compute the row-wise median for each group of columns.

Parameters:

• group (Sequence) – Sequence of length equal to the number of columns of the matrix, containing the group assignment for each column.

• num_threads (int) – Number of threads.

Return type:

Tuple[ndarray, list]

Returns:

Tuple containing a 2-dimensional array where each column represents a group and contains the row-wise medians for that group, across all rows of the matrix; and a list containing the unique levels of group represented by each column.

row_mins(num_threads=1)

Convenience method to compute row minima.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of row minima.

row_nan_counts(num_threads=1)

Convenience method to count the number of NaNs on each row.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of row NaN counts.

row_ranges(num_threads=1)

Convenience method to compute row ranges.

Parameters:

num_threads (int) – Number of threads.

Return type:

Tuple[ndarray, ndarray]

Returns:

Tuple containing the row minima and maxima.

row_sums(num_threads=1)

Convenience method to compute row sums.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of row sums.

row_sums_by_group(group, num_threads=1)

Convenience method to compute the row-wise sum for each group of columns.

Parameters:

• group (Sequence) – Sequence of length equal to the number of columns of the matrix, containing the group assignment for each column.

• num_threads (int) – Number of threads.

Return type:

Tuple[ndarray, list]

Returns:

Tuple containing a 2-dimensional array where each column represents a group and contains the row-wise sums for that group, across all rows of the matrix; and a list containing the unique levels of group represented by each column.

row_variances(num_threads=1)

Convenience method to compute row variances.

Parameters:

num_threads (int) – Number of threads.

Return type:

ndarray

Returns:

Array of row variances.

row_variances_by_group(group, num_threads=1)

Convenience method to compute the row-wise variance for each group of columns.

Parameters:

• group (Sequence) – Sequence of length equal to the number of columns of the matrix, containing the group assignment for each column.

• num_threads (int) – Number of threads.

Return type:

Tuple[ndarray, list]

Returns:

Tuple containing a 2-dimensional array where each column represents a group and contains the row-wise variances for that group, across all rows of the matrix; and a list containing the unique levels of group represented by each column.

property shape: Tuple[int, int]

Shape of the matrix, to masquerade as a NumPy-like object.

sparse()

Is the matrix sparse?

Return type:

bool

Returns:

True if matrix is sparse.

mattress.InitializedMatrix.chunk_grid(x)

See chunk_grid().

Return type:

bool

mattress.InitializedMatrix.extract_dense_array(x, subset)

See extract_dense_array().

Return type:

ndarray

mattress.InitializedMatrix.extract_sparse_array(x, subset)

See extract_sparse_array().

Return type:

SparseNdarray

mattress.InitializedMatrix.is_masked(x)

See is_masked().

Return type:

bool

mattress.InitializedMatrix.is_sparse(x)

See is_sparse().

mattress.initialize module

mattress.initialize.initialize(x, _unknown_action='message', **kwargs)

Initialize an InitializedMatrix from a Python matrix representation. This prepares the matrix for use in C++ code that can accept a tatami::Matrix instance.

Parameters:

• x (Any) – Any matrix-like object.

• _unknown_action (Literal['none', 'message', 'warn', 'error']) – Action to take upon encountering an unknown matrix. If not error, falls back to the unknown matrix handler with a message or warning. Otherwise, raises an error.

• kwargs – Additional named arguments for individual methods.

Raises:

NotImplementedError – if x is not supported.

Return type:

InitializedMatrix

Returns:

A pointer to tatami object.