Unit tests

Python bindings for tatami

Overview

The mattress package implements Python bindings to the tatami C++ library for matrix representations. Downstream packages can use mattress to develop C++ extensions that are interoperable with many different matrix classes, e.g., dense, sparse, delayed or file-backed. mattress is inspired by the beachmat Bioconductor package, which does the same thing for R packages.

Instructions

mattress is published to PyPI, so installation is simple:

pip install mattress

mattress is intended for Python package developers writing C++ extensions that operate on matrices. The aim is to allow package C++ code to accept all types of matrix representations without requiring re-compilation of the associated code. To achive this:

Add mattress.includes() and assorthead.includes() to the compiler's include path. This can be done through include_dirs= of the Extension() definition in setup.py or by adding a target_include_directories() in CMake, depending on the build system.
Call mattress.initialize() on a Python matrix object to wrap it in a tatami-compatible C++ representation. This returns an InitializedMatrix with a ptr property that contains a pointer to the C++ matrix.
Pass ptr to C++ code as a uintptr_t referencing a tatami::Matrix, which can be interrogated as described in the tatami documentation.

So, for example, the C++ code in our downstream package might look like the code below:

#include "mattress.h"

int do_something(uintptr_t ptr) {
    const auto& mat_ptr = mattress::cast(ptr)->ptr;
    // Do something with the tatami interface.
    return 1;
}

// Assuming we're using pybind11, but any framework that can accept a uintptr_t is fine.
PYBIND11_MODULE(lib_downstream, m) {
    m.def("do_something", &do_something);
}

Which can then be called from Python:

from . import lib_downstream as lib
from mattress import initialize

def do_something(x):
    tmat = initialize(x)
    return lib.do_something(tmat.ptr)

Check out the included header for more definitions.

Supported matrices

Dense numpy matrices of varying numeric type:

import numpy as np
from mattress import initialize
x = np.random.rand(1000, 100)
init = initialize(x)

ix = (x * 100).astype(np.uint16)
init2 = initialize(ix)

Compressed sparse matrices from scipy with varying index/data types:

from scipy import sparse as sp
from mattress import initialize

xc = sp.random(100, 20, format="csc")
init = initialize(xc)

xr = sp.random(100, 20, format="csc", dtype=np.uint8)
init2 = initialize(xr)

Delayed arrays from the delayedarray package:

from delayedarray import DelayedArray
from scipy import sparse as sp
from mattress import initialize
import numpy

xd = DelayedArray(sp.random(100, 20, format="csc"))
xd = numpy.log1p(xd * 5)

init = initialize(xd)

Sparse arrays from delayedarray are also supported:

import delayedarray
from numpy import float64, int32
from mattress import initialize
sa = delayedarray.SparseNdarray((50, 20), None, dtype=float64, index_dtype=int32)
init = initialize(sa)

See below to extend initialize() to custom matrix representations.

Utility methods

The InitializedMatrix instance returned by initialize() provides a few Python-visible methods for querying the C++ matrix.

init.nrow() // number of rows
init.column(1) // contents of column 1
init.sparse() // whether the matrix is sparse.

It also has a few methods for computing common statistics:

init.row_sums()
init.column_variances(num_threads = 2)

grouping = [i%3 for i in range(init.ncol())]
init.row_medians_by_group(grouping)

init.row_nan_counts()
init.column_ranges()

These are mostly intended for non-intensive work or testing/debugging. It is expected that any serious computation should be performed by iterating over the matrix in C++.

Operating on an existing pointer

If we already have a InitializedMatrix, we can easily apply additional operations by wrapping it in the relevant delayedarray layers and calling initialize() afterwards. For example, if we want to add a scalar, we might do:

from delayedarray import DelayedArray
from mattress import initialize
import numpy

x = numpy.random.rand(1000, 10)
init = initialize(x)

wrapped = DelayedArray(init) + 1
init2 = initialize(wrapped)

This is more efficient as it re-uses the InitializedMatrix already generated from x. It is also more convenient as we don't have to carry around x to generate init2.

Extending to custom matrices

Developers can extend mattress to custom matrix classes by registering new methods with the initialize() generic. This should return a InitializedMatrix object containing a uintptr_t cast from a pointer to a tatami::Matrix (see the included header). Once this is done, all calls to initialize() will be able to handle matrices of the newly registered types.

