mattress package¶

class mattress.InitializedMatrix(ptr)[source]¶

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

This constructor should only be called by registered methods for initialize().

Parameters:: ptr (int) – Address of a mattress::BoundMatrix instance. This is typically obtained by passing a std::uintptr_t from C++ code.

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. This should be non-negative and less than ncol().
Return type:: ndarray
Returns:: Contents of column c from the matrix. This is always in double-precision, regardless of the underlying representation.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.column(0)

column_maxs(num_threads=1)[source]¶

Convenience method to compute column maxima.

Parameters:: num_threads (int) – Number of threads.
Return type:: ndarray
Returns:: Double-precision array of column maxima.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.column_maxs()

column_medians(num_threads=1)[source]¶

Convenience method to compute column medians.

Parameters:: num_threads (int) – Number of threads.
Return type:: ndarray
Returns:: Double-precision array of column medians.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.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 of (i) a 2-dimensional array where each row represents a group and contains the column-wise medians for that group; and (ii) a list containing the unique levels of group represented by each row.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> group = ["A", "B"] * 5
>>> ptr.column_medians_by_group(group)

column_mins(num_threads=1)[source]¶

Convenience method to compute column minima.

Parameters:: num_threads (int) – Number of threads.
Return type:: ndarray
Returns:: Double-precision array of column minima.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.column_mins()

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:: Integer array containing the number of NaNs in each column.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> mat[0,0] = numpy.nan
>>> mat[9,19] = numpy.nan
>>> ptr = mattress.initialize(mat)
>>> ptr.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 of two double-precision arrays. The first contains the column minima and the second contains the column maxima.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.column_ranges()

column_sums(num_threads=1)[source]¶

Convenience method to compute column sums.

Parameters:: num_threads (int) – Number of threads.
Return type:: ndarray
Returns:: Double-precision array of column sums.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.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 of (i) a 2-dimensional array where each row represents a group and contains the column-wise sums for that group; and (ii) a list containing the unique levels of group represented by each row.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> group = ["A", "B"] * 5
>>> ptr.column_sums_by_group(group)

column_variances(num_threads=1)[source]¶

Convenience method to compute column variances.

Parameters:: num_threads (int) – Number of threads.
Return type:: ndarray
Returns:: Double-precision array of column variances.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.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 of (i) a 2-dimensional array where each row represents a group and contains the column-wise variances for that group; and (ii) a list containing the unique levels of group represented by each row.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> group = ["A", "B"] * 5
>>> ptr.column_variances_by_group(group)

property dtype: dtype¶

Type of the matrix, to masquerade as a NumPy-like object. This is always a double-precision type.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(1000, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.dtype

ncol()[source]¶

Get the number of columns in the matrix.

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

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(1000, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.ncol()

nrow()[source]¶

Get the number of rows in the matrix.

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

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(1000, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.nrow()

property ptr: int¶

Address to a mattress::BoundMatrix instance, to be passed as a std::uintptr_t to C++ - see the mattress.h header. This should not be used after the InitializedMatrix is deleted. This should not be used to construct a new InitializedMatrix.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(1000, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.ptr

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. This should be non-negative and less than nrow().
Return type:: ndarray
Returns:: Contents of row r of the matrix. This is always in double-precision, regardless of the underlying representation.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(1000, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.row(0)

row_maxs(num_threads=1)[source]¶

Convenience method to compute row maxima.

Parameters:: num_threads (int) – Number of threads.
Return type:: ndarray
Returns:: Double-precision array of row maxima.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.row_maxs()

row_medians(num_threads=1)[source]¶

Convenience method to compute row medians.

Parameters:: num_threads (int) – Number of threads.
Return type:: ndarray
Returns:: Double-precision array of row medians.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.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 of (i) a 2-dimensional array where each column represents a group and contains the row-wise medians for that group; and (ii) a list containing the unique levels of group represented by each column.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> group = ["A", "B"] * 10
>>> ptr.row_medians_by_group(group)

row_mins(num_threads=1)[source]¶

Convenience method to compute row minima.

Parameters:: num_threads (int) – Number of threads.
Return type:: ndarray
Returns:: Double-precision array of row minima.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.row_mins()

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:: Integer array containing the number of NaNs in each row.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> mat[0,0] = numpy.nan
>>> mat[9,19] = numpy.nan
>>> ptr = mattress.initialize(mat)
>>> ptr.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 of two double-precision arrays. The first contains the row minima and the second contains the row maxima.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.row_ranges()

row_sums(num_threads=1)[source]¶

Convenience method to compute row sums.

Parameters:: num_threads (int) – Number of threads.
Return type:: ndarray
Returns:: Double-precision array of row sums.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.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 of (i) a 2-dimensional array where each column represents a group and contains the row-wise sums for that group; and (ii) a list containing the unique levels of group represented by each column.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> group = ["A", "B"] * 10
>>> ptr.row_sums_by_group(group)

row_variances(num_threads=1)[source]¶

Convenience method to compute row variances.

Parameters:: num_threads (int) – Number of threads.
Return type:: ndarray
Returns:: Double-precision array of row variances.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.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 of (i) a 2-dimensional array where each column represents a group and contains the row-wise variances for that group; and (ii) a list containing the unique levels of group represented by each column.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(10, 20)
>>> ptr = mattress.initialize(mat)
>>> group = ["A", "B"] * 10
>>> ptr.row_variances_by_group(group)

property shape: Tuple[int, int]¶

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

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(1000, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.shape

sparse()[source]¶

Is the matrix sparse?

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

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(1000, 20)
>>> ptr = mattress.initialize(mat)
>>> ptr.sparse()

mattress.includes()[source]¶

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

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

mattress.initialize(x, _unknown_action='message', **kwargs)[source]¶

mattress.initialize(x, **kwargs)

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

mattress.initialize(x, **kwargs)

Initialize an InitializedMatrix from a Python matrix representation. This prepares the matrix for use in C++ code that can accept a mattress::BoundMatrix 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 no method is registered for the class of x and _unknown_action = "error".

Return type:

InitializedMatrix

Returns:

An InitializedMatrix containing a pointer to mattress::BoundMatrix C++ object.

Examples

>>> import numpy
>>> import mattress
>>> mat = numpy.random.rand(1000, 20)
>>> ptr = mattress.initialize(mat)