Fast Array Utilities

Common errors

• ModuleNotFoundError: No module named 'fast_array_utils.stats'

  cause The `stats` submodule (and `numba` submodule) depends on `numba` for accelerated operations. This dependency is optional and must be installed via an 'extra' package.
  fix Install `fast-array-utils` with the 'accel' extra: `pip install 'fast-array-utils[accel]'`.

• TypeError: Cannot convert array-like to SparseArray: expecting 1D or 2D array, got a 0D array

  cause This (or similar `TypeError`s related to array shape or type) indicates that the array being passed to a utility function is not in a format or shape that `fast-array-utils` expects for that particular operation. For instance, some functions might expect 2D arrays, or specific sparse formats.
  fix Inspect the array type and shape. Ensure it matches the requirements of the `fast-array-utils` function being called. Convert the array to a supported type (e.g., `numpy.ndarray`, `scipy.sparse.csr_matrix`) and reshape if necessary.

Warnings

• gotcha The `fast_array_utils.stats` and `fast_array_utils.numba` submodules require `numba` for their functionality. These are installed via the `accel` extra (e.g., `pip install 'fast-array-utils[accel]'`). Without this, attempts to import or use functions from these modules will result in `ImportError` or `ModuleNotFoundError`.
  Fix: Install the library with the `accel` extra: `pip install 'fast-array-utils[accel]'`.
• gotcha The library is designed to work efficiently with specific array types: `numpy.ndarray`, `scipy.sparse.cs{rc}_{array,matrix}`, `cupy.ndarray`, `cupyx.scipy.sparse.cs{rc}_matrix`, `dask.array.Array`, `h5py.Dataset`, `zarr.Array`, and `anndata.abc.CS{CR}Dataset`. Passing unsupported array types may lead to unexpected `TypeError` or incorrect behavior, particularly when using conversion or statistical functions.
  Fix: Ensure that input arrays conform to one of the explicitly supported types. Convert arrays if necessary before passing them to `fast-array-utils` functions.
• gotcha The library primarily operates on Python 3.12 and newer. While some older versions might support Python 3.11, the official documentation for version 1.4 and current PyPI metadata specify a minimum requirement of Python >=3.12.
  Fix: Ensure your Python environment is running Python 3.12 or higher. Upgrade Python if needed.

Install

• pip install fast-array-utils Base installation
• pip install 'fast-array-utils[accel]' With Numba acceleration (for stats and numba modules)
• pip install 'fast-array-utils[testing]' With testing utilities

Imports

• to_dense

  from fast_array_utils.conv import to_dense

• stats

  from fast_array_utils import stats

• conv

  from fast_array_utils import conv

Quickstart

This quickstart demonstrates converting a sparse matrix to a dense NumPy array using `to_dense` from the `conv` submodule and calculating statistics like sums and means using the `stats` submodule. Note that the `stats` submodule requires the optional `accel` dependencies to be installed.

import numpy as np
from scipy.sparse import csr_matrix
from fast_array_utils.conv import to_dense
from fast_array_utils import stats

# Example with to_dense
sparse_matrix = csr_matrix(np.array([[0, 1, 0], [1, 0, 2], [0, 0, 0]]))
numpy_arr = to_dense(sparse_matrix)
print(f"Dense array from sparse matrix:\n{numpy_arr}")

# Example with stats module (requires 'fast-array-utils[accel]' to be installed)
try:
    data_2d = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
    col_sums = stats.sum(data_2d, axis=0)
    mean_val = stats.mean(data_2d)
    print(f"\nColumn sums: {col_sums}")
    print(f"Mean value: {mean_val}")
except ImportError:
    print("\nSkipping stats examples: 'fast-array-utils[accel]' not installed.")