from . import lib_downstream as lib
import mattress

@mattress.initialize.register
def _initialize_my_custom_matrix(x: MyCustomMatrix):
    data = x.some_internal_data
    return mattress.InitializedMatrix(lib.initialize_custom(data))

If the initialized tatami::Matrix contains references to Python-managed data, e.g., in NumPy arrays, we must ensure that the data is not garbage-collected during the lifetime of the tatami::Matrix. This is achieved by storing a reference to the data in the original member of the mattress::BoundMatrix.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mattress-0.4.3.tar.gz (45.7 kB view details)

Uploaded Aug 14, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

mattress-0.4.3-cp315-cp315t-musllinux_1_2_x86_64.whl (3.2 MB view details)

Uploaded Aug 14, 2026 CPython 3.15tmusllinux: musl 1.2+ x86-64

mattress-0.4.3-cp315-cp315t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (2.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.15tmanylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mattress-0.4.3-cp315-cp315t-macosx_11_0_arm64.whl (840.8 kB view details)

Uploaded Aug 14, 2026 CPython 3.15tmacOS 11.0+ ARM64

mattress-0.4.3-cp315-cp315t-macosx_10_15_x86_64.whl (1.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.15tmacOS 10.15+ x86-64

mattress-0.4.3-cp315-cp315-musllinux_1_2_x86_64.whl (3.2 MB view details)

Uploaded Aug 14, 2026 CPython 3.15musllinux: musl 1.2+ x86-64

mattress-0.4.3-cp315-cp315-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (2.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.15manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mattress-0.4.3-cp315-cp315-macosx_11_0_arm64.whl (840.8 kB view details)

Uploaded Aug 14, 2026 CPython 3.15macOS 11.0+ ARM64

mattress-0.4.3-cp315-cp315-macosx_10_15_x86_64.whl (1.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.15macOS 10.15+ x86-64

mattress-0.4.3-cp314-cp314t-musllinux_1_2_x86_64.whl (3.2 MB view details)

Uploaded Aug 14, 2026 CPython 3.14tmusllinux: musl 1.2+ x86-64

mattress-0.4.3-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (2.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.14tmanylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mattress-0.4.3-cp314-cp314t-macosx_11_0_arm64.whl (840.8 kB view details)

Uploaded Aug 14, 2026 CPython 3.14tmacOS 11.0+ ARM64

mattress-0.4.3-cp314-cp314t-macosx_10_15_x86_64.whl (1.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.14tmacOS 10.15+ x86-64

mattress-0.4.3-cp314-cp314-musllinux_1_2_x86_64.whl (3.2 MB view details)

Uploaded Aug 14, 2026 CPython 3.14musllinux: musl 1.2+ x86-64

mattress-0.4.3-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (2.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.14manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mattress-0.4.3-cp314-cp314-macosx_11_0_arm64.whl (840.8 kB view details)

Uploaded Aug 14, 2026 CPython 3.14macOS 11.0+ ARM64

mattress-0.4.3-cp314-cp314-macosx_10_15_x86_64.whl (1.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.14macOS 10.15+ x86-64

mattress-0.4.3-cp313-cp313-musllinux_1_2_x86_64.whl (3.2 MB view details)

Uploaded Aug 14, 2026 CPython 3.13musllinux: musl 1.2+ x86-64

mattress-0.4.3-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (2.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mattress-0.4.3-cp313-cp313-macosx_11_0_arm64.whl (840.5 kB view details)

Uploaded Aug 14, 2026 CPython 3.13macOS 11.0+ ARM64

mattress-0.4.3-cp313-cp313-macosx_10_13_x86_64.whl (1.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.13macOS 10.13+ x86-64

mattress-0.4.3-cp312-cp312-musllinux_1_2_x86_64.whl (3.2 MB view details)

Uploaded Aug 14, 2026 CPython 3.12musllinux: musl 1.2+ x86-64

mattress-0.4.3-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (2.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.12manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mattress-0.4.3-cp312-cp312-macosx_11_0_arm64.whl (840.4 kB view details)

Uploaded Aug 14, 2026 CPython 3.12macOS 11.0+ ARM64

mattress-0.4.3-cp312-cp312-macosx_10_13_x86_64.whl (1.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.12macOS 10.13+ x86-64

mattress-0.4.3-cp311-cp311-musllinux_1_2_x86_64.whl (3.2 MB view details)

Uploaded Aug 14, 2026 CPython 3.11musllinux: musl 1.2+ x86-64

mattress-0.4.3-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (2.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.11manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mattress-0.4.3-cp311-cp311-macosx_11_0_arm64.whl (847.2 kB view details)

Uploaded Aug 14, 2026 CPython 3.11macOS 11.0+ ARM64

mattress-0.4.3-cp311-cp311-macosx_10_9_x86_64.whl (1.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.11macOS 10.9+ x86-64

mattress-0.4.3-cp310-cp310-musllinux_1_2_x86_64.whl (3.2 MB view details)

Uploaded Aug 14, 2026 CPython 3.10musllinux: musl 1.2+ x86-64

mattress-0.4.3-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (2.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.10manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mattress-0.4.3-cp310-cp310-macosx_11_0_arm64.whl (846.1 kB view details)

Uploaded Aug 14, 2026 CPython 3.10macOS 11.0+ ARM64

mattress-0.4.3-cp310-cp310-macosx_10_9_x86_64.whl (1.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.10macOS 10.9+ x86-64

File details

Details for the file mattress-0.4.3.tar.gz.

File metadata

Download URL: mattress-0.4.3.tar.gz
Upload date: Aug 14, 2026
Size: 45.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mattress-0.4.3.tar.gz
Algorithm	Hash digest
SHA256	`973b9b27a93c0b145123e455b336af0c22e49c049585b5a9d4fb58294c427bf1`
MD5	`6fd6ac805141aec8428163a1e0d9b495`
BLAKE2b-256	`4e071195a72490f50612170b0d6d8fd41652d4822f308ee21e1d8e8d7558a8a7`

Algorithm	Hash digest
SHA256	`714357dc21e1e948d5519aa9a372afad0960b92836888afae4e6e8badfa21fb0`
MD5	`b7aa59710216b0f5ecf8604cdc4e318f`
BLAKE2b-256	`2df907d383ac539b203dd54fa7c8446b4a1a0a63020916204286ce6e424f9607`

Algorithm	Hash digest
SHA256	`6682821f0789e21155914f95255ccf1dad0df102d29755bd525428bbe9a7ccc4`
MD5	`b4e522f3094a73dd7207a73eba36bc83`
BLAKE2b-256	`dff49e17412a1050819469f4a5fa932736cac559e57f78042920a4f21106a758`

Algorithm	Hash digest
SHA256	`5e9a8b17966c095ac6445d6e0d9e5a2510bdf87fe8967c706bdda93b903c0f68`
MD5	`7b36b461e9b8b72a5c954424f85d8c8f`
BLAKE2b-256	`7ae08baded51722460fbfc6d1dc0a5809c4c6741f11136dbef15ec3df52bbfc5`

Algorithm	Hash digest
SHA256	`972be1b8befaf1a4be9a2baf3f2f04b1c47d2a0f4b00caef4e13989f5b732ae0`
MD5	`70a7d5d2a2b1d15aa73ef0323f96c29b`
BLAKE2b-256	`21013abdc1a0b64a2c10da2776162b0adb6aadcf7d9c1b0b1cc88d004a1fcecd`

Algorithm	Hash digest
SHA256	`8e6216353a75976dfb8700c03a36c8f7aa8ae6a5a6c820e7f1236bd39497c434`
MD5	`a5ce865f093e96a5474fb9b771757000`
BLAKE2b-256	`7b44578c50e01cec89eb966f2accb04aaf6bd7ab33205b4075cb8d9c6fc8f927`

Algorithm	Hash digest
SHA256	`47c9f51e6d12d23020ca261999ea7ed6fd357c7f1d942d8c468017e7aa0ec0d8`
MD5	`1fe6cfde88b99a6f6d851907c646237b`
BLAKE2b-256	`f20ce1aed7375dd80e8b6e5fed6c54856bf81e5ef8d7a17057e96e23b073cb26`

Algorithm	Hash digest
SHA256	`e6761c4eb0d0deb257a6a5e196705b30d069aee2259933843831f16b124deeb6`
MD5	`a1ba3d211229ed72d73ecbba106c40e6`
BLAKE2b-256	`a7464d61ace5e764eb879693a226d6eb7fa8a8f6e04d6731486f4d3ce0402ab5`

Algorithm	Hash digest
SHA256	`b9b06fc0cbfb16a16de62a1b0ac9e38ed48fec88f059cab49812acb2f51070c0`
MD5	`be8bbaf386e39149d08225cc820e65c0`
BLAKE2b-256	`489889ece914c54cb4eca53248c04457f10d73938c1023594a6580b7625bca36`

Algorithm	Hash digest
SHA256	`ba1984f3365fb419a0f4a4e41ba6def874d3570a065c11bde16a9c55189482ce`
MD5	`75fd8bb1622e70dfd47517bb3396985a`
BLAKE2b-256	`ed410519e3dcf554c6d373267fe43a1dd98fcd073e32367c9e758337eb75c156`

Algorithm	Hash digest
SHA256	`80c62ad84d175bd6850a9c1aac16f31e4a7410735df1a4f6aa2f823f4c1e72dc`
MD5	`960f7a5f7c97cc823af4ee53db8006bc`
BLAKE2b-256	`48894eb95ef9eae736a24fc26dc963d171563561571af95c5dd524df4746981c`

Algorithm	Hash digest
SHA256	`4fff6a5b81fc49732e1146013b1b253b00a1969b03e8c033376a4abdcf557fcb`
MD5	`b8573c1aa68befe54da4ea503ad5df90`
BLAKE2b-256	`6827d4505682a08931ac34f9099068fad011be67953541dfcbd023ec51fd4604`

Algorithm	Hash digest
SHA256	`e0e3d55afd6d4a79b548da7a101aa11f064800ed069e6ab5c3997b911de1525d`
MD5	`2a300e4eda2c7df12f61577efb939d40`
BLAKE2b-256	`823a837e0bd2107cac4485ff1fbf4d47c7dfee3631201345f9772e5f77a17cb4`

Algorithm	Hash digest
SHA256	`792e978c6d6af5c8e46bf27c85fa5bcee4ae98bd6ebb5b4ab36c0f98bd221811`
MD5	`5aa2d97d0f0200116f11f9845d3e11fb`
BLAKE2b-256	`e51ca9dc7b61f4d6357dbf011b0a55e79c420d275037ca6adec345c46a83e29a`

Algorithm	Hash digest
SHA256	`bba8b0299507fd63dbfb4f5dcc32f2f31cebf5f7b9f20e66e80fb0a69d976589`
MD5	`23154fa134ced03508fa384049707b12`
BLAKE2b-256	`f09aea42b32e25e17d5e90d3c80fa22a83d79719bd99c3ca192b1d473d9845b7`

Algorithm	Hash digest
SHA256	`76160650870dc26e7a1a9edf52582ade3b166a6f99e6538f201566d3f693ccd9`
MD5	`a832220edd1f790994976742d0598469`
BLAKE2b-256	`88de1aeb394f99469f925546c2b93254bcafadfaa984d3cdef7da94d11f7ddd4`

Algorithm	Hash digest
SHA256	`5eed8e28f38e972f9a760dfdbbf62c61d65ed9832918d4949551bb7338b1e702`
MD5	`d3e487431e9a38d06fe80ea3212be1cb`
BLAKE2b-256	`a558500843838b43f0413a98e0354bd1d49f9ad12b6b7f0e5f28aa60ab8d754b`

Algorithm	Hash digest
SHA256	`d569ed701f3bc9f0d4b504ee299a7e50203b016ca8e47dcf42d61bd6281c42a5`
MD5	`68a352f72cb13a6d9177d42cada8cd21`
BLAKE2b-256	`38478957ea36feb239671e474156232b446c418b648781aa863d8fb63b41d213`

Algorithm	Hash digest
SHA256	`f21129e3826ffea069eb601f72bc14baffee11d5ca13641bd80e794d3e77fdc9`
MD5	`8519873c24060f9e03ba23496636e8d4`
BLAKE2b-256	`d581ac883715ea9b7719eece17118889b5b00090c69e31cfa64456e2caea2b52`

Algorithm	Hash digest
SHA256	`b9ca045ae377cc8472af2683cebf3a222326dd28f196bde1919401fb83b814cf`
MD5	`1efd8e3cf68b3f756cf703b92ee0ce60`
BLAKE2b-256	`cea99e815eabc1a8582dcbaae8735d06802569c19f64a9a876c5c8385dc2cb9e`

Algorithm	Hash digest
SHA256	`a8a6a86e92024403ac9d21a5cb31d9bc6ba6ee563b46b3ab80307d174ae9099a`
MD5	`2f5e6a692e912075a182ea884012fed2`
BLAKE2b-256	`7a1489166aa15cb77618cf045e9a3dc6fce0250706e5b8c2ebe3072c6fb9620a`

mattress 0.4.3

Python bindings for tatami

Overview

Instructions

Supported matrices

Utility methods

Operating on an existing pointer

Extending to custom matrices

Project links

Key dates

2 maintainers

Credits

GitHub Statistics

License

Requires

Provides Extra

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Algorithm	Hash digest
SHA256	`a379eefa8ff6ad77685348fb7981548e8e2e063bb10d47d3e951e3cf1e05c7e9`
MD5	`036e3f71e8098aeb3405850dc1b31931`
BLAKE2b-256	`6e07c03241152a5733fc8b20d082930df5ed9a6c47ff7ae65e49028952558c20`

Algorithm	Hash digest
SHA256	`da04068b28eab9dff944adb48cf2959a3913b41940ec4a267a8f56651dbe99c5`
MD5	`2e0be8013f754375caa31bc26301e484`
BLAKE2b-256	`119b751de72e8196bbd3e5b0e2ae9c87c254c95bf31cd5bbed497b184ed2d965`

Algorithm	Hash digest
SHA256	`876734a48678a569be95860069d354fceeaec38d24bd92916d0f4dea0be24741`
MD5	`7d7b22d7d9b6885571cc4a5da9c97fd5`
BLAKE2b-256	`7a129ebf4e71ac5bdf6fde7579aae9bb89352b9817d57b357d9ef1660102fd7a`

Algorithm	Hash digest
SHA256	`528df3f0b271d212c1901a0f381da0be9a49df8833a4842dcc488061e6079009`
MD5	`8c51a637914a3f1ac34a486c1c0b530c`
BLAKE2b-256	`eefa5dfc68892092f9751be396ce41cc37e3245e011dbdceaf2a1f4faa91421a`

Algorithm	Hash digest
SHA256	`f7fd3e933f06ddcb9f127cbd9d629d782337baee5f40b9fcb6466e51fc7abeae`
MD5	`3254d507f1abaac0a035e73a6ae99146`
BLAKE2b-256	`edd347ac2f4c11c272c1e7a8043ab3d1950a0fe5f2da2f1666ffe9d59a0dd12b`

Algorithm	Hash digest
SHA256	`d45f4f1c688b213c82fa8644f0520ad8b31dcd39d5a2b5d19b0762548972dc39`
MD5	`78535d6a34567c0c78ee3bcdd50bdbe2`
BLAKE2b-256	`02a442297519532def98889cd0eb614e4e82728d10b41bc6f5015ef80bd5df7e`

Algorithm	Hash digest
SHA256	`fd01c7e1bfb5102df048aafb782871d511307d3847647ec1160587f222200374`
MD5	`eaf32e5dceb90f8347635c7658d6022e`
BLAKE2b-256	`891f9a963134e2d9150614567facabca5bebc3964ea04cd3febdad1926d18be3`

Algorithm	Hash digest
SHA256	`8f723346a8d1712c16ae97e6fb1fb7a14ab129afe4e1e1144eda5a2b9863e2f6`
MD5	`c29ac82e9c8da367af6d3d33af1a9161`
BLAKE2b-256	`704169c6348f67ac44b1ee76c9d858c9b4704fafe24590d146bfaccb76d7ca61`

Algorithm	Hash digest
SHA256	`c088a32f2b25b0886ecac097b0b956f202576e861140206d53df3edf22c0f45b`
MD5	`088119d54f628147b2520de0c24b5ba1`
BLAKE2b-256	`c83af10136bb963f45d73ae7d2ccad73e4af2fe6758466f3ff36419167dbfef1`

Algorithm	Hash digest
SHA256	`ec54c566993527673fac40833c2159aa34c57d2bbf8a049d93f2cbabc3f35001`
MD5	`8176fb5fea3fa8bf563353d7f4d14a66`
BLAKE2b-256	`e05b15b33c6fc947949b76bfe0f6e110a2211f6cfa62403c367ebc4da13236ef`