Tabmat

4.2.1 · active · verified Fri Apr 17

Tabmat provides efficient matrix representations for working with tabular data, designed to integrate seamlessly with various dataframe libraries. It offers specialized matrix types like DenseMatrix, CategoricalMatrix, and SplitMatrix for performance-critical statistical and machine learning tasks, especially useful for generalized linear models. The current version is 4.2.1, with an active development pace and frequent releases addressing bug fixes and new features.

Common errors

```
AttributeError: 'DenseMatrix' object has no attribute 'A'
```
cause Attempting to access the underlying NumPy array using the `.A` attribute, which was removed in tabmat v4.0.0 when `DenseMatrix` stopped inheriting from `np.ndarray`.

fix Use `dense_matrix.unpack()` or `dense_matrix.toarray()` to get the underlying NumPy array for direct array manipulation.
```
TypeError: can't convert DenseMatrix to numpy.ndarray implicitly
```
cause Trying to pass a `DenseMatrix` directly where a `numpy.ndarray` is expected, due to the breaking change in tabmat v4.0.0 that removed direct inheritance from `np.ndarray`.

fix Explicitly convert the `DenseMatrix` to a NumPy array using `dense_matrix.unpack()` or `dense_matrix.toarray()` before passing it to functions expecting a `np.ndarray`.
```
ERROR: Package 'tabmat' requires Python '>=3.10' but the running Python is 3.X.Y
```
cause Attempting to install or use tabmat version 4.2.0 or higher with an incompatible Python version (older than 3.10).

fix Upgrade your Python environment to 3.10 or newer. If an upgrade is not possible, install an older version of tabmat: `pip install "tabmat<4.2.0"`.
```
RuntimeError: buffer source array is read-only
```
cause Certain `CategoricalMatrix` methods or related internal operations in older tabmat versions were called with an immutable (read-only) NumPy array or buffer, which they attempted to modify.

fix Upgrade to tabmat version 4.2.1 or newer, which includes fixes for operating on read-only buffers. If an upgrade is not possible, ensure any input arrays are writable, e.g., by creating a copy: `my_array.copy(order='C')`.

Warnings

breaking As of v4.0.0, `DenseMatrix` and `SparseMatrix` no longer inherit from `numpy.ndarray` and `scipy.sparse.csc_matrix` respectively. Direct array-like access (e.g., `.A`) or implicit conversion will now fail.
Fix: Use the `.unpack()` method (or `.toarray()` for `DenseMatrix`) to explicitly convert to the underlying array type before performing operations that require a standard NumPy array or SciPy sparse matrix. For example, `dense_matrix.unpack()`.
breaking Tabmat v4.2.0 and later require Python 3.10 or newer. Installation via `pip` will fail with an incompatibility error on older Python versions.
Fix: Upgrade your Python environment to version 3.10 or higher. If unable to upgrade, install an older version of tabmat, e.g., `pip install "tabmat<4.2.0"`.
gotcha Methods of `CategoricalMatrix` and related internal functions in versions prior to 4.2.1/4.1.3 might raise a `RuntimeError` when operating on read-only buffers (e.g., NumPy arrays with `writeable=False`).
Fix: Upgrade to tabmat >=4.2.1, which includes fixes for read-only buffer handling across various matrix operations. If upgrading is not an option, ensure that any input arrays passed to tabmat methods are writable (e.g., by making a copy: `my_array.copy()`).
gotcha `tabmat.from_df` and `tabmat.from_formula` now use `narwhals`' v2 API and support a wider range of dataframes (including `polars`). While this enhances compatibility, users should be aware of potential subtle behavioral changes if they were relying on specific `pandas` dataframe quirks or older `narwhals` API behavior.
Fix: Test your existing code with the new versions. Consult the `narwhals` documentation if you encounter unexpected behavior, especially when working with non-pandas dataframes or specific dataframe operations.

Install

pip install tabmat Install tabmat

Imports

from_df
```
from tabmat import from_df
```
from_formula
```
from tabmat import from_formula
```
DenseMatrix
wrong:
```
import tabmat.DenseMatrix
```
correct:
```
from tabmat import DenseMatrix
```
Class is directly in the tabmat package, not a submodule.
CategoricalMatrix
```
from tabmat import CategoricalMatrix
```
SplitMatrix
```
from tabmat import SplitMatrix
```

Quickstart

This quickstart demonstrates how to create a `SplitMatrix` from a pandas DataFrame using `tabmat.from_df`. It automatically handles different column types, applying standardization and one-hot encoding as specified. The example then shows how to perform a matrix-vector multiplication, a common operation for `tabmat` objects.

import pandas as pd
import tabmat as tm
import numpy as np

# Create a sample DataFrame
df = pd.DataFrame({"numeric_col": [1, 2, 3, 4],
                   "categorical_col": ["A", "B", "A", "C"],
                   "bool_col": [True, False, True, False]})

# Create a SplitMatrix from the DataFrame, standardizing numeric columns
# and dropping the first level for categorical encoding
matrix = tm.from_df(df, standardize=True, drop_first=True)

print(f"Matrix shape: {matrix.shape}")
print(f"Matrix parts (e.g., DenseMatrix, CategoricalMatrix): {matrix.matrices}")

# Example of matrix-vector multiplication
vec = np.random.rand(matrix.shape[1])
result = matrix.matvec(vec)
print(f"Result of matvec (first 5 elements): {result[:5]}")

view raw JSON →