mattress package¶

mattress.includes()[source]¶

Provides access to mattress C++ headers.

Returns:: Path to a directory containing the mattress header.
Return type:: str

Submodules¶

mattress.InitializedMatrix module¶

class mattress.InitializedMatrix.InitializedMatrix(ptr)[source]¶

Bases: object

Pointer to an initialized tatami::matrix, 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 mattress::BoundMatrix. 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)[source]¶

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

column(c)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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()[source]¶

Get number of columns.

Return type:: int
Returns:: Number of columns.

nrow()[source]¶

Get number of rows.

Return type:: int
Returns:: Number of rows.

property ptr¶: An address to a mattress::BoundMatrix instance, to be passed as a uintptr_t to C++ for casting.

row(r)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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()[source]¶

Is the matrix sparse?

Return type:: bool
Returns:: True if matrix is sparse.

mattress.InitializedMatrix.chunk_grid(x)[source]¶

See chunk_grid().

Return type:: bool

mattress.InitializedMatrix.extract_dense_array(x, subset)[source]¶

See extract_dense_array().

Return type:: ndarray

mattress.InitializedMatrix.extract_sparse_array(x, subset)[source]¶

See extract_sparse_array().

Return type:: SparseNdarray

mattress.InitializedMatrix.is_masked(x)[source]¶

See is_masked().

Return type:: bool

mattress.InitializedMatrix.is_sparse(x)[source]¶: See is_sparse().

mattress.initialize module¶

mattress.initialize.initialize(x)[source]¶

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.
Raises:: NotImplementedError – if x is not supported.
Return type:: InitializedMatrix
Returns:: A pointer to tatami object.