Skip to content

API Reference

parafac2

Main exports.

CSRMatrix

Bases: Matrix

A SciPy CSR array with optional implicit mean-centering.

The norms expand ||X - 1 mu^T||^2 into sum-of-squares and cross terms over the stored nonzeros, so a centered norm never densifies X.

Parameters:

Name Type Description Default
mat csr_array

The sparse data matrix of shape (n_rows, n_cols). Any SciPy sparse format is accepted and converted to CSR.

required
means ndarray | None

Per-column means to subtract implicitly.

None
Source code in parafac2/matrix.py
class CSRMatrix(Matrix):
    """A SciPy CSR array with optional implicit mean-centering.

    The norms expand ``||X - 1 mu^T||^2`` into sum-of-squares and cross terms
    over the stored nonzeros, so a centered norm never densifies ``X``.

    Parameters
    ----------
    mat : csr_array
        The sparse data matrix of shape ``(n_rows, n_cols)``. Any SciPy
        sparse format is accepted and converted to CSR.
    means : np.ndarray | None, default None
        Per-column means to subtract implicitly.
    """

    def __init__(self, mat: Any, means: np.ndarray | None = None) -> None:
        self.mat = mat if isinstance(mat, csr_array) else csr_array(mat)
        super().__init__(self.mat.shape, self.mat.dtype, means)

    def _mkl_dot(self) -> Any:
        """MKL's kernel if it is installed and it supports this dtype.

        MKL needs single- or double-precision data; the operand's dtype and
        layout are already guaranteed by :meth:`Matrix._operand`.
        """
        if self.dtype not in (np.float32, np.float64):
            return None
        return mkl_dot()

    def _matmul(self, rhs: np.ndarray) -> np.ndarray:
        dot = self._mkl_dot()
        return self.mat @ rhs if dot is None else dot(self.mat, rhs)

    def _rmatmul(self, lhs: np.ndarray) -> np.ndarray:
        dot = self._mkl_dot()
        return lhs @ self.mat if dot is None else dot(lhs, self.mat)

    def norm_sq(self) -> float:
        data = self.mat.data
        if self.means is None:
            return float(np.sum(data**2))
        term1 = np.sum(data**2)
        term2 = -2.0 * np.sum(data * self.means[self.mat.indices])
        term3 = self.shape[0] * np.sum(self.means**2)
        return float(term1 + term2 + term3)

    def slice_norms(self, condition_idxs: np.ndarray, n_cond: int) -> np.ndarray:
        idxs = np.asarray(condition_idxs)
        group_of_nnz = np.repeat(idxs, np.diff(self.mat.indptr))
        data = self.mat.data.astype(np.float64)
        sums_sq = np.bincount(group_of_nnz, weights=data**2, minlength=n_cond)
        if self.means is None:
            return np.sqrt(sums_sq)

        counts = np.bincount(idxs, minlength=n_cond).astype(np.float64)
        cross = np.bincount(
            group_of_nnz,
            weights=data * self.means[self.mat.indices],
            minlength=n_cond,
        )
        mean_sq_total = np.sum(self.means**2)
        return np.sqrt(np.maximum(sums_sq - 2.0 * cross + counts * mean_sq_total, 0.0))

    def to_device(self, backend: str | None = None) -> Matrix:
        chosen = get_backend(backend)
        if chosen == "cupy":
            return DeviceMatrix(
                self, to_cupy_csr(self.mat), cupy_csr_matmul, cupy_csr_rmatmul
            )
        if chosen == "mlx":
            return DeviceMatrix(
                self, to_mlx_csr(self.mat), mlx_csr_matmul, mlx_csr_rmatmul
            )
        return self

CompressedData dataclass

Compressed representation of a multi-condition single-cell dataset.

Stores the small dense per-condition cores and the orthonormal bases for the gene mode (Q) and cell mode (Q_k), enabling fast rank sweeps without touching the raw data again.

Source code in parafac2/compress.py
@dataclass
class CompressedData:
    """Compressed representation of a multi-condition single-cell dataset.

    Stores the small dense per-condition cores and the orthonormal bases for
    the gene mode (``Q``) and cell mode (``Q_k``), enabling fast rank sweeps
    without touching the raw data again.
    """

    cores: list[np.ndarray]
    """List of length ``n_cond`` with dense cores ``Y_k`` of shape ``(L_c_k, L_g)``."""

    Q: np.ndarray
    """Gene projection basis of shape ``(n_genes, L_g)`` with orthonormal columns."""

    Q_k: list[np.ndarray | None] | None
    """Per-condition cell projection bases ``(n_cells_k, L_c_k)`` or ``None``."""

    condition_unique_idxs: np.ndarray
    """Integer condition indices for each cell."""

    norm_tensor: float
    """Total squared Frobenius norm of the original mean-centered dataset."""

    lost_var: float
    """Variance discarded by the compression projectors."""

    total_cells: int
    """Total number of cells across all conditions."""

    n_genes: int
    """Number of genes in the uncompressed dataset."""

    n_cond: int
    """Number of conditions."""

    slice_weights: np.ndarray | None = None
    """Optional per-condition slice weights for normalized ALS."""

    norm_weighted: float | None = None
    """Squared norm of the weighted slices ``w_k X_k``, set with ``slice_weights``."""

    means: np.ndarray | None = None
    """Per-gene means subtracted during compression."""

    adata: anndata.AnnData | None = None
    """Reference to original AnnData object if available."""

    @property
    def L_g(self) -> int:
        """Gene compression dimension."""
        return self.Q.shape[1]

    @property
    def max_cell_dim(self) -> int:
        """Maximum cell dimension across cores."""
        return max(c.shape[0] for c in self.cores)

L_g property

Gene compression dimension.

Q instance-attribute

Gene projection basis of shape (n_genes, L_g) with orthonormal columns.

Q_k instance-attribute

Per-condition cell projection bases (n_cells_k, L_c_k) or None.

adata = None class-attribute instance-attribute

Reference to original AnnData object if available.

condition_unique_idxs instance-attribute

Integer condition indices for each cell.

cores instance-attribute

List of length n_cond with dense cores Y_k of shape (L_c_k, L_g).

lost_var instance-attribute

Variance discarded by the compression projectors.

max_cell_dim property

Maximum cell dimension across cores.

means = None class-attribute instance-attribute

Per-gene means subtracted during compression.

n_cond instance-attribute

Number of conditions.

n_genes instance-attribute

Number of genes in the uncompressed dataset.

norm_tensor instance-attribute

Total squared Frobenius norm of the original mean-centered dataset.

norm_weighted = None class-attribute instance-attribute

Squared norm of the weighted slices w_k X_k, set with slice_weights.

slice_weights = None class-attribute instance-attribute

Optional per-condition slice weights for normalized ALS.

total_cells instance-attribute

Total number of cells across all conditions.

DenseMatrix

Bases: Matrix

A dense NumPy array with optional implicit mean-centering.

Parameters:

Name Type Description Default
mat ndarray

The dense data matrix of shape (n_rows, n_cols).

required
means ndarray | None

Per-column means to subtract implicitly.

None
Source code in parafac2/matrix.py
class DenseMatrix(Matrix):
    """A dense NumPy array with optional implicit mean-centering.

    Parameters
    ----------
    mat : np.ndarray
        The dense data matrix of shape ``(n_rows, n_cols)``.
    means : np.ndarray | None, default None
        Per-column means to subtract implicitly.
    """

    def __init__(self, mat: np.ndarray, means: np.ndarray | None = None) -> None:
        self.mat = np.asarray(mat)
        super().__init__(self.mat.shape, self.mat.dtype, means)

    def _matmul(self, rhs: np.ndarray) -> np.ndarray:
        return self.mat @ rhs

    def _rmatmul(self, lhs: np.ndarray) -> np.ndarray:
        return lhs @ self.mat

    def norm_sq(self) -> float:
        if self.means is None:
            return float(np.sum(self.mat**2))
        return float(np.sum((self.mat - self.means) ** 2))

    def slice_norms(self, condition_idxs: np.ndarray, n_cond: int) -> np.ndarray:
        idxs = np.asarray(condition_idxs)
        centered = self.mat if self.means is None else self.mat - self.means
        row_sums_sq = np.sum(centered**2, axis=1)
        return np.sqrt(np.bincount(idxs, weights=row_sums_sq, minlength=n_cond))

    def to_device(self, backend: str | None = None) -> Matrix:
        chosen = get_backend(backend)
        if chosen == "cupy":
            return DeviceMatrix(
                self, to_cupy_dense(self.mat), cupy_dense_matmul, cupy_dense_rmatmul
            )
        if chosen == "mlx":
            return DeviceMatrix(
                self, to_mlx_dense(self.mat), mlx_dense_matmul, mlx_dense_rmatmul
            )
        return self

Matrix

Bases: ABC

Base class implementing the duck-typed matrix contract.

Subclasses supply the raw products (:meth:_matmul/:meth:_rmatmul, which receive an operand already cast to self.dtype and made C-contiguous) and the two norms. This class layers the shared parts on top: operand coercion, the float64 result contract, and the implicit mean-centering, which is applied as a rank-1 correction to the (small) product rather than by materializing X - 1 mu^T.

Parameters:

Name Type Description Default
shape tuple[int, int]

The matrix's (n_rows, n_cols) shape.

required
dtype dtype

The dtype products are taken in.

required
means ndarray | None

Per-column means to subtract implicitly. None or an all-zero array means no centering.

None
Source code in parafac2/matrix.py
class Matrix(ABC):
    """Base class implementing the duck-typed matrix contract.

    Subclasses supply the raw products (:meth:`_matmul`/:meth:`_rmatmul`,
    which receive an operand already cast to ``self.dtype`` and made
    C-contiguous) and the two norms. This class layers the shared parts on
    top: operand coercion, the float64 result contract, and the implicit
    mean-centering, which is applied as a rank-1 correction to the (small)
    product rather than by materializing ``X - 1 mu^T``.

    Parameters
    ----------
    shape : tuple[int, int]
        The matrix's ``(n_rows, n_cols)`` shape.
    dtype : np.dtype
        The dtype products are taken in.
    means : np.ndarray | None, default None
        Per-column means to subtract implicitly. ``None`` or an all-zero
        array means no centering.
    """

    __array_priority__ = 1000
    __array_ufunc__ = None

    def __init__(
        self,
        shape: tuple[int, int],
        dtype: Any,
        means: np.ndarray | None = None,
    ) -> None:
        self.shape = (int(shape[0]), int(shape[1]))
        self.dtype = np.dtype(dtype)
        self.means = _clean_means(means)

    @abstractmethod
    def _matmul(self, rhs: np.ndarray) -> np.ndarray:
        """Compute the uncentered ``self @ rhs``."""

    @abstractmethod
    def _rmatmul(self, lhs: np.ndarray) -> np.ndarray:
        """Compute the uncentered ``lhs @ self``."""

    @abstractmethod
    def norm_sq(self) -> float:
        """Return the squared Frobenius norm of the (centered) matrix."""

    @abstractmethod
    def slice_norms(self, condition_idxs: np.ndarray, n_cond: int) -> np.ndarray:
        """Return the per-condition Frobenius norms of the (centered) rows.

        Parameters
        ----------
        condition_idxs : np.ndarray
            Integer array assigning each row to a condition in ``[0, n_cond)``.
        n_cond : int
            The total number of conditions.
        """

    def to_device(self, backend: str | None = None) -> Matrix:
        """Return this matrix with its data resident on ``backend``."""
        raise NotImplementedError

    def _operand(self, arr: np.ndarray) -> np.ndarray:
        """Cast a dense operand to this matrix's dtype and C-contiguous layout.

        Taking the product in ``X``'s own dtype matters: handing a float64
        operand to a float32 sparse ``X`` makes SciPy upcast the *whole*
        sparse matrix, doubling both the memory traffic that dominates the
        fit and the peak memory.
        """
        return np.ascontiguousarray(arr, dtype=self.dtype)

    def __matmul__(self, rhs: np.ndarray) -> np.ndarray:
        """Compute ``(self - 1 mu^T) @ rhs`` as a float64 NumPy array."""
        rhs = np.asarray(rhs)
        prod = np.asarray(self._matmul(self._operand(rhs)), dtype=np.float64)
        if self.means is not None:
            prod -= self.means @ rhs
        return prod

    def __rmatmul__(self, lhs: np.ndarray) -> np.ndarray:
        """Compute ``lhs @ (self - 1 mu^T)`` as a float64 NumPy array."""
        lhs = np.asarray(lhs)
        prod = np.asarray(self._rmatmul(self._operand(lhs)), dtype=np.float64)
        if self.means is not None:
            if lhs.ndim == 1:
                prod -= lhs.sum() * self.means
            else:
                prod -= np.outer(lhs.sum(axis=1), self.means)
        return prod

__matmul__(rhs)

Compute (self - 1 mu^T) @ rhs as a float64 NumPy array.

Source code in parafac2/matrix.py
def __matmul__(self, rhs: np.ndarray) -> np.ndarray:
    """Compute ``(self - 1 mu^T) @ rhs`` as a float64 NumPy array."""
    rhs = np.asarray(rhs)
    prod = np.asarray(self._matmul(self._operand(rhs)), dtype=np.float64)
    if self.means is not None:
        prod -= self.means @ rhs
    return prod

__rmatmul__(lhs)

Compute lhs @ (self - 1 mu^T) as a float64 NumPy array.

Source code in parafac2/matrix.py
def __rmatmul__(self, lhs: np.ndarray) -> np.ndarray:
    """Compute ``lhs @ (self - 1 mu^T)`` as a float64 NumPy array."""
    lhs = np.asarray(lhs)
    prod = np.asarray(self._rmatmul(self._operand(lhs)), dtype=np.float64)
    if self.means is not None:
        if lhs.ndim == 1:
            prod -= lhs.sum() * self.means
        else:
            prod -= np.outer(lhs.sum(axis=1), self.means)
    return prod

norm_sq() abstractmethod

Return the squared Frobenius norm of the (centered) matrix.

Source code in parafac2/matrix.py
@abstractmethod
def norm_sq(self) -> float:
    """Return the squared Frobenius norm of the (centered) matrix."""

slice_norms(condition_idxs, n_cond) abstractmethod

Return the per-condition Frobenius norms of the (centered) rows.

Parameters:

Name Type Description Default
condition_idxs ndarray

Integer array assigning each row to a condition in [0, n_cond).

required
n_cond int

The total number of conditions.

required
Source code in parafac2/matrix.py
@abstractmethod
def slice_norms(self, condition_idxs: np.ndarray, n_cond: int) -> np.ndarray:
    """Return the per-condition Frobenius norms of the (centered) rows.

    Parameters
    ----------
    condition_idxs : np.ndarray
        Integer array assigning each row to a condition in ``[0, n_cond)``.
    n_cond : int
        The total number of conditions.
    """

to_device(backend=None)

Return this matrix with its data resident on backend.

Source code in parafac2/matrix.py
def to_device(self, backend: str | None = None) -> Matrix:
    """Return this matrix with its data resident on ``backend``."""
    raise NotImplementedError

GPUMatrix(mat, backend=None, means=None)

Deprecated alias for :func:to_gpu, kept for backwards compatibility.

The GPU-resident matrix is now just another implementation of the duck-typed contract (see :class:DeviceMatrix) rather than a separate wrapper class.

Source code in parafac2/matrix.py
def GPUMatrix(
    mat: Any, backend: str | None = None, means: np.ndarray | None = None
) -> Any:
    """Deprecated alias for :func:`to_gpu`, kept for backwards compatibility.

    The GPU-resident matrix is now just another implementation of the
    duck-typed contract (see :class:`DeviceMatrix`) rather than a separate
    wrapper class.
    """
    return to_gpu(mat, backend=backend, means=means)

as_linear_operator(mat, means=None)

Return mat as a SciPy :class:~scipy.sparse.linalg.LinearOperator.

This is how the data is handed to SciPy's decompositions (see :func:~parafac2.utils.randomized_svd_right): anything :func:as_matrix accepts becomes an operator without the decomposition ever learning what the data actually is or where it lives.

Parameters:

Name Type Description Default
mat Any

Anything :func:as_matrix accepts.

required
means ndarray | None

Per-column means to center by, as accepted by :func:as_matrix.

None

Returns:

Type Description
LinearOperator

An (n_rows, n_cols) float64 operator applying X @ rhs and lhs @ X.

Source code in parafac2/matrix.py
def as_linear_operator(mat: Any, means: np.ndarray | None = None) -> LinearOperator:
    """Return ``mat`` as a SciPy :class:`~scipy.sparse.linalg.LinearOperator`.

    This is how the data is handed to SciPy's decompositions (see
    :func:`~parafac2.utils.randomized_svd_right`): anything :func:`as_matrix`
    accepts becomes an operator without the decomposition ever learning what
    the data actually is or where it lives.

    Parameters
    ----------
    mat : Any
        Anything :func:`as_matrix` accepts.
    means : np.ndarray | None, default None
        Per-column means to center by, as accepted by :func:`as_matrix`.

    Returns
    -------
    LinearOperator
        An ``(n_rows, n_cols)`` float64 operator applying ``X @ rhs`` and
        ``lhs @ X``.
    """
    return _MatrixOperator(as_matrix(mat, means))

as_matrix(mat, means=None)

Return mat as something satisfying the duck-typed matrix contract.

This is the single place in the package that looks at the data's type: a NumPy array or SciPy sparse matrix is wrapped, and anything else is assumed to implement the contract itself and passed through untouched.

Parameters:

Name Type Description Default
mat Any

A NumPy array, a SciPy sparse matrix, or an object already implementing the contract (including a :class:Matrix).

required
means ndarray | None

Per-column means to center by. Only meaningful for a plain NumPy or SciPy input: a type that implements the contract itself already accounts for its own centering.

None

Returns:

Type Description
Any

A :class:DenseMatrix or :class:CSRMatrix for NumPy/SciPy input, otherwise mat itself.

Raises:

Type Description
ValueError

If a nonzero means is passed alongside a matrix that already handles its own centering.

Source code in parafac2/matrix.py
def as_matrix(mat: Any, means: np.ndarray | None = None) -> Any:
    """Return ``mat`` as something satisfying the duck-typed matrix contract.

    This is the single place in the package that looks at the data's type:
    a NumPy array or SciPy sparse matrix is wrapped, and anything else is
    assumed to implement the contract itself and passed through untouched.

    Parameters
    ----------
    mat : Any
        A NumPy array, a SciPy sparse matrix, or an object already
        implementing the contract (including a :class:`Matrix`).
    means : np.ndarray | None, default None
        Per-column means to center by. Only meaningful for a plain NumPy or
        SciPy input: a type that implements the contract itself already
        accounts for its own centering.

    Returns
    -------
    Any
        A :class:`DenseMatrix` or :class:`CSRMatrix` for NumPy/SciPy input,
        otherwise ``mat`` itself.

    Raises
    ------
    ValueError
        If a nonzero ``means`` is passed alongside a matrix that already
        handles its own centering.
    """
    if isinstance(mat, np.ndarray):
        return DenseMatrix(mat, means)
    if issparse(mat):
        return CSRMatrix(mat, means)

    if _clean_means(means) is not None:
        raise ValueError(
            f"{type(mat).__name__} implements its own centering, so passing a "
            "nonzero `means` alongside it is not supported."
        )
    return mat

compress_dataset(X_in, L='auto', rank=None, n_power_iter=20, random_state=None, normalize_slices=False, backend=None)

Compress an AnnData dataset in gene and cell modes.

Parameters:

Name Type Description Default
X_in AnnData

Input dataset with data in X_in.X, condition indices in X_in.obs["condition_unique_idxs"], and optional means in X_in.var["means"].

required
L int | tuple[int, int | None] | str | bool

Compression dimension(s). If "auto" or True, uses max(2 * rank, rank + 20) for both modes (with rank defaulting to 30 when it is None). If an int, sets both L_g = L and L_c = L. If a tuple (L_g, L_c), sets gene and cell dimensions individually (pass L_c=None for gene-only compression).

"auto"
rank int | None

Expected maximum rank to fit on the compressed data. Used when L="auto".

None
n_power_iter int

Maximum number of refinement iterations for the randomized SVD (see :func:~parafac2.utils.randomized_svd_right).

20
random_state int | Generator | None

Random seed or generator.

None
normalize_slices bool

Whether to precalculate slice weights for normalized ALS.

False
backend str | None

Compute backend for raw matrix products.

None

Returns:

Type Description
CompressedData

The compressed dataset ready for fast PARAFAC2 fitting.

Source code in parafac2/compress.py
def compress_dataset(
    X_in: anndata.AnnData,
    L: int | tuple[int, int | None] | str | bool = "auto",
    rank: int | None = None,
    n_power_iter: int = 20,
    random_state: int | np.random.Generator | None = None,
    normalize_slices: bool = False,
    backend: str | None = None,
) -> CompressedData:
    """Compress an AnnData dataset in gene and cell modes.

    Parameters
    ----------
    X_in : anndata.AnnData
        Input dataset with data in ``X_in.X``, condition indices in
        ``X_in.obs["condition_unique_idxs"]``, and optional means in
        ``X_in.var["means"]``.
    L : int | tuple[int, int | None] | str | bool, default "auto"
        Compression dimension(s). If ``"auto"`` or ``True``, uses
        ``max(2 * rank, rank + 20)`` for both modes (with ``rank`` defaulting
        to 30 when it is ``None``). If an int, sets
        both ``L_g = L`` and ``L_c = L``. If a tuple ``(L_g, L_c)``, sets
        gene and cell dimensions individually (pass ``L_c=None`` for
        gene-only compression).
    rank : int | None, default None
        Expected maximum rank to fit on the compressed data. Used when
        ``L="auto"``.
    n_power_iter : int, default 20
        Maximum number of refinement iterations for the randomized SVD
        (see :func:`~parafac2.utils.randomized_svd_right`).
    random_state : int | np.random.Generator | None, default None
        Random seed or generator.
    normalize_slices : bool, default False
        Whether to precalculate slice weights for normalized ALS.
    backend : str | None, default None
        Compute backend for raw matrix products.

    Returns
    -------
    CompressedData
        The compressed dataset ready for fast PARAFAC2 fitting.
    """
    (
        X_mat,
        condition_unique_idxs,
        means,
        norm_tensor,
        slice_weights,
        norm_weighted,
    ) = extract_dataset_info(X_in, normalize_slices=normalize_slices)
    total_cells, n_genes = X_mat.shape
    n_cond = int(np.amax(condition_unique_idxs)) + 1

    # Determine L_g and L_c
    target_rank = rank if rank is not None else 30
    # `L is True` has to be checked before the int branch: `bool` is a
    # subclass of `int`, so `compress=True` would otherwise be read as L=1.
    if L is True or (isinstance(L, str) and L == "auto"):
        # 2x the rank, with a +20 floor for small ranks. The 4x this used to
        # take was headroom for a less accurate gene basis; measured against
        # uncompressed converged fits at rank 30 on two single-cell datasets,
        # the retained R2X from 2x to 4x differs by 0.01-0.06 percentage
        # points (thomson 99.86% -> 99.87%, BAL 99.81% -> 99.87%), while the
        # compression itself takes about twice as long at 4x.
        auto_L = max(2 * target_rank, target_rank + 20)
        L_g_val = min(n_genes, auto_L)
        L_c_val: int | None = auto_L
    elif isinstance(L, tuple):
        L_g_val, L_c_val = L
        L_g_val = min(n_genes, L_g_val)
    elif isinstance(L, (int, np.integer)):
        L_g_val = min(n_genes, int(L))
        L_c_val = int(L)
    else:
        raise ValueError(f"Invalid compression parameter L: {L}")

    X_raw = to_gpu(X_mat, backend=backend)
    X_c, Q, _norm_Xc_sq = compress_genes(
        X_raw,
        L_g=L_g_val,
        n_power_iter=n_power_iter,
        random_state=random_state,
        row_weights=None
        if slice_weights is None
        else slice_weights[condition_unique_idxs],
    )

    cores, Q_k, norm_cores_sq = compress_cells(
        X_c,
        condition_unique_idxs,
        L_c=L_c_val,
    )

    lost_var = float(np.maximum(0.0, norm_tensor - norm_cores_sq))

    return CompressedData(
        cores=cores,
        Q=Q,
        Q_k=Q_k,
        condition_unique_idxs=condition_unique_idxs,
        norm_tensor=norm_tensor,
        lost_var=lost_var,
        total_cells=total_cells,
        n_genes=n_genes,
        n_cond=n_cond,
        slice_weights=slice_weights,
        norm_weighted=norm_weighted,
        means=means,
        adata=X_in,
    )

get_backend(backend=None)

Return the requested backend, or auto-detect the first available one.

Parameters:

Name Type Description Default
backend str

One of 'mlx', 'cupy', or 'cpu'. None consults PARAFAC2_BACKEND and then auto-detects.

None

Returns:

Type Description
str

The resolved backend name: 'mlx', 'cupy', or 'cpu'.

Source code in parafac2/backend.py
def get_backend(backend: str | None = None) -> str:
    """Return the requested backend, or auto-detect the first available one.

    Parameters
    ----------
    backend : str, optional
        One of ``'mlx'``, ``'cupy'``, or ``'cpu'``. ``None`` consults
        ``PARAFAC2_BACKEND`` and then auto-detects.

    Returns
    -------
    str
        The resolved backend name: ``'mlx'``, ``'cupy'``, or ``'cpu'``.
    """
    if backend is None:
        backend = os.environ.get(BACKEND_ENV_VAR) or None
        source = f"{BACKEND_ENV_VAR}="
    else:
        source = "backend="

    if backend is not None:
        backend_lower = backend.strip().lower()
        if backend_lower in _VALID_BACKENDS:
            return backend_lower
        raise ValueError(
            f"Unknown backend '{backend}' (from {source}{backend!r}). "
            f"Supported backends: 'mlx', 'cupy', 'cpu'."
        )

    if _cuda_is_usable():
        return "cupy"

    try:
        import mlx.core  # noqa: F401  # ty: ignore[unresolved-import]

        return "mlx"
    except ImportError:
        pass

    return "cpu"

parafac2_init(X, condition_unique_idxs, rank=3, means=None, random_state=None, n_oversamples=10, n_iter=20, norm_tensor=None, row_weights=None)

Compute initial factors using randomized SVD.

Parameters:

Name Type Description Default
X Any

The data matrix, stacked across all conditions, with shape (total_cells, n_genes). Any object satisfying the duck-typed contract in :mod:parafac2.matrix, or a plain NumPy/SciPy sparse matrix (wrapped here via :func:~parafac2.matrix.as_matrix).

required
condition_unique_idxs ndarray

Integer array of length total_cells giving each row's condition index.

required
rank int

The number of components to compute.

3
means ndarray | None

Per-gene means to mean-center X by, or None to skip centering. Only accepted for a plain NumPy/SciPy X; a matrix that handles its own centering must not be given one.

None
random_state int | Generator | None

Seed or generator controlling the random projection used by the randomized SVD.

None
n_oversamples int

Extra dimensions added to rank when forming the random projection, to improve the accuracy of the randomized SVD.

10
n_iter int

Maximum number of LOBPCG refinement iterations applied to the randomized SVD's subspace.

20
norm_tensor float | None

Precomputed squared Frobenius norm of the mean-centered X. If None, it is computed via X.norm_sq().

None
row_weights ndarray | None

Per-row weights; if given, C comes from the row-weighted data.

None

Returns:

Type Description
tuple[list[ndarray], float]

The initial [A, B, C] factor matrices (with A all-ones, B the identity, and C the top right-singular vectors of the mean-centered X), and the squared Frobenius norm norm_tensor.

Source code in parafac2/parafac2.py
def parafac2_init(
    X: Any,
    condition_unique_idxs: np.ndarray,
    rank: int = 3,
    means: np.ndarray | None = None,
    random_state: int | np.random.Generator | None = None,
    n_oversamples: int = 10,
    n_iter: int = 20,
    norm_tensor: float | None = None,
    row_weights: np.ndarray | None = None,
) -> tuple[list[np.ndarray], float]:
    """Compute initial factors using randomized SVD.

    Parameters
    ----------
    X : Any
        The data matrix, stacked across all conditions, with shape
        ``(total_cells, n_genes)``. Any object satisfying the duck-typed
        contract in :mod:`parafac2.matrix`, or a plain NumPy/SciPy sparse
        matrix (wrapped here via :func:`~parafac2.matrix.as_matrix`).
    condition_unique_idxs : np.ndarray
        Integer array of length ``total_cells`` giving each row's condition
        index.
    rank : int, default 3
        The number of components to compute.
    means : np.ndarray | None, default None
        Per-gene means to mean-center ``X`` by, or ``None`` to skip
        centering. Only accepted for a plain NumPy/SciPy ``X``; a matrix
        that handles its own centering must not be given one.
    random_state : int | np.random.Generator | None, default None
        Seed or generator controlling the random projection used by the
        randomized SVD.
    n_oversamples : int, default 10
        Extra dimensions added to ``rank`` when forming the random
        projection, to improve the accuracy of the randomized SVD.
    n_iter : int, default 20
        Maximum number of LOBPCG refinement iterations applied to the
        randomized SVD's subspace.
    norm_tensor : float | None, default None
        Precomputed squared Frobenius norm of the mean-centered ``X``. If
        ``None``, it is computed via ``X.norm_sq()``.
    row_weights : np.ndarray | None, default None
        Per-row weights; if given, ``C`` comes from the row-weighted data.

    Returns
    -------
    tuple[list[np.ndarray], float]
        The initial ``[A, B, C]`` factor matrices (with ``A`` all-ones,
        ``B`` the identity, and ``C`` the top right-singular vectors of the
        mean-centered ``X``), and the squared Frobenius norm ``norm_tensor``.
    """
    X = as_matrix(X, means)
    n_cond = int(np.amax(condition_unique_idxs)) + 1
    if norm_tensor is None:
        norm_tensor = float(X.norm_sq())

    C = randomized_svd_right(
        X,
        n_components=rank,
        n_oversamples=n_oversamples,
        n_power_iter=n_iter,
        random_state=random_state,
        row_weights=row_weights,
    )

    factors = [
        np.ones((n_cond, rank), dtype=np.float64),
        np.eye(rank, dtype=np.float64),
        C,
    ]
    return factors, norm_tensor

parafac2_nd(X_in, rank, n_iter_max=100, tol=1e-06, random_state=None, callback=None, backend=None, normalize_slices=False, n_inner=1, compress=None, n_power_iter=20, fix_B_identity=False)

The same interface as regular PARAFAC2 with optional CANDELINC compression.

If compress is specified (or if X_in is already a :class:~parafac2.compress.CompressedData), PARAFAC2 is fit in the compressed subspace (Bro's "compress-then-fit"), eliminating per-sweep raw data passes.

If normalize_slices is True, each condition is weighted by the inverse of its (mean-centered) Frobenius norm, so every condition counts equally in the fit regardless of its cell count or variance. The fit is that of the rescaled slices X_k / ||X_k|| (X itself is never copied or modified), so tol and callback follow their error. The returned A is in data units and R2X is the unweighted fraction of variance explained, comparable to an unweighted fit.

Parameters:

Name Type Description Default
X_in AnnData | CompressedData

Input dataset with the (optionally sparse) data matrix in X_in.X, condition labels in X_in.obs["condition_unique_idxs"], and optionally per-gene means in X_in.var["means"] (defaults to zero, i.e. no centering, if absent). Alternatively, a pre-compressed :class:~parafac2.compress.CompressedData object.

required
rank int

The number of components to fit.

required
n_iter_max int

Maximum number of ALS iterations.

100
tol float

Convergence tolerance: iteration stops once the (non-negative) decrease in relative error between successive iterations drops below this value.

1e-6
random_state int | None

Seed controlling the randomized SVD initialization.

None
callback Callable[[int, float, list[ndarray]], None] | None

Optional callback invoked after each iteration with the iteration index, the relative error, and the current factor matrices.

None
backend str | None

Compute backend to run matrix products on: one of 'mlx', 'cupy', or 'cpu'. If None, the first available accelerator is auto-detected (see :func:~parafac2.backend.get_backend).

None
normalize_slices bool

Whether to weight each condition by the inverse of its Frobenius norm, as described above.

False
n_inner int

Number of (projection, A, B) sub-iterations per sweep. These read the data only through the cached W, costing O(n_cells * rank^2) against the O(nnz * rank) of a raw-data product, so they are close to free on sparse inputs. Raising n_inner trades that cheap compute for fewer sweeps, and so for fewer raw-data passes: on structured test data, n_inner=2 cut the sweeps needed to reach a fixed error by ~20%, with little further gain beyond 3. Whether that is a net win depends on how strongly the raw-data products dominate, so it is worth benchmarking per dataset. The default of 1 reproduces the classic one-update-per-mode ALS sweep.

1
compress int | tuple[int, int | None] | str | bool | None

Compression mode. If None or False (default), exact ALS is used. If "auto" or True, sets compression dimensions automatically based on rank. If an integer, sets both gene and cell compression dimensions to that value. If a tuple (L_g, L_c), sets dimensions separately (pass L_c=None for gene-only compression). Ignored if X_in is already a :class:~parafac2.compress.CompressedData.

None
n_power_iter int

Maximum number of refinement iterations for the randomized SVD in the compression step (see :func:~parafac2.compress.compress_dataset). Ignored if compress is disabled or if X_in is already a :class:~parafac2.compress.CompressedData.

20
fix_B_identity bool

Whether to hold the B factor matrix fixed at the identity rather than fitting it. B is initialized to the identity either way, so this simply drops the mode-1 update from each ALS sweep; every other mode still sees B as usual. This constrains each condition's loading matrix to P_k diag(a_k), i.e. it ties component r to the r-th column of every projection, making the components directly comparable across conditions at the cost of some fit. The returned B is exactly the identity.

False

Returns:

Type Description
tuple[tuple[ndarray, list[ndarray], list[ndarray]], float]

A ((weights, factors, projections), R2X) tuple: the standardized weights and [A, B, C] factor matrices, the per-condition projection matrices P_k, and the final fraction of variance explained.

Source code in parafac2/parafac2.py
def parafac2_nd(
    X_in: anndata.AnnData | CompressedData,
    rank: int,
    n_iter_max: int = 100,
    tol: float = 1e-6,
    random_state: int | None = None,
    callback: Callable[[int, float, list[np.ndarray]], None] | None = None,
    backend: str | None = None,
    normalize_slices: bool = False,
    n_inner: int = 1,
    compress: int | tuple[int, int | None] | str | bool | None = None,
    n_power_iter: int = 20,
    fix_B_identity: bool = False,
) -> tuple[tuple[np.ndarray, list[np.ndarray], list[np.ndarray]], float]:
    r"""The same interface as regular PARAFAC2 with optional CANDELINC compression.

    If ``compress`` is specified (or if ``X_in`` is already a
    :class:`~parafac2.compress.CompressedData`), PARAFAC2 is fit in the
    compressed subspace (Bro's "compress-then-fit"), eliminating per-sweep raw
    data passes.

    If ``normalize_slices`` is True, each condition is weighted by the
    inverse of its (mean-centered) Frobenius norm, so every condition counts
    equally in the fit regardless of its cell count or variance. The fit is
    that of the rescaled slices ``X_k / ||X_k||`` (``X`` itself is never
    copied or modified), so ``tol`` and ``callback`` follow their error. The
    returned ``A`` is in data units and ``R2X`` is the unweighted fraction of
    variance explained, comparable to an unweighted fit.

    Parameters
    ----------
    X_in : anndata.AnnData | CompressedData
        Input dataset with the (optionally sparse) data matrix in ``X_in.X``,
        condition labels in ``X_in.obs["condition_unique_idxs"]``, and
        optionally per-gene means in ``X_in.var["means"]`` (defaults to zero,
        i.e. no centering, if absent). Alternatively, a pre-compressed
        :class:`~parafac2.compress.CompressedData` object.
    rank : int
        The number of components to fit.
    n_iter_max : int, default 100
        Maximum number of ALS iterations.
    tol : float, default 1e-6
        Convergence tolerance: iteration stops once the (non-negative)
        decrease in relative error between successive iterations drops
        below this value.
    random_state : int | None, default None
        Seed controlling the randomized SVD initialization.
    callback : Callable[[int, float, list[np.ndarray]], None] | None, default None
        Optional callback invoked after each iteration with the iteration
        index, the relative error, and the current factor matrices.
    backend : str | None, default None
        Compute backend to run matrix products on: one of ``'mlx'``,
        ``'cupy'``, or ``'cpu'``. If ``None``, the first available
        accelerator is auto-detected (see
        :func:`~parafac2.backend.get_backend`).
    normalize_slices : bool, default False
        Whether to weight each condition by the inverse of its Frobenius
        norm, as described above.
    n_inner : int, default 1
        Number of ``(projection, A, B)`` sub-iterations per sweep. These read
        the data only through the cached ``W``, costing ``O(n_cells *
        rank^2)`` against the ``O(nnz * rank)`` of a raw-data product, so
        they are close to free on sparse inputs. Raising ``n_inner`` trades
        that cheap compute for fewer sweeps, and so for fewer raw-data
        passes: on structured test data, ``n_inner=2`` cut the sweeps needed
        to reach a fixed error by ~20%, with little further gain beyond 3.
        Whether that is a net win depends on how strongly the raw-data
        products dominate, so it is worth benchmarking per dataset. The
        default of 1 reproduces the classic one-update-per-mode ALS sweep.
    compress : int | tuple[int, int | None] | str | bool | None, default None
        Compression mode. If ``None`` or ``False`` (default), exact ALS is
        used. If ``"auto"`` or ``True``, sets compression dimensions
        automatically based on ``rank``. If an integer, sets both gene and cell
        compression dimensions to that value. If a tuple ``(L_g, L_c)``, sets
        dimensions separately (pass ``L_c=None`` for gene-only compression).
        Ignored if ``X_in`` is already a
        :class:`~parafac2.compress.CompressedData`.
    n_power_iter : int, default 20
        Maximum number of refinement iterations for the randomized SVD in the
        compression step (see :func:`~parafac2.compress.compress_dataset`).
        Ignored if ``compress`` is disabled or if ``X_in`` is already a
        :class:`~parafac2.compress.CompressedData`.
    fix_B_identity : bool, default False
        Whether to hold the ``B`` factor matrix fixed at the identity rather
        than fitting it. ``B`` is initialized to the identity either way, so
        this simply drops the mode-1 update from each ALS sweep; every other
        mode still sees ``B`` as usual. This constrains each condition's
        loading matrix to ``P_k diag(a_k)``, i.e. it ties component ``r`` to
        the ``r``-th column of every projection, making the components
        directly comparable across conditions at the cost of some fit. The
        returned ``B`` is exactly the identity.

    Returns
    -------
    tuple[tuple[np.ndarray, list[np.ndarray], list[np.ndarray]], float]
        A ``((weights, factors, projections), R2X)`` tuple: the standardized
        weights and ``[A, B, C]`` factor matrices, the per-condition
        projection matrices ``P_k``, and the final fraction of variance
        explained.
    """
    # Verbose if this is not an automated build
    verbose = "CI" not in os.environ

    if isinstance(X_in, CompressedData):
        return _fit_parafac2_compressed(
            X_in,
            rank=rank,
            n_iter_max=n_iter_max,
            tol=tol,
            random_state=random_state,
            callback=callback,
            verbose=verbose,
            fix_B_identity=fix_B_identity,
        )

    if compress is not None and compress is not False:
        compressed = compress_dataset(
            X_in,
            L=compress,
            rank=rank,
            n_power_iter=n_power_iter,
            random_state=random_state,
            normalize_slices=normalize_slices,
            backend=backend,
        )
        return _fit_parafac2_compressed(
            compressed,
            rank=rank,
            n_iter_max=n_iter_max,
            tol=tol,
            random_state=random_state,
            callback=callback,
            verbose=verbose,
            fix_B_identity=fix_B_identity,
        )

    (
        X_mat,
        condition_unique_idxs,
        _means,
        norm_tensor,
        slice_weights,
        norm_weighted,
    ) = extract_dataset_info(X_in, normalize_slices=normalize_slices)

    n_cond = int(np.amax(condition_unique_idxs)) + 1
    min_cond_size = int(np.min(np.bincount(condition_unique_idxs, minlength=n_cond)))
    if min_cond_size < rank:
        raise ValueError(
            f"Rank ({rank}) cannot exceed the smallest condition's cell count "
            f"({min_cond_size}); every condition's projection matrix needs at "
            f"least `rank` cells to be orthonormal."
        )

    X_raw = to_gpu(X_mat, backend=backend)

    factors, _ = parafac2_init(
        X_raw,
        condition_unique_idxs,
        rank=rank,
        random_state=random_state,
        norm_tensor=norm_tensor,
        row_weights=None
        if slice_weights is None
        else slice_weights[condition_unique_idxs],
    )

    cond_slices = condition_slices(condition_unique_idxs, n_cond)

    # The error tracked is that of the weighted slices w_k X_k, whose
    # compressed slices are w_k S_k.
    w = np.ones(n_cond) if slice_weights is None else slice_weights
    norm_fit = norm_tensor if norm_weighted is None else norm_weighted

    # W depends only on C, so it stays valid across the A and B updates and is
    # recomputed only once C changes. Each sweep therefore costs exactly two
    # raw-data products: this one and the X^T @ H inside the mode-2 update.
    W = calc_W(X_raw, factors[2])
    projections, S = project_data(W, factors, cond_slices)
    errs = [calc_err(S * w[:, None, None], factors, norm_fit) / norm_fit]

    tq = tqdm(range(n_iter_max), disable=(not verbose), delay=0.5)
    for iteration in tq:
        # The (P, A, B) block reads the data only through the cached W, so
        # extra inner passes buy convergence at no raw-data cost.
        for _ in range(n_inner):
            factors = parafac_update(factors, 0, S, slice_weights=slice_weights)
            projections, S = project_data(W, factors, cond_slices)
            # B starts at the identity, so skipping its update leaves it there.
            if not fix_B_identity:
                factors = parafac_update(factors, 1, S, slice_weights=slice_weights)
                projections, S = project_data(W, factors, cond_slices)

        factors = parafac_update(
            factors,
            2,
            S,
            projections,
            X=X_raw,
            cond_slices=cond_slices,
            slice_weights=slice_weights,
        )

        # C changed, so refresh W; this also yields the projections and error
        # for the factors as they stand at the end of this sweep.
        W = calc_W(X_raw, factors[2])
        projections, S = project_data(W, factors, cond_slices)
        errs.append(calc_err(S * w[:, None, None], factors, norm_fit) / norm_fit)

        delta = errs[-2] - errs[-1]
        tq.set_postfix(error=errs[-1], R2X=1.0 - errs[-1], Δ=delta, refresh=False)
        if callback is not None:
            callback(iteration, errs[-1], factors)

        if 0 <= delta < tol:
            break

    R2X = 1 - errs[-1]
    if slice_weights is not None:
        # Map A back to data units and score it against the unweighted data.
        factors[0] = factors[0] / w[:, np.newaxis]
        R2X = 1 - calc_err(S, factors, norm_tensor) / norm_tensor

    # Standardize the results and return
    return standardize_pf2(factors, projections), R2X

prepare_dataset(X, condition_name, geneThreshold)

Preprocess and normalize an AnnData dataset for PARAFAC2 factorization.

Performs quality control filtering of low-count cells and low-expression genes, normalizes total cell counts and gene sums, applies a log10 transformation, and computes metadata required by PARAFAC2 (condition indices and gene means).

Parameters:

Name Type Description Default
X AnnData

Input single-cell dataset with raw count matrix stored in X.X (must be a sparse matrix with non-negative values).

required
condition_name str

Column name in X.obs identifying the sample or experimental condition grouping for each cell.

required
geneThreshold float

Minimum threshold fraction for gene inclusion. Genes with total counts less than geneThreshold * total_cells are filtered out.

required

Returns:

Type Description
AnnData

A filtered and normalized copy of the AnnData object. Contains the log-transformed normalized counts in X.X, integer condition codes in X.obs["condition_unique_idxs"], and per-gene mean expression values in X.var["means"].

Source code in parafac2/normalize.py
def prepare_dataset(
    X: anndata.AnnData, condition_name: str, geneThreshold: float
) -> anndata.AnnData:
    """Preprocess and normalize an AnnData dataset for PARAFAC2 factorization.

    Performs quality control filtering of low-count cells and low-expression
    genes, normalizes total cell counts and gene sums, applies a log10
    transformation, and computes metadata required by PARAFAC2 (condition
    indices and gene means).

    Parameters
    ----------
    X : anndata.AnnData
        Input single-cell dataset with raw count matrix stored in ``X.X``
        (must be a sparse matrix with non-negative values).
    condition_name : str
        Column name in ``X.obs`` identifying the sample or experimental
        condition grouping for each cell.
    geneThreshold : float
        Minimum threshold fraction for gene inclusion. Genes with total counts
        less than ``geneThreshold * total_cells`` are filtered out.

    Returns
    -------
    anndata.AnnData
        A filtered and normalized copy of the AnnData object. Contains the
        log-transformed normalized counts in ``X.X``, integer condition
        codes in ``X.obs["condition_unique_idxs"]``, and per-gene mean
        expression values in ``X.var["means"]``.
    """
    assert issparse(X.X)
    X_X_raw = cast("csr_array", X.X)
    assert np.amin(X_X_raw.data) >= 0.0

    # Filter out genes with too few reads, and cells with fewer than 10 counts
    cell_mask = np.ravel(X_X_raw.sum(axis=1)) > 10
    gene_mask = np.ravel(X_X_raw.sum(axis=0)) > (geneThreshold * X_X_raw.shape[0])

    if not cell_mask.any():
        raise ValueError(
            "prepare_dataset: no cells passed the count filter (every cell's "
            "total count is <= 10); check the input data."
        )
    if not gene_mask.any():
        raise ValueError(
            "prepare_dataset: no genes passed the count filter (every gene's "
            f"total count is <= {geneThreshold} * n_cells); check the input "
            "data or lower geneThreshold."
        )

    # Subset and materialize actual AnnData object before modifying X.X
    if cell_mask.all() and gene_mask.all():
        X = X.copy()
    else:
        X = X[cell_mask, gene_mask].copy()

    # Convert subset to csr_array and float32 data
    X.X = csr_array(X.X)
    X_X = cast("csr_array", X.X)

    if X_X.dtype != np.float32:
        X_X.data = X_X.data.astype(np.float32)

    ## Normalize total counts per cell
    # Keep the counts on a reasonable scale to avoid accuracy issues
    counts_per_cell = np.ravel(X_X.sum(axis=1)).astype(np.float32, copy=False)
    counts_per_cell /= np.median(counts_per_cell)
    # In-place CSR row scaling
    X_X.data /= np.repeat(counts_per_cell, np.diff(X_X.indptr))

    # Scale genes by sum, in-place CSR column scaling
    gene_sums = np.ravel(X_X.sum(axis=0)).astype(np.float32, copy=False)
    X_X.data /= gene_sums[X_X.indices]

    # Transform values in-place to avoid nnz-sized temporaries
    X_X.data *= np.float32(1000.0)
    X_X.data += np.float32(1.0)
    np.log10(X_X.data, out=X_X.data)

    # Get the indices for subsetting the data
    X.obs["condition_unique_idxs"] = pd.Categorical(X.obs[condition_name]).codes

    # Pre-calculate gene means
    X.var["means"] = np.ravel(X_X.mean(axis=0))

    return X

store_pf2(X, parafac2_output)

Store the Pf2 results into the anndata object.

Parameters:

Name Type Description Default
X AnnData | CompressedData

The dataset the factorization was fit on. Must have X.obs["condition_unique_idxs"] set (as produced by :func:~parafac2.normalize.prepare_dataset or equivalent). If a :class:~parafac2.compress.CompressedData is provided, factors are written to its underlying .adata object.

required
parafac2_output tuple[ndarray, list[ndarray], list[ndarray]]

The (weights, factors, projections) output of :func:parafac2_nd, where factors is the [A, B, C] factor matrices and projections is the per-condition projection matrices P_k.

required

Returns:

Type Description
AnnData

The target AnnData object, mutated in place, with the weights in X.uns["Pf2_weights"], factors in X.uns["Pf2_A"]/X.uns["Pf2_B"]/X.varm["Pf2_C"], and per-cell projections in X.obsm["projections"] and X.obsm["weighted_projections"] (projections composed with B).

Source code in parafac2/parafac2.py
def store_pf2(
    X: anndata.AnnData | CompressedData,
    parafac2_output: tuple[np.ndarray, list[np.ndarray], list[np.ndarray]],
) -> anndata.AnnData:
    """Store the Pf2 results into the anndata object.

    Parameters
    ----------
    X : anndata.AnnData | CompressedData
        The dataset the factorization was fit on. Must have
        ``X.obs["condition_unique_idxs"]`` set (as produced by
        :func:`~parafac2.normalize.prepare_dataset` or equivalent). If a
        :class:`~parafac2.compress.CompressedData` is provided, factors are
        written to its underlying ``.adata`` object.
    parafac2_output : tuple[np.ndarray, list[np.ndarray], list[np.ndarray]]
        The ``(weights, factors, projections)`` output of :func:`parafac2_nd`,
        where ``factors`` is the ``[A, B, C]`` factor matrices and
        ``projections`` is the per-condition projection matrices ``P_k``.

    Returns
    -------
    anndata.AnnData
        The target AnnData object, mutated in place, with the weights in
        ``X.uns["Pf2_weights"]``, factors in
        ``X.uns["Pf2_A"]``/``X.uns["Pf2_B"]``/``X.varm["Pf2_C"]``, and
        per-cell projections in ``X.obsm["projections"]`` and
        ``X.obsm["weighted_projections"]`` (projections composed with ``B``).
    """
    if isinstance(X, CompressedData):
        if X.adata is None:
            raise ValueError("CompressedData has no associated AnnData object.")
        target_adata = X.adata
        condition_unique_idxs = X.condition_unique_idxs
    else:
        target_adata = X
        condition_unique_idxs = target_adata.obs["condition_unique_idxs"]

    target_adata.uns["Pf2_weights"] = parafac2_output[0]
    target_adata.uns["Pf2_A"], target_adata.uns["Pf2_B"], target_adata.varm["Pf2_C"] = (
        parafac2_output[1]
    )

    target_adata.obsm["projections"] = np.zeros(
        (target_adata.shape[0], len(target_adata.uns["Pf2_weights"])), dtype=np.float32
    )
    for i, p in enumerate(parafac2_output[2]):
        target_adata.obsm["projections"][condition_unique_idxs == i, :] = p

    target_adata.obsm["weighted_projections"] = (
        target_adata.obsm["projections"] @ target_adata.uns["Pf2_B"]
    ).astype(np.float32, copy=False)

    return target_adata

to_gpu(mat, backend=None, means=None)

Wrap mat for the fit and move it to the resolved backend's device.

Parameters:

Name Type Description Default
mat Any

The matrix to (optionally) transfer, as accepted by :func:as_matrix.

required
backend str

One of 'mlx', 'cupy', or 'cpu'. If None, the first available accelerator is auto-detected (see :func:~parafac2.backend.get_backend).

None
means ndarray | None

Per-column means to center by, as accepted by :func:as_matrix.

None

Returns:

Type Description
Any

The device-resident matrix on a GPU backend, otherwise the CPU-resident one.

Raises:

Type Description
TypeError

If a GPU backend is selected for a duck-typed matrix that does not implement to_device.

Source code in parafac2/matrix.py
def to_gpu(
    mat: Any, backend: str | None = None, means: np.ndarray | None = None
) -> Any:
    """Wrap ``mat`` for the fit and move it to the resolved backend's device.

    Parameters
    ----------
    mat : Any
        The matrix to (optionally) transfer, as accepted by :func:`as_matrix`.
    backend : str, optional
        One of ``'mlx'``, ``'cupy'``, or ``'cpu'``. If ``None``, the first
        available accelerator is auto-detected (see
        :func:`~parafac2.backend.get_backend`).
    means : np.ndarray | None, default None
        Per-column means to center by, as accepted by :func:`as_matrix`.

    Returns
    -------
    Any
        The device-resident matrix on a GPU backend, otherwise the
        CPU-resident one.

    Raises
    ------
    TypeError
        If a GPU backend is selected for a duck-typed matrix that does not
        implement ``to_device``.
    """
    X = as_matrix(mat, means)
    chosen = get_backend(backend)
    if chosen == "cpu":
        return X

    to_device = getattr(X, "to_device", None)
    if to_device is None:
        raise TypeError(
            f"{type(X).__name__} does not implement `to_device`, so it cannot "
            f"run on the {chosen!r} backend. Pass backend='cpu', or convert "
            "it to a NumPy array or SciPy sparse array first."
        )
    return to_device(chosen)

parafac2.parafac2

parafac2.parafac2

Core PARAFAC2 decomposition routines.

Implements PARAFAC2 initialization (randomized SVD), the alternating-least- squares fitting loop, CANDELINC-style compression, and standardization/storage of the fitted factors and per-condition projections. Operates directly on a single (optionally sparse) data matrix held in an AnnData object, avoiding per-condition copies.

parafac2_init(X, condition_unique_idxs, rank=3, means=None, random_state=None, n_oversamples=10, n_iter=20, norm_tensor=None, row_weights=None)

Compute initial factors using randomized SVD.

Parameters:

Name Type Description Default
X Any

The data matrix, stacked across all conditions, with shape (total_cells, n_genes). Any object satisfying the duck-typed contract in :mod:parafac2.matrix, or a plain NumPy/SciPy sparse matrix (wrapped here via :func:~parafac2.matrix.as_matrix).

required
condition_unique_idxs ndarray

Integer array of length total_cells giving each row's condition index.

required
rank int

The number of components to compute.

3
means ndarray | None

Per-gene means to mean-center X by, or None to skip centering. Only accepted for a plain NumPy/SciPy X; a matrix that handles its own centering must not be given one.

None
random_state int | Generator | None

Seed or generator controlling the random projection used by the randomized SVD.

None
n_oversamples int

Extra dimensions added to rank when forming the random projection, to improve the accuracy of the randomized SVD.

10
n_iter int

Maximum number of LOBPCG refinement iterations applied to the randomized SVD's subspace.

20
norm_tensor float | None

Precomputed squared Frobenius norm of the mean-centered X. If None, it is computed via X.norm_sq().

None
row_weights ndarray | None

Per-row weights; if given, C comes from the row-weighted data.

None

Returns:

Type Description
tuple[list[ndarray], float]

The initial [A, B, C] factor matrices (with A all-ones, B the identity, and C the top right-singular vectors of the mean-centered X), and the squared Frobenius norm norm_tensor.

Source code in parafac2/parafac2.py
def parafac2_init(
    X: Any,
    condition_unique_idxs: np.ndarray,
    rank: int = 3,
    means: np.ndarray | None = None,
    random_state: int | np.random.Generator | None = None,
    n_oversamples: int = 10,
    n_iter: int = 20,
    norm_tensor: float | None = None,
    row_weights: np.ndarray | None = None,
) -> tuple[list[np.ndarray], float]:
    """Compute initial factors using randomized SVD.

    Parameters
    ----------
    X : Any
        The data matrix, stacked across all conditions, with shape
        ``(total_cells, n_genes)``. Any object satisfying the duck-typed
        contract in :mod:`parafac2.matrix`, or a plain NumPy/SciPy sparse
        matrix (wrapped here via :func:`~parafac2.matrix.as_matrix`).
    condition_unique_idxs : np.ndarray
        Integer array of length ``total_cells`` giving each row's condition
        index.
    rank : int, default 3
        The number of components to compute.
    means : np.ndarray | None, default None
        Per-gene means to mean-center ``X`` by, or ``None`` to skip
        centering. Only accepted for a plain NumPy/SciPy ``X``; a matrix
        that handles its own centering must not be given one.
    random_state : int | np.random.Generator | None, default None
        Seed or generator controlling the random projection used by the
        randomized SVD.
    n_oversamples : int, default 10
        Extra dimensions added to ``rank`` when forming the random
        projection, to improve the accuracy of the randomized SVD.
    n_iter : int, default 20
        Maximum number of LOBPCG refinement iterations applied to the
        randomized SVD's subspace.
    norm_tensor : float | None, default None
        Precomputed squared Frobenius norm of the mean-centered ``X``. If
        ``None``, it is computed via ``X.norm_sq()``.
    row_weights : np.ndarray | None, default None
        Per-row weights; if given, ``C`` comes from the row-weighted data.

    Returns
    -------
    tuple[list[np.ndarray], float]
        The initial ``[A, B, C]`` factor matrices (with ``A`` all-ones,
        ``B`` the identity, and ``C`` the top right-singular vectors of the
        mean-centered ``X``), and the squared Frobenius norm ``norm_tensor``.
    """
    X = as_matrix(X, means)
    n_cond = int(np.amax(condition_unique_idxs)) + 1
    if norm_tensor is None:
        norm_tensor = float(X.norm_sq())

    C = randomized_svd_right(
        X,
        n_components=rank,
        n_oversamples=n_oversamples,
        n_power_iter=n_iter,
        random_state=random_state,
        row_weights=row_weights,
    )

    factors = [
        np.ones((n_cond, rank), dtype=np.float64),
        np.eye(rank, dtype=np.float64),
        C,
    ]
    return factors, norm_tensor

parafac2_nd(X_in, rank, n_iter_max=100, tol=1e-06, random_state=None, callback=None, backend=None, normalize_slices=False, n_inner=1, compress=None, n_power_iter=20, fix_B_identity=False)

The same interface as regular PARAFAC2 with optional CANDELINC compression.

If compress is specified (or if X_in is already a :class:~parafac2.compress.CompressedData), PARAFAC2 is fit in the compressed subspace (Bro's "compress-then-fit"), eliminating per-sweep raw data passes.

If normalize_slices is True, each condition is weighted by the inverse of its (mean-centered) Frobenius norm, so every condition counts equally in the fit regardless of its cell count or variance. The fit is that of the rescaled slices X_k / ||X_k|| (X itself is never copied or modified), so tol and callback follow their error. The returned A is in data units and R2X is the unweighted fraction of variance explained, comparable to an unweighted fit.

Parameters:

Name Type Description Default
X_in AnnData | CompressedData

Input dataset with the (optionally sparse) data matrix in X_in.X, condition labels in X_in.obs["condition_unique_idxs"], and optionally per-gene means in X_in.var["means"] (defaults to zero, i.e. no centering, if absent). Alternatively, a pre-compressed :class:~parafac2.compress.CompressedData object.

required
rank int

The number of components to fit.

required
n_iter_max int

Maximum number of ALS iterations.

100
tol float

Convergence tolerance: iteration stops once the (non-negative) decrease in relative error between successive iterations drops below this value.

1e-6
random_state int | None

Seed controlling the randomized SVD initialization.

None
callback Callable[[int, float, list[ndarray]], None] | None

Optional callback invoked after each iteration with the iteration index, the relative error, and the current factor matrices.

None
backend str | None

Compute backend to run matrix products on: one of 'mlx', 'cupy', or 'cpu'. If None, the first available accelerator is auto-detected (see :func:~parafac2.backend.get_backend).

None
normalize_slices bool

Whether to weight each condition by the inverse of its Frobenius norm, as described above.

False
n_inner int

Number of (projection, A, B) sub-iterations per sweep. These read the data only through the cached W, costing O(n_cells * rank^2) against the O(nnz * rank) of a raw-data product, so they are close to free on sparse inputs. Raising n_inner trades that cheap compute for fewer sweeps, and so for fewer raw-data passes: on structured test data, n_inner=2 cut the sweeps needed to reach a fixed error by ~20%, with little further gain beyond 3. Whether that is a net win depends on how strongly the raw-data products dominate, so it is worth benchmarking per dataset. The default of 1 reproduces the classic one-update-per-mode ALS sweep.

1
compress int | tuple[int, int | None] | str | bool | None

Compression mode. If None or False (default), exact ALS is used. If "auto" or True, sets compression dimensions automatically based on rank. If an integer, sets both gene and cell compression dimensions to that value. If a tuple (L_g, L_c), sets dimensions separately (pass L_c=None for gene-only compression). Ignored if X_in is already a :class:~parafac2.compress.CompressedData.

None
n_power_iter int

Maximum number of refinement iterations for the randomized SVD in the compression step (see :func:~parafac2.compress.compress_dataset). Ignored if compress is disabled or if X_in is already a :class:~parafac2.compress.CompressedData.

20
fix_B_identity bool

Whether to hold the B factor matrix fixed at the identity rather than fitting it. B is initialized to the identity either way, so this simply drops the mode-1 update from each ALS sweep; every other mode still sees B as usual. This constrains each condition's loading matrix to P_k diag(a_k), i.e. it ties component r to the r-th column of every projection, making the components directly comparable across conditions at the cost of some fit. The returned B is exactly the identity.

False

Returns:

Type Description
tuple[tuple[ndarray, list[ndarray], list[ndarray]], float]

A ((weights, factors, projections), R2X) tuple: the standardized weights and [A, B, C] factor matrices, the per-condition projection matrices P_k, and the final fraction of variance explained.

Source code in parafac2/parafac2.py
def parafac2_nd(
    X_in: anndata.AnnData | CompressedData,
    rank: int,
    n_iter_max: int = 100,
    tol: float = 1e-6,
    random_state: int | None = None,
    callback: Callable[[int, float, list[np.ndarray]], None] | None = None,
    backend: str | None = None,
    normalize_slices: bool = False,
    n_inner: int = 1,
    compress: int | tuple[int, int | None] | str | bool | None = None,
    n_power_iter: int = 20,
    fix_B_identity: bool = False,
) -> tuple[tuple[np.ndarray, list[np.ndarray], list[np.ndarray]], float]:
    r"""The same interface as regular PARAFAC2 with optional CANDELINC compression.

    If ``compress`` is specified (or if ``X_in`` is already a
    :class:`~parafac2.compress.CompressedData`), PARAFAC2 is fit in the
    compressed subspace (Bro's "compress-then-fit"), eliminating per-sweep raw
    data passes.

    If ``normalize_slices`` is True, each condition is weighted by the
    inverse of its (mean-centered) Frobenius norm, so every condition counts
    equally in the fit regardless of its cell count or variance. The fit is
    that of the rescaled slices ``X_k / ||X_k||`` (``X`` itself is never
    copied or modified), so ``tol`` and ``callback`` follow their error. The
    returned ``A`` is in data units and ``R2X`` is the unweighted fraction of
    variance explained, comparable to an unweighted fit.

    Parameters
    ----------
    X_in : anndata.AnnData | CompressedData
        Input dataset with the (optionally sparse) data matrix in ``X_in.X``,
        condition labels in ``X_in.obs["condition_unique_idxs"]``, and
        optionally per-gene means in ``X_in.var["means"]`` (defaults to zero,
        i.e. no centering, if absent). Alternatively, a pre-compressed
        :class:`~parafac2.compress.CompressedData` object.
    rank : int
        The number of components to fit.
    n_iter_max : int, default 100
        Maximum number of ALS iterations.
    tol : float, default 1e-6
        Convergence tolerance: iteration stops once the (non-negative)
        decrease in relative error between successive iterations drops
        below this value.
    random_state : int | None, default None
        Seed controlling the randomized SVD initialization.
    callback : Callable[[int, float, list[np.ndarray]], None] | None, default None
        Optional callback invoked after each iteration with the iteration
        index, the relative error, and the current factor matrices.
    backend : str | None, default None
        Compute backend to run matrix products on: one of ``'mlx'``,
        ``'cupy'``, or ``'cpu'``. If ``None``, the first available
        accelerator is auto-detected (see
        :func:`~parafac2.backend.get_backend`).
    normalize_slices : bool, default False
        Whether to weight each condition by the inverse of its Frobenius
        norm, as described above.
    n_inner : int, default 1
        Number of ``(projection, A, B)`` sub-iterations per sweep. These read
        the data only through the cached ``W``, costing ``O(n_cells *
        rank^2)`` against the ``O(nnz * rank)`` of a raw-data product, so
        they are close to free on sparse inputs. Raising ``n_inner`` trades
        that cheap compute for fewer sweeps, and so for fewer raw-data
        passes: on structured test data, ``n_inner=2`` cut the sweeps needed
        to reach a fixed error by ~20%, with little further gain beyond 3.
        Whether that is a net win depends on how strongly the raw-data
        products dominate, so it is worth benchmarking per dataset. The
        default of 1 reproduces the classic one-update-per-mode ALS sweep.
    compress : int | tuple[int, int | None] | str | bool | None, default None
        Compression mode. If ``None`` or ``False`` (default), exact ALS is
        used. If ``"auto"`` or ``True``, sets compression dimensions
        automatically based on ``rank``. If an integer, sets both gene and cell
        compression dimensions to that value. If a tuple ``(L_g, L_c)``, sets
        dimensions separately (pass ``L_c=None`` for gene-only compression).
        Ignored if ``X_in`` is already a
        :class:`~parafac2.compress.CompressedData`.
    n_power_iter : int, default 20
        Maximum number of refinement iterations for the randomized SVD in the
        compression step (see :func:`~parafac2.compress.compress_dataset`).
        Ignored if ``compress`` is disabled or if ``X_in`` is already a
        :class:`~parafac2.compress.CompressedData`.
    fix_B_identity : bool, default False
        Whether to hold the ``B`` factor matrix fixed at the identity rather
        than fitting it. ``B`` is initialized to the identity either way, so
        this simply drops the mode-1 update from each ALS sweep; every other
        mode still sees ``B`` as usual. This constrains each condition's
        loading matrix to ``P_k diag(a_k)``, i.e. it ties component ``r`` to
        the ``r``-th column of every projection, making the components
        directly comparable across conditions at the cost of some fit. The
        returned ``B`` is exactly the identity.

    Returns
    -------
    tuple[tuple[np.ndarray, list[np.ndarray], list[np.ndarray]], float]
        A ``((weights, factors, projections), R2X)`` tuple: the standardized
        weights and ``[A, B, C]`` factor matrices, the per-condition
        projection matrices ``P_k``, and the final fraction of variance
        explained.
    """
    # Verbose if this is not an automated build
    verbose = "CI" not in os.environ

    if isinstance(X_in, CompressedData):
        return _fit_parafac2_compressed(
            X_in,
            rank=rank,
            n_iter_max=n_iter_max,
            tol=tol,
            random_state=random_state,
            callback=callback,
            verbose=verbose,
            fix_B_identity=fix_B_identity,
        )

    if compress is not None and compress is not False:
        compressed = compress_dataset(
            X_in,
            L=compress,
            rank=rank,
            n_power_iter=n_power_iter,
            random_state=random_state,
            normalize_slices=normalize_slices,
            backend=backend,
        )
        return _fit_parafac2_compressed(
            compressed,
            rank=rank,
            n_iter_max=n_iter_max,
            tol=tol,
            random_state=random_state,
            callback=callback,
            verbose=verbose,
            fix_B_identity=fix_B_identity,
        )

    (
        X_mat,
        condition_unique_idxs,
        _means,
        norm_tensor,
        slice_weights,
        norm_weighted,
    ) = extract_dataset_info(X_in, normalize_slices=normalize_slices)

    n_cond = int(np.amax(condition_unique_idxs)) + 1
    min_cond_size = int(np.min(np.bincount(condition_unique_idxs, minlength=n_cond)))
    if min_cond_size < rank:
        raise ValueError(
            f"Rank ({rank}) cannot exceed the smallest condition's cell count "
            f"({min_cond_size}); every condition's projection matrix needs at "
            f"least `rank` cells to be orthonormal."
        )

    X_raw = to_gpu(X_mat, backend=backend)

    factors, _ = parafac2_init(
        X_raw,
        condition_unique_idxs,
        rank=rank,
        random_state=random_state,
        norm_tensor=norm_tensor,
        row_weights=None
        if slice_weights is None
        else slice_weights[condition_unique_idxs],
    )

    cond_slices = condition_slices(condition_unique_idxs, n_cond)

    # The error tracked is that of the weighted slices w_k X_k, whose
    # compressed slices are w_k S_k.
    w = np.ones(n_cond) if slice_weights is None else slice_weights
    norm_fit = norm_tensor if norm_weighted is None else norm_weighted

    # W depends only on C, so it stays valid across the A and B updates and is
    # recomputed only once C changes. Each sweep therefore costs exactly two
    # raw-data products: this one and the X^T @ H inside the mode-2 update.
    W = calc_W(X_raw, factors[2])
    projections, S = project_data(W, factors, cond_slices)
    errs = [calc_err(S * w[:, None, None], factors, norm_fit) / norm_fit]

    tq = tqdm(range(n_iter_max), disable=(not verbose), delay=0.5)
    for iteration in tq:
        # The (P, A, B) block reads the data only through the cached W, so
        # extra inner passes buy convergence at no raw-data cost.
        for _ in range(n_inner):
            factors = parafac_update(factors, 0, S, slice_weights=slice_weights)
            projections, S = project_data(W, factors, cond_slices)
            # B starts at the identity, so skipping its update leaves it there.
            if not fix_B_identity:
                factors = parafac_update(factors, 1, S, slice_weights=slice_weights)
                projections, S = project_data(W, factors, cond_slices)

        factors = parafac_update(
            factors,
            2,
            S,
            projections,
            X=X_raw,
            cond_slices=cond_slices,
            slice_weights=slice_weights,
        )

        # C changed, so refresh W; this also yields the projections and error
        # for the factors as they stand at the end of this sweep.
        W = calc_W(X_raw, factors[2])
        projections, S = project_data(W, factors, cond_slices)
        errs.append(calc_err(S * w[:, None, None], factors, norm_fit) / norm_fit)

        delta = errs[-2] - errs[-1]
        tq.set_postfix(error=errs[-1], R2X=1.0 - errs[-1], Δ=delta, refresh=False)
        if callback is not None:
            callback(iteration, errs[-1], factors)

        if 0 <= delta < tol:
            break

    R2X = 1 - errs[-1]
    if slice_weights is not None:
        # Map A back to data units and score it against the unweighted data.
        factors[0] = factors[0] / w[:, np.newaxis]
        R2X = 1 - calc_err(S, factors, norm_tensor) / norm_tensor

    # Standardize the results and return
    return standardize_pf2(factors, projections), R2X

store_pf2(X, parafac2_output)

Store the Pf2 results into the anndata object.

Parameters:

Name Type Description Default
X AnnData | CompressedData

The dataset the factorization was fit on. Must have X.obs["condition_unique_idxs"] set (as produced by :func:~parafac2.normalize.prepare_dataset or equivalent). If a :class:~parafac2.compress.CompressedData is provided, factors are written to its underlying .adata object.

required
parafac2_output tuple[ndarray, list[ndarray], list[ndarray]]

The (weights, factors, projections) output of :func:parafac2_nd, where factors is the [A, B, C] factor matrices and projections is the per-condition projection matrices P_k.

required

Returns:

Type Description
AnnData

The target AnnData object, mutated in place, with the weights in X.uns["Pf2_weights"], factors in X.uns["Pf2_A"]/X.uns["Pf2_B"]/X.varm["Pf2_C"], and per-cell projections in X.obsm["projections"] and X.obsm["weighted_projections"] (projections composed with B).

Source code in parafac2/parafac2.py
def store_pf2(
    X: anndata.AnnData | CompressedData,
    parafac2_output: tuple[np.ndarray, list[np.ndarray], list[np.ndarray]],
) -> anndata.AnnData:
    """Store the Pf2 results into the anndata object.

    Parameters
    ----------
    X : anndata.AnnData | CompressedData
        The dataset the factorization was fit on. Must have
        ``X.obs["condition_unique_idxs"]`` set (as produced by
        :func:`~parafac2.normalize.prepare_dataset` or equivalent). If a
        :class:`~parafac2.compress.CompressedData` is provided, factors are
        written to its underlying ``.adata`` object.
    parafac2_output : tuple[np.ndarray, list[np.ndarray], list[np.ndarray]]
        The ``(weights, factors, projections)`` output of :func:`parafac2_nd`,
        where ``factors`` is the ``[A, B, C]`` factor matrices and
        ``projections`` is the per-condition projection matrices ``P_k``.

    Returns
    -------
    anndata.AnnData
        The target AnnData object, mutated in place, with the weights in
        ``X.uns["Pf2_weights"]``, factors in
        ``X.uns["Pf2_A"]``/``X.uns["Pf2_B"]``/``X.varm["Pf2_C"]``, and
        per-cell projections in ``X.obsm["projections"]`` and
        ``X.obsm["weighted_projections"]`` (projections composed with ``B``).
    """
    if isinstance(X, CompressedData):
        if X.adata is None:
            raise ValueError("CompressedData has no associated AnnData object.")
        target_adata = X.adata
        condition_unique_idxs = X.condition_unique_idxs
    else:
        target_adata = X
        condition_unique_idxs = target_adata.obs["condition_unique_idxs"]

    target_adata.uns["Pf2_weights"] = parafac2_output[0]
    target_adata.uns["Pf2_A"], target_adata.uns["Pf2_B"], target_adata.varm["Pf2_C"] = (
        parafac2_output[1]
    )

    target_adata.obsm["projections"] = np.zeros(
        (target_adata.shape[0], len(target_adata.uns["Pf2_weights"])), dtype=np.float32
    )
    for i, p in enumerate(parafac2_output[2]):
        target_adata.obsm["projections"][condition_unique_idxs == i, :] = p

    target_adata.obsm["weighted_projections"] = (
        target_adata.obsm["projections"] @ target_adata.uns["Pf2_B"]
    ).astype(np.float32, copy=False)

    return target_adata

parafac2.normalize

parafac2.normalize

Dataset preprocessing and normalization utilities for PARAFAC2 analysis.

This module provides functions to filter, normalize, and annotate single-cell gene expression datasets stored in AnnData objects prior to PARAFAC2 matrix factorization.

prepare_dataset(X, condition_name, geneThreshold)

Preprocess and normalize an AnnData dataset for PARAFAC2 factorization.

Performs quality control filtering of low-count cells and low-expression genes, normalizes total cell counts and gene sums, applies a log10 transformation, and computes metadata required by PARAFAC2 (condition indices and gene means).

Parameters:

Name Type Description Default
X AnnData

Input single-cell dataset with raw count matrix stored in X.X (must be a sparse matrix with non-negative values).

required
condition_name str

Column name in X.obs identifying the sample or experimental condition grouping for each cell.

required
geneThreshold float

Minimum threshold fraction for gene inclusion. Genes with total counts less than geneThreshold * total_cells are filtered out.

required

Returns:

Type Description
AnnData

A filtered and normalized copy of the AnnData object. Contains the log-transformed normalized counts in X.X, integer condition codes in X.obs["condition_unique_idxs"], and per-gene mean expression values in X.var["means"].

Source code in parafac2/normalize.py
def prepare_dataset(
    X: anndata.AnnData, condition_name: str, geneThreshold: float
) -> anndata.AnnData:
    """Preprocess and normalize an AnnData dataset for PARAFAC2 factorization.

    Performs quality control filtering of low-count cells and low-expression
    genes, normalizes total cell counts and gene sums, applies a log10
    transformation, and computes metadata required by PARAFAC2 (condition
    indices and gene means).

    Parameters
    ----------
    X : anndata.AnnData
        Input single-cell dataset with raw count matrix stored in ``X.X``
        (must be a sparse matrix with non-negative values).
    condition_name : str
        Column name in ``X.obs`` identifying the sample or experimental
        condition grouping for each cell.
    geneThreshold : float
        Minimum threshold fraction for gene inclusion. Genes with total counts
        less than ``geneThreshold * total_cells`` are filtered out.

    Returns
    -------
    anndata.AnnData
        A filtered and normalized copy of the AnnData object. Contains the
        log-transformed normalized counts in ``X.X``, integer condition
        codes in ``X.obs["condition_unique_idxs"]``, and per-gene mean
        expression values in ``X.var["means"]``.
    """
    assert issparse(X.X)
    X_X_raw = cast("csr_array", X.X)
    assert np.amin(X_X_raw.data) >= 0.0

    # Filter out genes with too few reads, and cells with fewer than 10 counts
    cell_mask = np.ravel(X_X_raw.sum(axis=1)) > 10
    gene_mask = np.ravel(X_X_raw.sum(axis=0)) > (geneThreshold * X_X_raw.shape[0])

    if not cell_mask.any():
        raise ValueError(
            "prepare_dataset: no cells passed the count filter (every cell's "
            "total count is <= 10); check the input data."
        )
    if not gene_mask.any():
        raise ValueError(
            "prepare_dataset: no genes passed the count filter (every gene's "
            f"total count is <= {geneThreshold} * n_cells); check the input "
            "data or lower geneThreshold."
        )

    # Subset and materialize actual AnnData object before modifying X.X
    if cell_mask.all() and gene_mask.all():
        X = X.copy()
    else:
        X = X[cell_mask, gene_mask].copy()

    # Convert subset to csr_array and float32 data
    X.X = csr_array(X.X)
    X_X = cast("csr_array", X.X)

    if X_X.dtype != np.float32:
        X_X.data = X_X.data.astype(np.float32)

    ## Normalize total counts per cell
    # Keep the counts on a reasonable scale to avoid accuracy issues
    counts_per_cell = np.ravel(X_X.sum(axis=1)).astype(np.float32, copy=False)
    counts_per_cell /= np.median(counts_per_cell)
    # In-place CSR row scaling
    X_X.data /= np.repeat(counts_per_cell, np.diff(X_X.indptr))

    # Scale genes by sum, in-place CSR column scaling
    gene_sums = np.ravel(X_X.sum(axis=0)).astype(np.float32, copy=False)
    X_X.data /= gene_sums[X_X.indices]

    # Transform values in-place to avoid nnz-sized temporaries
    X_X.data *= np.float32(1000.0)
    X_X.data += np.float32(1.0)
    np.log10(X_X.data, out=X_X.data)

    # Get the indices for subsetting the data
    X.obs["condition_unique_idxs"] = pd.Categorical(X.obs[condition_name]).codes

    # Pre-calculate gene means
    X.var["means"] = np.ravel(X_X.mean(axis=0))

    return X

parafac2.compress

parafac2.compress

CANDELINC compression for PARAFAC2.

Compresses the gene and cell modes of single-cell datasets prior to PARAFAC2 factorization, collapsing the problem to small dense per-condition cores.

CompressedData dataclass

Compressed representation of a multi-condition single-cell dataset.

Stores the small dense per-condition cores and the orthonormal bases for the gene mode (Q) and cell mode (Q_k), enabling fast rank sweeps without touching the raw data again.

Source code in parafac2/compress.py
@dataclass
class CompressedData:
    """Compressed representation of a multi-condition single-cell dataset.

    Stores the small dense per-condition cores and the orthonormal bases for
    the gene mode (``Q``) and cell mode (``Q_k``), enabling fast rank sweeps
    without touching the raw data again.
    """

    cores: list[np.ndarray]
    """List of length ``n_cond`` with dense cores ``Y_k`` of shape ``(L_c_k, L_g)``."""

    Q: np.ndarray
    """Gene projection basis of shape ``(n_genes, L_g)`` with orthonormal columns."""

    Q_k: list[np.ndarray | None] | None
    """Per-condition cell projection bases ``(n_cells_k, L_c_k)`` or ``None``."""

    condition_unique_idxs: np.ndarray
    """Integer condition indices for each cell."""

    norm_tensor: float
    """Total squared Frobenius norm of the original mean-centered dataset."""

    lost_var: float
    """Variance discarded by the compression projectors."""

    total_cells: int
    """Total number of cells across all conditions."""

    n_genes: int
    """Number of genes in the uncompressed dataset."""

    n_cond: int
    """Number of conditions."""

    slice_weights: np.ndarray | None = None
    """Optional per-condition slice weights for normalized ALS."""

    norm_weighted: float | None = None
    """Squared norm of the weighted slices ``w_k X_k``, set with ``slice_weights``."""

    means: np.ndarray | None = None
    """Per-gene means subtracted during compression."""

    adata: anndata.AnnData | None = None
    """Reference to original AnnData object if available."""

    @property
    def L_g(self) -> int:
        """Gene compression dimension."""
        return self.Q.shape[1]

    @property
    def max_cell_dim(self) -> int:
        """Maximum cell dimension across cores."""
        return max(c.shape[0] for c in self.cores)

L_g property

Gene compression dimension.

Q instance-attribute

Gene projection basis of shape (n_genes, L_g) with orthonormal columns.

Q_k instance-attribute

Per-condition cell projection bases (n_cells_k, L_c_k) or None.

adata = None class-attribute instance-attribute

Reference to original AnnData object if available.

condition_unique_idxs instance-attribute

Integer condition indices for each cell.

cores instance-attribute

List of length n_cond with dense cores Y_k of shape (L_c_k, L_g).

lost_var instance-attribute

Variance discarded by the compression projectors.

max_cell_dim property

Maximum cell dimension across cores.

means = None class-attribute instance-attribute

Per-gene means subtracted during compression.

n_cond instance-attribute

Number of conditions.

n_genes instance-attribute

Number of genes in the uncompressed dataset.

norm_tensor instance-attribute

Total squared Frobenius norm of the original mean-centered dataset.

norm_weighted = None class-attribute instance-attribute

Squared norm of the weighted slices w_k X_k, set with slice_weights.

slice_weights = None class-attribute instance-attribute

Optional per-condition slice weights for normalized ALS.

total_cells instance-attribute

Total number of cells across all conditions.

compress_cells(X_c, condition_unique_idxs, L_c=None)

Compute per-condition cell-mode compression projectors Q_k and cores Y_k.

Parameters:

Name Type Description Default
X_c ndarray

Gene-compressed data matrix of shape (total_cells, L_g).

required
condition_unique_idxs ndarray

Integer condition index for each cell.

required
L_c int | None

Target cell subspace dimension per condition. If None, cell compression is skipped (cores are X_c slices).

None

Returns:

Type Description
tuple[list[ndarray], list[ndarray | None] | None, float]

(cores, Q_k_list, norm_cores_sq) where each core Y_k has shape (L_c_k, L_g) and norm_cores_sq is the total squared Frobenius norm of all cores.

Source code in parafac2/compress.py
def compress_cells(
    X_c: np.ndarray,
    condition_unique_idxs: np.ndarray,
    L_c: int | None = None,
) -> tuple[list[np.ndarray], list[np.ndarray | None] | None, float]:
    """Compute per-condition cell-mode compression projectors Q_k and cores Y_k.

    Parameters
    ----------
    X_c : np.ndarray
        Gene-compressed data matrix of shape ``(total_cells, L_g)``.
    condition_unique_idxs : np.ndarray
        Integer condition index for each cell.
    L_c : int | None, default None
        Target cell subspace dimension per condition. If ``None``, cell
        compression is skipped (cores are ``X_c`` slices).

    Returns
    -------
    tuple[list[np.ndarray], list[np.ndarray | None] | None, float]
        ``(cores, Q_k_list, norm_cores_sq)`` where each core ``Y_k`` has
        shape ``(L_c_k, L_g)`` and ``norm_cores_sq`` is the total squared
        Frobenius norm of all cores.
    """
    n_cond = int(np.amax(condition_unique_idxs)) + 1
    cores: list[np.ndarray] = []
    Q_k_list: list[np.ndarray | None] | None = [] if L_c is not None else None
    norm_cores_sq = 0.0

    for i in range(n_cond):
        cond_i = condition_unique_idxs == i
        X_c_i = X_c[cond_i]
        n_k = X_c_i.shape[0]

        if L_c is None or n_k <= L_c:
            cores.append(X_c_i)
            if Q_k_list is not None:
                Q_k_list.append(None)
            norm_cores_sq += float(np.sum(X_c_i**2))
        else:
            # Thin SVD of (n_k, L_g) where L_g <= 100
            U_i, S_i, Vh_i = np.linalg.svd(X_c_i, full_matrices=False)
            L_k = min(n_k, L_c)
            Q_i = U_i[:, :L_k].astype(np.float64)
            Y_i = (S_i[:L_k, np.newaxis] * Vh_i[:L_k, :]).astype(np.float64)
            cores.append(Y_i)
            if Q_k_list is not None:
                Q_k_list.append(Q_i)
            norm_cores_sq += float(np.sum(S_i[:L_k] ** 2))

    return cores, Q_k_list, norm_cores_sq

compress_dataset(X_in, L='auto', rank=None, n_power_iter=20, random_state=None, normalize_slices=False, backend=None)

Compress an AnnData dataset in gene and cell modes.

Parameters:

Name Type Description Default
X_in AnnData

Input dataset with data in X_in.X, condition indices in X_in.obs["condition_unique_idxs"], and optional means in X_in.var["means"].

required
L int | tuple[int, int | None] | str | bool

Compression dimension(s). If "auto" or True, uses max(2 * rank, rank + 20) for both modes (with rank defaulting to 30 when it is None). If an int, sets both L_g = L and L_c = L. If a tuple (L_g, L_c), sets gene and cell dimensions individually (pass L_c=None for gene-only compression).

"auto"
rank int | None

Expected maximum rank to fit on the compressed data. Used when L="auto".

None
n_power_iter int

Maximum number of refinement iterations for the randomized SVD (see :func:~parafac2.utils.randomized_svd_right).

20
random_state int | Generator | None

Random seed or generator.

None
normalize_slices bool

Whether to precalculate slice weights for normalized ALS.

False
backend str | None

Compute backend for raw matrix products.

None

Returns:

Type Description
CompressedData

The compressed dataset ready for fast PARAFAC2 fitting.

Source code in parafac2/compress.py
def compress_dataset(
    X_in: anndata.AnnData,
    L: int | tuple[int, int | None] | str | bool = "auto",
    rank: int | None = None,
    n_power_iter: int = 20,
    random_state: int | np.random.Generator | None = None,
    normalize_slices: bool = False,
    backend: str | None = None,
) -> CompressedData:
    """Compress an AnnData dataset in gene and cell modes.

    Parameters
    ----------
    X_in : anndata.AnnData
        Input dataset with data in ``X_in.X``, condition indices in
        ``X_in.obs["condition_unique_idxs"]``, and optional means in
        ``X_in.var["means"]``.
    L : int | tuple[int, int | None] | str | bool, default "auto"
        Compression dimension(s). If ``"auto"`` or ``True``, uses
        ``max(2 * rank, rank + 20)`` for both modes (with ``rank`` defaulting
        to 30 when it is ``None``). If an int, sets
        both ``L_g = L`` and ``L_c = L``. If a tuple ``(L_g, L_c)``, sets
        gene and cell dimensions individually (pass ``L_c=None`` for
        gene-only compression).
    rank : int | None, default None
        Expected maximum rank to fit on the compressed data. Used when
        ``L="auto"``.
    n_power_iter : int, default 20
        Maximum number of refinement iterations for the randomized SVD
        (see :func:`~parafac2.utils.randomized_svd_right`).
    random_state : int | np.random.Generator | None, default None
        Random seed or generator.
    normalize_slices : bool, default False
        Whether to precalculate slice weights for normalized ALS.
    backend : str | None, default None
        Compute backend for raw matrix products.

    Returns
    -------
    CompressedData
        The compressed dataset ready for fast PARAFAC2 fitting.
    """
    (
        X_mat,
        condition_unique_idxs,
        means,
        norm_tensor,
        slice_weights,
        norm_weighted,
    ) = extract_dataset_info(X_in, normalize_slices=normalize_slices)
    total_cells, n_genes = X_mat.shape
    n_cond = int(np.amax(condition_unique_idxs)) + 1

    # Determine L_g and L_c
    target_rank = rank if rank is not None else 30
    # `L is True` has to be checked before the int branch: `bool` is a
    # subclass of `int`, so `compress=True` would otherwise be read as L=1.
    if L is True or (isinstance(L, str) and L == "auto"):
        # 2x the rank, with a +20 floor for small ranks. The 4x this used to
        # take was headroom for a less accurate gene basis; measured against
        # uncompressed converged fits at rank 30 on two single-cell datasets,
        # the retained R2X from 2x to 4x differs by 0.01-0.06 percentage
        # points (thomson 99.86% -> 99.87%, BAL 99.81% -> 99.87%), while the
        # compression itself takes about twice as long at 4x.
        auto_L = max(2 * target_rank, target_rank + 20)
        L_g_val = min(n_genes, auto_L)
        L_c_val: int | None = auto_L
    elif isinstance(L, tuple):
        L_g_val, L_c_val = L
        L_g_val = min(n_genes, L_g_val)
    elif isinstance(L, (int, np.integer)):
        L_g_val = min(n_genes, int(L))
        L_c_val = int(L)
    else:
        raise ValueError(f"Invalid compression parameter L: {L}")

    X_raw = to_gpu(X_mat, backend=backend)
    X_c, Q, _norm_Xc_sq = compress_genes(
        X_raw,
        L_g=L_g_val,
        n_power_iter=n_power_iter,
        random_state=random_state,
        row_weights=None
        if slice_weights is None
        else slice_weights[condition_unique_idxs],
    )

    cores, Q_k, norm_cores_sq = compress_cells(
        X_c,
        condition_unique_idxs,
        L_c=L_c_val,
    )

    lost_var = float(np.maximum(0.0, norm_tensor - norm_cores_sq))

    return CompressedData(
        cores=cores,
        Q=Q,
        Q_k=Q_k,
        condition_unique_idxs=condition_unique_idxs,
        norm_tensor=norm_tensor,
        lost_var=lost_var,
        total_cells=total_cells,
        n_genes=n_genes,
        n_cond=n_cond,
        slice_weights=slice_weights,
        norm_weighted=norm_weighted,
        means=means,
        adata=X_in,
    )

compress_genes(X, L_g, n_power_iter=20, random_state=None, row_weights=None)

Compute gene-mode compression projector Q and compressed matrix Xc.

Parameters:

Name Type Description Default
X Any

Stacked data matrix of shape (total_cells, n_genes), already accounting for any mean-centering (see :mod:parafac2.matrix).

required
L_g int

Target gene subspace dimension.

required
n_power_iter int

Maximum number of refinement iterations for the randomized SVD (see :func:~parafac2.utils.randomized_svd_right).

20
random_state int | Generator | None

Random seed or generator.

None
row_weights ndarray | None

Per-row weights; if given, Q spans the row-weighted data.

None

Returns:

Type Description
tuple[ndarray, ndarray, float]

(X_c, Q, norm_Xc_sq) where X_c = (X - 1 mu^T) @ Q of shape (total_cells, L_g), Q is (n_genes, L_g) orthonormal, and norm_Xc_sq is the squared Frobenius norm of X_c.

Source code in parafac2/compress.py
def compress_genes(
    X: Any,
    L_g: int,
    n_power_iter: int = 20,
    random_state: int | np.random.Generator | None = None,
    row_weights: np.ndarray | None = None,
) -> tuple[np.ndarray, np.ndarray, float]:
    """Compute gene-mode compression projector Q and compressed matrix Xc.

    Parameters
    ----------
    X : Any
        Stacked data matrix of shape ``(total_cells, n_genes)``, already
        accounting for any mean-centering (see :mod:`parafac2.matrix`).
    L_g : int
        Target gene subspace dimension.
    n_power_iter : int, default 20
        Maximum number of refinement iterations for the randomized SVD
        (see :func:`~parafac2.utils.randomized_svd_right`).
    random_state : int | np.random.Generator | None, default None
        Random seed or generator.
    row_weights : np.ndarray | None, default None
        Per-row weights; if given, ``Q`` spans the row-weighted data.

    Returns
    -------
    tuple[np.ndarray, np.ndarray, float]
        ``(X_c, Q, norm_Xc_sq)`` where ``X_c = (X - 1 mu^T) @ Q`` of shape
        ``(total_cells, L_g)``, ``Q`` is ``(n_genes, L_g)`` orthonormal, and
        ``norm_Xc_sq`` is the squared Frobenius norm of ``X_c``.
    """
    n_cells, n_genes = X.shape
    # Clip to the data's own maximum rank: a target that exceeds it is not
    # achievable (randomized_svd_right raises otherwise), but here it should
    # simply degrade to the largest compression the data actually supports.
    L_g = min(n_genes, n_cells, L_g)

    Q = randomized_svd_right(
        X,
        n_components=L_g,
        n_oversamples=0,
        n_power_iter=n_power_iter,
        random_state=random_state,
        row_weights=row_weights,
    )
    X_c = calc_W(X, Q)
    norm_Xc_sq = float(np.sum(X_c**2))

    return X_c, Q, norm_Xc_sq

init_compressed_factors(cores, rank, random_state=None, slice_weights=None)

Initialize factor matrices [A, B, C_L] directly on compressed cores.

Source code in parafac2/compress.py
def init_compressed_factors(
    cores: list[np.ndarray],
    rank: int,
    random_state: int | np.random.Generator | None = None,
    slice_weights: np.ndarray | None = None,
) -> list[np.ndarray]:
    """Initialize factor matrices [A, B, C_L] directly on compressed cores."""
    n_cond = len(cores)
    L_g = cores[0].shape[1]
    assert rank <= L_g, f"Rank {rank} exceeds compressed gene dimension {L_g}"

    # SVD of stacked (weighted) cores to initialize C_L
    if slice_weights is not None:
        cores = [w_k * Y_k for w_k, Y_k in zip(slice_weights, cores, strict=True)]
    Y_stacked = np.concatenate(cores, axis=0)
    _, _, vh = np.linalg.svd(Y_stacked, full_matrices=False)
    C_L = vh[:rank, :].T.astype(np.float64)

    return [
        np.ones((n_cond, rank), dtype=np.float64),
        np.eye(rank, dtype=np.float64),
        C_L,
    ]

project_data_compressed(cores, factors, norm_tensor, mode, return_projections=False, slice_weights=None)

project_data_compressed(
    cores: list[np.ndarray],
    factors: list[np.ndarray],
    norm_tensor: float,
    mode: int,
    return_projections: Literal[False] = False,
    slice_weights: np.ndarray | None = None,
) -> tuple[np.ndarray, float]
project_data_compressed(
    cores: list[np.ndarray],
    factors: list[np.ndarray],
    norm_tensor: float,
    mode: int,
    return_projections: Literal[True],
    slice_weights: np.ndarray | None = None,
) -> list[np.ndarray]

Project compressed per-condition cores and accumulate MTTKRP and error.

Parameters:

Name Type Description Default
cores list[ndarray]

List of per-condition core matrices Y_k of shape (L_c_k, L_g).

required
factors list[ndarray]

Current factor matrices [A, B, C_L] in the compressed space.

required
norm_tensor float

Squared Frobenius norm of the original mean-centered tensor, or of its weighted slices when slice_weights is given.

required
mode int

Mode to update (0, 1, or 2).

required
return_projections bool

Whether to return the list of projection matrices P_tilde_k.

False
slice_weights ndarray | None

Optional per-condition weights w_k; the MTTKRP and error are then those of the weighted cores w_k Y_k.

None

Returns:

Type Description
tuple[ndarray, float] | list[ndarray]

(mttkrp, norm_sq_err) or list of P_tilde_k.

Source code in parafac2/compress.py
def project_data_compressed(
    cores: list[np.ndarray],
    factors: list[np.ndarray],
    norm_tensor: float,
    mode: int,
    return_projections: bool = False,
    slice_weights: np.ndarray | None = None,
) -> tuple[np.ndarray, float] | list[np.ndarray]:
    """Project compressed per-condition cores and accumulate MTTKRP and error.

    Parameters
    ----------
    cores : list[np.ndarray]
        List of per-condition core matrices ``Y_k`` of shape ``(L_c_k, L_g)``.
    factors : list[np.ndarray]
        Current factor matrices ``[A, B, C_L]`` in the compressed space.
    norm_tensor : float
        Squared Frobenius norm of the original mean-centered tensor, or of
        its weighted slices when ``slice_weights`` is given.
    mode : int
        Mode to update (0, 1, or 2).
    return_projections : bool, default False
        Whether to return the list of projection matrices ``P_tilde_k``.
    slice_weights : np.ndarray | None, default None
        Optional per-condition weights ``w_k``; the MTTKRP and error are then
        those of the weighted cores ``w_k Y_k``.

    Returns
    -------
    tuple[np.ndarray, float] | list[np.ndarray]
        ``(mttkrp, norm_sq_err)`` or list of ``P_tilde_k``.
    """
    A, B, C_L = factors
    rank = B.shape[0]
    n_cond = len(cores)

    norm_sq_err = norm_tensor + float(((A.T @ A) * (B.T @ B) * (C_L.T @ C_L)).sum())

    if mode == 0:
        mttkrp = np.zeros((n_cond, rank), dtype=np.float64)
    elif mode == 1:
        mttkrp = np.zeros((rank, rank), dtype=np.float64)
    else:
        mttkrp = np.zeros_like(C_L, dtype=np.float64)

    proj_list = []
    for i in range(n_cond):
        Y_i = cores[i]
        W_i = Y_i @ C_L  # (L_c_i, rank)
        M = W_i @ (B * A[i]).T  # (L_c_i, rank)
        proj = polar_factor(M)
        proj_list.append(proj)

        if return_projections:
            continue

        w_i = 1.0 if slice_weights is None else slice_weights[i]
        psc = w_i * (proj.T @ W_i)  # (rank, rank), of the weighted core
        m_i = np.sum(psc * B, axis=0)
        norm_sq_err -= 2.0 * float(np.dot(A[i], m_i))

        if mode == 0:
            mttkrp[i] = m_i
        elif mode == 1:
            mttkrp += psc * A[i]
        else:
            H_tilde_i = proj @ (B * A[i]) * w_i
            mttkrp += Y_i.T @ H_tilde_i

    if return_projections:
        return proj_list

    return mttkrp, float(norm_sq_err)

parafac2.matrix

parafac2.matrix

The duck-typed matrix contract the PARAFAC2 fit talks to, and the wrappers that give NumPy arrays and SciPy CSR arrays that interface.

Everything downstream of :func:as_matrix -- :mod:parafac2.utils, :mod:parafac2.compress, :mod:parafac2.parafac2 -- reaches the raw data only through this contract. Nothing there branches on the data's type.

The contract

An object usable as X must provide:

shape The (n_rows, n_cols) tuple. dtype The NumPy dtype products should be taken in. Callers build their dense operands in this dtype so the product never has to upcast the (possibly enormous) data matrix. X @ rhs and lhs @ X Matrix products against a 1-D or 2-D NumPy array, returning a float64 NumPy array. Any mean-centering the matrix represents must already be applied -- X @ rhs means (X_raw - 1 mu^T) @ rhs. norm_sq() The squared Frobenius norm of the (centered) matrix, as a float. slice_norms(condition_idxs, n_cond) Per-condition Frobenius norms of the (centered) rows, as a length n_cond array. to_device(backend) Return an object satisfying this same contract with its data resident on backend ('cupy' or 'mlx'). Only needed to run on a GPU backend; parafac2 has no transfer logic of its own for a third-party storage format. __array_ufunc__ = None Required, so that lhs @ X for a plain NumPy lhs defers to X's own __rmatmul__ instead of NumPy trying to broadcast X into an ndarray (which fails outright for a type that cannot be converted to one, as most duck-typed backends cannot).

:func:as_linear_operator adapts any of these to a SciPy :class:~scipy.sparse.linalg.LinearOperator, which is how the data reaches SciPy's decompositions (the randomized SVD in :mod:parafac2.utils) without those ever learning what the data is or where it lives.

:class:Matrix implements everything but the two products and the two norms, so subclassing it is the easy way to satisfy the contract; vsparse-style types that implement it structurally work just as well and are passed through :func:as_matrix untouched.

CSRMatrix

Bases: Matrix

A SciPy CSR array with optional implicit mean-centering.

The norms expand ||X - 1 mu^T||^2 into sum-of-squares and cross terms over the stored nonzeros, so a centered norm never densifies X.

Parameters:

Name Type Description Default
mat csr_array

The sparse data matrix of shape (n_rows, n_cols). Any SciPy sparse format is accepted and converted to CSR.

required
means ndarray | None

Per-column means to subtract implicitly.

None
Source code in parafac2/matrix.py
class CSRMatrix(Matrix):
    """A SciPy CSR array with optional implicit mean-centering.

    The norms expand ``||X - 1 mu^T||^2`` into sum-of-squares and cross terms
    over the stored nonzeros, so a centered norm never densifies ``X``.

    Parameters
    ----------
    mat : csr_array
        The sparse data matrix of shape ``(n_rows, n_cols)``. Any SciPy
        sparse format is accepted and converted to CSR.
    means : np.ndarray | None, default None
        Per-column means to subtract implicitly.
    """

    def __init__(self, mat: Any, means: np.ndarray | None = None) -> None:
        self.mat = mat if isinstance(mat, csr_array) else csr_array(mat)
        super().__init__(self.mat.shape, self.mat.dtype, means)

    def _mkl_dot(self) -> Any:
        """MKL's kernel if it is installed and it supports this dtype.

        MKL needs single- or double-precision data; the operand's dtype and
        layout are already guaranteed by :meth:`Matrix._operand`.
        """
        if self.dtype not in (np.float32, np.float64):
            return None
        return mkl_dot()

    def _matmul(self, rhs: np.ndarray) -> np.ndarray:
        dot = self._mkl_dot()
        return self.mat @ rhs if dot is None else dot(self.mat, rhs)

    def _rmatmul(self, lhs: np.ndarray) -> np.ndarray:
        dot = self._mkl_dot()
        return lhs @ self.mat if dot is None else dot(lhs, self.mat)

    def norm_sq(self) -> float:
        data = self.mat.data
        if self.means is None:
            return float(np.sum(data**2))
        term1 = np.sum(data**2)
        term2 = -2.0 * np.sum(data * self.means[self.mat.indices])
        term3 = self.shape[0] * np.sum(self.means**2)
        return float(term1 + term2 + term3)

    def slice_norms(self, condition_idxs: np.ndarray, n_cond: int) -> np.ndarray:
        idxs = np.asarray(condition_idxs)
        group_of_nnz = np.repeat(idxs, np.diff(self.mat.indptr))
        data = self.mat.data.astype(np.float64)
        sums_sq = np.bincount(group_of_nnz, weights=data**2, minlength=n_cond)
        if self.means is None:
            return np.sqrt(sums_sq)

        counts = np.bincount(idxs, minlength=n_cond).astype(np.float64)
        cross = np.bincount(
            group_of_nnz,
            weights=data * self.means[self.mat.indices],
            minlength=n_cond,
        )
        mean_sq_total = np.sum(self.means**2)
        return np.sqrt(np.maximum(sums_sq - 2.0 * cross + counts * mean_sq_total, 0.0))

    def to_device(self, backend: str | None = None) -> Matrix:
        chosen = get_backend(backend)
        if chosen == "cupy":
            return DeviceMatrix(
                self, to_cupy_csr(self.mat), cupy_csr_matmul, cupy_csr_rmatmul
            )
        if chosen == "mlx":
            return DeviceMatrix(
                self, to_mlx_csr(self.mat), mlx_csr_matmul, mlx_csr_rmatmul
            )
        return self

DenseMatrix

Bases: Matrix

A dense NumPy array with optional implicit mean-centering.

Parameters:

Name Type Description Default
mat ndarray

The dense data matrix of shape (n_rows, n_cols).

required
means ndarray | None

Per-column means to subtract implicitly.

None
Source code in parafac2/matrix.py
class DenseMatrix(Matrix):
    """A dense NumPy array with optional implicit mean-centering.

    Parameters
    ----------
    mat : np.ndarray
        The dense data matrix of shape ``(n_rows, n_cols)``.
    means : np.ndarray | None, default None
        Per-column means to subtract implicitly.
    """

    def __init__(self, mat: np.ndarray, means: np.ndarray | None = None) -> None:
        self.mat = np.asarray(mat)
        super().__init__(self.mat.shape, self.mat.dtype, means)

    def _matmul(self, rhs: np.ndarray) -> np.ndarray:
        return self.mat @ rhs

    def _rmatmul(self, lhs: np.ndarray) -> np.ndarray:
        return lhs @ self.mat

    def norm_sq(self) -> float:
        if self.means is None:
            return float(np.sum(self.mat**2))
        return float(np.sum((self.mat - self.means) ** 2))

    def slice_norms(self, condition_idxs: np.ndarray, n_cond: int) -> np.ndarray:
        idxs = np.asarray(condition_idxs)
        centered = self.mat if self.means is None else self.mat - self.means
        row_sums_sq = np.sum(centered**2, axis=1)
        return np.sqrt(np.bincount(idxs, weights=row_sums_sq, minlength=n_cond))

    def to_device(self, backend: str | None = None) -> Matrix:
        chosen = get_backend(backend)
        if chosen == "cupy":
            return DeviceMatrix(
                self, to_cupy_dense(self.mat), cupy_dense_matmul, cupy_dense_rmatmul
            )
        if chosen == "mlx":
            return DeviceMatrix(
                self, to_mlx_dense(self.mat), mlx_dense_matmul, mlx_dense_rmatmul
            )
        return self

DeviceMatrix

Bases: Matrix

A host matrix whose data has been transferred to an accelerator.

Holds the device-resident payload plus the product routines that understand it, and delegates the norms back to the host matrix (they are computed once at setup, from data the host object already owns).

Parameters:

Name Type Description Default
host Matrix

The CPU-resident matrix this was transferred from.

required
device_mat Any

The device-resident payload (a CuPy array or sparse matrix, an MLX array, or the (data, indices, indptr) MLX tuple for CSR).

required
matmul_fn callable

The backend routines computing device_mat @ rhs and lhs @ device_mat, each taking the logical shape as a third argument.

required
rmatmul_fn callable

The backend routines computing device_mat @ rhs and lhs @ device_mat, each taking the logical shape as a third argument.

required
Source code in parafac2/matrix.py
class DeviceMatrix(Matrix):
    """A host matrix whose data has been transferred to an accelerator.

    Holds the device-resident payload plus the product routines that
    understand it, and delegates the norms back to the host matrix (they are
    computed once at setup, from data the host object already owns).

    Parameters
    ----------
    host : Matrix
        The CPU-resident matrix this was transferred from.
    device_mat : Any
        The device-resident payload (a CuPy array or sparse matrix, an MLX
        array, or the ``(data, indices, indptr)`` MLX tuple for CSR).
    matmul_fn, rmatmul_fn : callable
        The backend routines computing ``device_mat @ rhs`` and
        ``lhs @ device_mat``, each taking the logical shape as a third
        argument.
    """

    def __init__(
        self,
        host: Matrix,
        device_mat: Any,
        matmul_fn: Any,
        rmatmul_fn: Any,
    ) -> None:
        self.host = host
        self.device_mat = device_mat
        self._matmul_fn = matmul_fn
        self._rmatmul_fn = rmatmul_fn
        super().__init__(host.shape, host.dtype, host.means)

    def _matmul(self, rhs: np.ndarray) -> np.ndarray:
        return self._matmul_fn(self.device_mat, rhs, self.shape)

    def _rmatmul(self, lhs: np.ndarray) -> np.ndarray:
        return self._rmatmul_fn(lhs, self.device_mat, self.shape)

    def norm_sq(self) -> float:
        return self.host.norm_sq()

    def slice_norms(self, condition_idxs: np.ndarray, n_cond: int) -> np.ndarray:
        return self.host.slice_norms(condition_idxs, n_cond)

    def to_device(self, backend: str | None = None) -> Matrix:
        return self.host.to_device(backend)

Matrix

Bases: ABC

Base class implementing the duck-typed matrix contract.

Subclasses supply the raw products (:meth:_matmul/:meth:_rmatmul, which receive an operand already cast to self.dtype and made C-contiguous) and the two norms. This class layers the shared parts on top: operand coercion, the float64 result contract, and the implicit mean-centering, which is applied as a rank-1 correction to the (small) product rather than by materializing X - 1 mu^T.

Parameters:

Name Type Description Default
shape tuple[int, int]

The matrix's (n_rows, n_cols) shape.

required
dtype dtype

The dtype products are taken in.

required
means ndarray | None

Per-column means to subtract implicitly. None or an all-zero array means no centering.

None
Source code in parafac2/matrix.py
class Matrix(ABC):
    """Base class implementing the duck-typed matrix contract.

    Subclasses supply the raw products (:meth:`_matmul`/:meth:`_rmatmul`,
    which receive an operand already cast to ``self.dtype`` and made
    C-contiguous) and the two norms. This class layers the shared parts on
    top: operand coercion, the float64 result contract, and the implicit
    mean-centering, which is applied as a rank-1 correction to the (small)
    product rather than by materializing ``X - 1 mu^T``.

    Parameters
    ----------
    shape : tuple[int, int]
        The matrix's ``(n_rows, n_cols)`` shape.
    dtype : np.dtype
        The dtype products are taken in.
    means : np.ndarray | None, default None
        Per-column means to subtract implicitly. ``None`` or an all-zero
        array means no centering.
    """

    __array_priority__ = 1000
    __array_ufunc__ = None

    def __init__(
        self,
        shape: tuple[int, int],
        dtype: Any,
        means: np.ndarray | None = None,
    ) -> None:
        self.shape = (int(shape[0]), int(shape[1]))
        self.dtype = np.dtype(dtype)
        self.means = _clean_means(means)

    @abstractmethod
    def _matmul(self, rhs: np.ndarray) -> np.ndarray:
        """Compute the uncentered ``self @ rhs``."""

    @abstractmethod
    def _rmatmul(self, lhs: np.ndarray) -> np.ndarray:
        """Compute the uncentered ``lhs @ self``."""

    @abstractmethod
    def norm_sq(self) -> float:
        """Return the squared Frobenius norm of the (centered) matrix."""

    @abstractmethod
    def slice_norms(self, condition_idxs: np.ndarray, n_cond: int) -> np.ndarray:
        """Return the per-condition Frobenius norms of the (centered) rows.

        Parameters
        ----------
        condition_idxs : np.ndarray
            Integer array assigning each row to a condition in ``[0, n_cond)``.
        n_cond : int
            The total number of conditions.
        """

    def to_device(self, backend: str | None = None) -> Matrix:
        """Return this matrix with its data resident on ``backend``."""
        raise NotImplementedError

    def _operand(self, arr: np.ndarray) -> np.ndarray:
        """Cast a dense operand to this matrix's dtype and C-contiguous layout.

        Taking the product in ``X``'s own dtype matters: handing a float64
        operand to a float32 sparse ``X`` makes SciPy upcast the *whole*
        sparse matrix, doubling both the memory traffic that dominates the
        fit and the peak memory.
        """
        return np.ascontiguousarray(arr, dtype=self.dtype)

    def __matmul__(self, rhs: np.ndarray) -> np.ndarray:
        """Compute ``(self - 1 mu^T) @ rhs`` as a float64 NumPy array."""
        rhs = np.asarray(rhs)
        prod = np.asarray(self._matmul(self._operand(rhs)), dtype=np.float64)
        if self.means is not None:
            prod -= self.means @ rhs
        return prod

    def __rmatmul__(self, lhs: np.ndarray) -> np.ndarray:
        """Compute ``lhs @ (self - 1 mu^T)`` as a float64 NumPy array."""
        lhs = np.asarray(lhs)
        prod = np.asarray(self._rmatmul(self._operand(lhs)), dtype=np.float64)
        if self.means is not None:
            if lhs.ndim == 1:
                prod -= lhs.sum() * self.means
            else:
                prod -= np.outer(lhs.sum(axis=1), self.means)
        return prod

__matmul__(rhs)

Compute (self - 1 mu^T) @ rhs as a float64 NumPy array.

Source code in parafac2/matrix.py
def __matmul__(self, rhs: np.ndarray) -> np.ndarray:
    """Compute ``(self - 1 mu^T) @ rhs`` as a float64 NumPy array."""
    rhs = np.asarray(rhs)
    prod = np.asarray(self._matmul(self._operand(rhs)), dtype=np.float64)
    if self.means is not None:
        prod -= self.means @ rhs
    return prod

__rmatmul__(lhs)

Compute lhs @ (self - 1 mu^T) as a float64 NumPy array.

Source code in parafac2/matrix.py
def __rmatmul__(self, lhs: np.ndarray) -> np.ndarray:
    """Compute ``lhs @ (self - 1 mu^T)`` as a float64 NumPy array."""
    lhs = np.asarray(lhs)
    prod = np.asarray(self._rmatmul(self._operand(lhs)), dtype=np.float64)
    if self.means is not None:
        if lhs.ndim == 1:
            prod -= lhs.sum() * self.means
        else:
            prod -= np.outer(lhs.sum(axis=1), self.means)
    return prod

norm_sq() abstractmethod

Return the squared Frobenius norm of the (centered) matrix.

Source code in parafac2/matrix.py
@abstractmethod
def norm_sq(self) -> float:
    """Return the squared Frobenius norm of the (centered) matrix."""

slice_norms(condition_idxs, n_cond) abstractmethod

Return the per-condition Frobenius norms of the (centered) rows.

Parameters:

Name Type Description Default
condition_idxs ndarray

Integer array assigning each row to a condition in [0, n_cond).

required
n_cond int

The total number of conditions.

required
Source code in parafac2/matrix.py
@abstractmethod
def slice_norms(self, condition_idxs: np.ndarray, n_cond: int) -> np.ndarray:
    """Return the per-condition Frobenius norms of the (centered) rows.

    Parameters
    ----------
    condition_idxs : np.ndarray
        Integer array assigning each row to a condition in ``[0, n_cond)``.
    n_cond : int
        The total number of conditions.
    """

to_device(backend=None)

Return this matrix with its data resident on backend.

Source code in parafac2/matrix.py
def to_device(self, backend: str | None = None) -> Matrix:
    """Return this matrix with its data resident on ``backend``."""
    raise NotImplementedError

GPUMatrix(mat, backend=None, means=None)

Deprecated alias for :func:to_gpu, kept for backwards compatibility.

The GPU-resident matrix is now just another implementation of the duck-typed contract (see :class:DeviceMatrix) rather than a separate wrapper class.

Source code in parafac2/matrix.py
def GPUMatrix(
    mat: Any, backend: str | None = None, means: np.ndarray | None = None
) -> Any:
    """Deprecated alias for :func:`to_gpu`, kept for backwards compatibility.

    The GPU-resident matrix is now just another implementation of the
    duck-typed contract (see :class:`DeviceMatrix`) rather than a separate
    wrapper class.
    """
    return to_gpu(mat, backend=backend, means=means)

as_linear_operator(mat, means=None)

Return mat as a SciPy :class:~scipy.sparse.linalg.LinearOperator.

This is how the data is handed to SciPy's decompositions (see :func:~parafac2.utils.randomized_svd_right): anything :func:as_matrix accepts becomes an operator without the decomposition ever learning what the data actually is or where it lives.

Parameters:

Name Type Description Default
mat Any

Anything :func:as_matrix accepts.

required
means ndarray | None

Per-column means to center by, as accepted by :func:as_matrix.

None

Returns:

Type Description
LinearOperator

An (n_rows, n_cols) float64 operator applying X @ rhs and lhs @ X.

Source code in parafac2/matrix.py
def as_linear_operator(mat: Any, means: np.ndarray | None = None) -> LinearOperator:
    """Return ``mat`` as a SciPy :class:`~scipy.sparse.linalg.LinearOperator`.

    This is how the data is handed to SciPy's decompositions (see
    :func:`~parafac2.utils.randomized_svd_right`): anything :func:`as_matrix`
    accepts becomes an operator without the decomposition ever learning what
    the data actually is or where it lives.

    Parameters
    ----------
    mat : Any
        Anything :func:`as_matrix` accepts.
    means : np.ndarray | None, default None
        Per-column means to center by, as accepted by :func:`as_matrix`.

    Returns
    -------
    LinearOperator
        An ``(n_rows, n_cols)`` float64 operator applying ``X @ rhs`` and
        ``lhs @ X``.
    """
    return _MatrixOperator(as_matrix(mat, means))

as_matrix(mat, means=None)

Return mat as something satisfying the duck-typed matrix contract.

This is the single place in the package that looks at the data's type: a NumPy array or SciPy sparse matrix is wrapped, and anything else is assumed to implement the contract itself and passed through untouched.

Parameters:

Name Type Description Default
mat Any

A NumPy array, a SciPy sparse matrix, or an object already implementing the contract (including a :class:Matrix).

required
means ndarray | None

Per-column means to center by. Only meaningful for a plain NumPy or SciPy input: a type that implements the contract itself already accounts for its own centering.

None

Returns:

Type Description
Any

A :class:DenseMatrix or :class:CSRMatrix for NumPy/SciPy input, otherwise mat itself.

Raises:

Type Description
ValueError

If a nonzero means is passed alongside a matrix that already handles its own centering.

Source code in parafac2/matrix.py
def as_matrix(mat: Any, means: np.ndarray | None = None) -> Any:
    """Return ``mat`` as something satisfying the duck-typed matrix contract.

    This is the single place in the package that looks at the data's type:
    a NumPy array or SciPy sparse matrix is wrapped, and anything else is
    assumed to implement the contract itself and passed through untouched.

    Parameters
    ----------
    mat : Any
        A NumPy array, a SciPy sparse matrix, or an object already
        implementing the contract (including a :class:`Matrix`).
    means : np.ndarray | None, default None
        Per-column means to center by. Only meaningful for a plain NumPy or
        SciPy input: a type that implements the contract itself already
        accounts for its own centering.

    Returns
    -------
    Any
        A :class:`DenseMatrix` or :class:`CSRMatrix` for NumPy/SciPy input,
        otherwise ``mat`` itself.

    Raises
    ------
    ValueError
        If a nonzero ``means`` is passed alongside a matrix that already
        handles its own centering.
    """
    if isinstance(mat, np.ndarray):
        return DenseMatrix(mat, means)
    if issparse(mat):
        return CSRMatrix(mat, means)

    if _clean_means(means) is not None:
        raise ValueError(
            f"{type(mat).__name__} implements its own centering, so passing a "
            "nonzero `means` alongside it is not supported."
        )
    return mat

to_gpu(mat, backend=None, means=None)

Wrap mat for the fit and move it to the resolved backend's device.

Parameters:

Name Type Description Default
mat Any

The matrix to (optionally) transfer, as accepted by :func:as_matrix.

required
backend str

One of 'mlx', 'cupy', or 'cpu'. If None, the first available accelerator is auto-detected (see :func:~parafac2.backend.get_backend).

None
means ndarray | None

Per-column means to center by, as accepted by :func:as_matrix.

None

Returns:

Type Description
Any

The device-resident matrix on a GPU backend, otherwise the CPU-resident one.

Raises:

Type Description
TypeError

If a GPU backend is selected for a duck-typed matrix that does not implement to_device.

Source code in parafac2/matrix.py
def to_gpu(
    mat: Any, backend: str | None = None, means: np.ndarray | None = None
) -> Any:
    """Wrap ``mat`` for the fit and move it to the resolved backend's device.

    Parameters
    ----------
    mat : Any
        The matrix to (optionally) transfer, as accepted by :func:`as_matrix`.
    backend : str, optional
        One of ``'mlx'``, ``'cupy'``, or ``'cpu'``. If ``None``, the first
        available accelerator is auto-detected (see
        :func:`~parafac2.backend.get_backend`).
    means : np.ndarray | None, default None
        Per-column means to center by, as accepted by :func:`as_matrix`.

    Returns
    -------
    Any
        The device-resident matrix on a GPU backend, otherwise the
        CPU-resident one.

    Raises
    ------
    TypeError
        If a GPU backend is selected for a duck-typed matrix that does not
        implement ``to_device``.
    """
    X = as_matrix(mat, means)
    chosen = get_backend(backend)
    if chosen == "cpu":
        return X

    to_device = getattr(X, "to_device", None)
    if to_device is None:
        raise TypeError(
            f"{type(X).__name__} does not implement `to_device`, so it cannot "
            f"run on the {chosen!r} backend. Pass backend='cpu', or convert "
            "it to a NumPy array or SciPy sparse array first."
        )
    return to_device(chosen)

parafac2.utils

parafac2.utils

Low-level numerical routines supporting the PARAFAC2 fit.

Provides the per-condition projection step, the per-mode ALS factor update (which forms its own MTTKRP), the randomized SVD used for initialization and gene compression (SciPy's, driven through a linear operator over the data), and post-fit standardization of the factors and projections.

The fit touches the raw data through exactly two products, which together dominate runtime on single-cell-sized inputs:

  • W = (X - 1 mu^T) @ C (:func:calc_W), which depends only on C.
  • X^T @ H for the mode-2 MTTKRP (inside :func:parafac_update).

Everything else flows through the compressed per-condition slices S_k = P_k^T W_k, an (n_cond, rank, rank) array small enough to keep resident. In particular the mode-0 and mode-1 MTTKRPs and the reconstruction error are all functions of S alone, so the projections and both of those factor updates can be recomputed from a cached W without re-reading the data.

Nothing here inspects X's type. X is any object satisfying the duck-typed matrix contract in :mod:parafac2.matrix -- a NumPy array or SciPy CSR array wrapped by :func:~parafac2.matrix.as_matrix, or a third-party type (e.g. one of vsparse's normalized views) implementing it directly. In particular the matrix carries its own mean-centering, so X @ C already means (X - 1 mu^T) @ C and no means argument is threaded through these routines.

calc_W(X, C)

Compute W = (X - 1 mu^T) @ C, the first of the two raw-data products.

W depends only on C, so it stays valid across the A and B updates and only has to be recomputed once C changes. Any centering and dtype handling belongs to X itself (see :mod:parafac2.matrix).

Parameters:

Name Type Description Default
X Any

The data matrix, stacked across all conditions, with shape (total_cells, n_genes).

required
C ndarray

The current gene factor matrix, shape (n_genes, rank).

required

Returns:

Type Description
ndarray

The float64 array W of shape (total_cells, rank).

Source code in parafac2/utils.py
def calc_W(X: Any, C: np.ndarray) -> np.ndarray:
    """Compute ``W = (X - 1 mu^T) @ C``, the first of the two raw-data products.

    ``W`` depends only on ``C``, so it stays valid across the ``A`` and ``B``
    updates and only has to be recomputed once ``C`` changes. Any centering
    and dtype handling belongs to ``X`` itself (see :mod:`parafac2.matrix`).

    Parameters
    ----------
    X : Any
        The data matrix, stacked across all conditions, with shape
        ``(total_cells, n_genes)``.
    C : np.ndarray
        The current gene factor matrix, shape ``(n_genes, rank)``.

    Returns
    -------
    np.ndarray
        The float64 array ``W`` of shape ``(total_cells, rank)``.
    """
    return np.asarray(X @ C, dtype=np.float64)

calc_err(S, factors, norm_X_sq)

Return the squared reconstruction error from the compressed slices.

Uses the expansion ||X||^2 + Tr(A^T A * B^T B * C^T C) - 2 <A, diag(B^T S_k)>, so no raw-data pass is needed and the error is free to evaluate as often as desired (e.g. to monitor an inner iteration).

Parameters:

Name Type Description Default
S ndarray

The stacked compressed slices from :func:project_data.

required
factors list[ndarray]

The current [A, B, C] factor matrices.

required
norm_X_sq float

The squared Frobenius norm of the mean-centered X, as returned by :func:calc_norm_sq.

required

Returns:

Type Description
float

The squared reconstruction error.

Source code in parafac2/utils.py
def calc_err(S: np.ndarray, factors: list[np.ndarray], norm_X_sq: float) -> float:
    """Return the squared reconstruction error from the compressed slices.

    Uses the expansion ``||X||^2 + Tr(A^T A * B^T B * C^T C) - 2 <A, diag(B^T
    S_k)>``, so no raw-data pass is needed and the error is free to evaluate
    as often as desired (e.g. to monitor an inner iteration).

    Parameters
    ----------
    S : np.ndarray
        The stacked compressed slices from :func:`project_data`.
    factors : list[np.ndarray]
        The current ``[A, B, C]`` factor matrices.
    norm_X_sq : float
        The squared Frobenius norm of the mean-centered ``X``, as returned by
        :func:`calc_norm_sq`.

    Returns
    -------
    float
        The squared reconstruction error.
    """
    A, B, C = factors
    norm_sq_err = norm_X_sq + float(((A.T @ A) * (B.T @ B) * (C.T @ C)).sum())
    norm_sq_err -= 2.0 * float(np.sum(A * np.einsum("kqr,qr->kr", S, B)))
    return norm_sq_err

condition_slices(condition_unique_idxs, n_cond)

Return a per-condition row selector for each condition.

Computing condition_unique_idxs == i inside the per-condition loop costs O(n_cells) per condition, i.e. O(n_cells * n_cond) per pass over the data, plus a fancy-indexed copy each time. Precomputing the selectors once drops that to O(n_cells), and when the rows are already grouped by condition (the usual case, since conditions are concatenated) the selectors are plain slice objects, making W[sel] a zero-copy view.

Parameters:

Name Type Description Default
condition_unique_idxs ndarray

Integer array assigning each row to a condition in [0, n_cond).

required
n_cond int

The total number of conditions.

required

Returns:

Type Description
list[slice | ndarray]

One selector per condition: a slice when the condition's rows are contiguous, otherwise an integer index array.

Source code in parafac2/utils.py
def condition_slices(
    condition_unique_idxs: np.ndarray, n_cond: int
) -> list[slice | np.ndarray]:
    """Return a per-condition row selector for each condition.

    Computing ``condition_unique_idxs == i`` inside the per-condition loop
    costs ``O(n_cells)`` per condition, i.e. ``O(n_cells * n_cond)`` per pass
    over the data, plus a fancy-indexed copy each time. Precomputing the
    selectors once drops that to ``O(n_cells)``, and when the rows are
    already grouped by condition (the usual case, since conditions are
    concatenated) the selectors are plain ``slice`` objects, making
    ``W[sel]`` a zero-copy view.

    Parameters
    ----------
    condition_unique_idxs : np.ndarray
        Integer array assigning each row to a condition in ``[0, n_cond)``.
    n_cond : int
        The total number of conditions.

    Returns
    -------
    list[slice | np.ndarray]
        One selector per condition: a ``slice`` when the condition's rows are
        contiguous, otherwise an integer index array.
    """
    idxs = np.asarray(condition_unique_idxs)

    if idxs.size and np.all(np.diff(idxs) >= 0):
        starts = np.searchsorted(idxs, np.arange(n_cond), side="left")
        stops = np.searchsorted(idxs, np.arange(n_cond), side="right")
        return [slice(int(a), int(b)) for a, b in zip(starts, stops, strict=True)]

    order = np.argsort(idxs, kind="stable")
    bounds = np.searchsorted(idxs[order], np.arange(n_cond + 1))
    return [order[bounds[k] : bounds[k + 1]] for k in range(n_cond)]

extract_dataset_info(X_in, normalize_slices=False)

Wrap an AnnData's matrix and summarize what the fit needs up front.

This is the boundary where a dataset stops being a specific storage type and becomes an opaque duck-typed matrix: X_in.X is handed to :func:~parafac2.matrix.as_matrix together with any per-gene means, and everything downstream works through that object alone.

Parameters:

Name Type Description Default
X_in AnnData

Input single-cell AnnData dataset.

required
normalize_slices bool

Whether to calculate per-condition slice inverse-norm weights.

False

Returns:

Type Description
tuple[Any, ndarray, ndarray, float, ndarray | None, float | None]

The (X, condition_unique_idxs, means, norm_tensor, slice_weights, norm_weighted) tuple, where norm_weighted is the squared norm of the weighted slices w_k X_k (None without weights). means is returned for bookkeeping only -- it is already folded into X.

Source code in parafac2/utils.py
def extract_dataset_info(
    X_in: anndata.AnnData,
    normalize_slices: bool = False,
) -> tuple[Any, np.ndarray, np.ndarray, float, np.ndarray | None, float | None]:
    """Wrap an AnnData's matrix and summarize what the fit needs up front.

    This is the boundary where a dataset stops being a specific storage type
    and becomes an opaque duck-typed matrix: ``X_in.X`` is handed to
    :func:`~parafac2.matrix.as_matrix` together with any per-gene means, and
    everything downstream works through that object alone.

    Parameters
    ----------
    X_in : anndata.AnnData
        Input single-cell AnnData dataset.
    normalize_slices : bool, default False
        Whether to calculate per-condition slice inverse-norm weights.

    Returns
    -------
    tuple[Any, np.ndarray, np.ndarray, float, np.ndarray | None, float | None]
        The ``(X, condition_unique_idxs, means, norm_tensor, slice_weights,
        norm_weighted)`` tuple, where ``norm_weighted`` is the squared norm of
        the weighted slices ``w_k X_k`` (``None`` without weights). ``means``
        is returned for bookkeeping only -- it is already folded into ``X``.
    """
    assert X_in.X is not None
    condition_unique_idxs = cast(
        "np.ndarray", X_in.obs["condition_unique_idxs"].to_numpy(dtype=int)
    )
    n_cond = int(np.amax(condition_unique_idxs)) + 1

    if "means" in X_in.var:
        means = X_in.var["means"].to_numpy()
    else:
        means = np.zeros(X_in.shape[1])

    X = as_matrix(X_in.X, means)
    norm_tensor = float(X.norm_sq())

    slice_weights: np.ndarray | None = None
    norm_weighted: float | None = None
    if normalize_slices:
        slice_norms = np.asarray(
            X.slice_norms(condition_unique_idxs, n_cond), dtype=np.float64
        )
        slice_weights = np.where(slice_norms > 1e-10, 1.0 / slice_norms, 1.0)
        norm_weighted = float(np.sum((slice_weights * slice_norms) ** 2))

    return X, condition_unique_idxs, means, norm_tensor, slice_weights, norm_weighted

parafac_update(factors, mode, S, projections=None, *, X=None, cond_slices=None, slice_weights=None)

Form the MTTKRP for the requested mode and update that factor.

Modes 0 and 1 are built from the compressed slices S alone and cost O(n_cond * rank^2). Mode 2 is the only update that has to revisit the raw data, via X^T @ H with H_k = P_k B diag(a_k).

slice_weights, if given, scales each condition's MTTKRP contribution, so the update fits the weighted slices w_k X_k without copying X.

Parameters:

Name Type Description Default
factors list[ndarray]

The current [A, B, C] factor matrices; factors[mode] is replaced with the updated matrix.

required
mode int

Which factor to update (index into factors).

required
S ndarray

The stacked compressed slices from :func:project_data.

required
projections list[ndarray] | None

The per-condition projections. Required for mode=2 only.

None
X (Any, keyword - only)

The raw data matrix. Required for mode=2 only.

None
cond_slices (list[slice | ndarray] | None, keyword - only)

Per-condition row selectors from :func:condition_slices. Required for mode=2 only.

None
slice_weights (ndarray | None, keyword - only)

Optional per-condition scalar weights, as described above.

None

Returns:

Type Description
list[ndarray]

factors, with factors[mode] updated by solving the normal equations factors[mode] @ v = mttkrp for the Gram-matrix product v of the other factors (falling back to a least-squares solve if v is singular).

Raises:

Type Description
ValueError

If mode=2 is requested without projections, X, or cond_slices.

Source code in parafac2/utils.py
def parafac_update(
    factors: list[np.ndarray],
    mode: int,
    S: np.ndarray,
    projections: list[np.ndarray] | None = None,
    *,
    X: Any = None,
    cond_slices: list[slice | np.ndarray] | None = None,
    slice_weights: np.ndarray | None = None,
) -> list[np.ndarray]:
    """
    Form the MTTKRP for the requested mode and update that factor.

    Modes 0 and 1 are built from the compressed slices ``S`` alone and cost
    ``O(n_cond * rank^2)``. Mode 2 is the only update that has to revisit the
    raw data, via ``X^T @ H`` with ``H_k = P_k B diag(a_k)``.

    ``slice_weights``, if given, scales each condition's MTTKRP contribution,
    so the update fits the weighted slices ``w_k X_k`` without copying ``X``.

    Parameters
    ----------
    factors : list[np.ndarray]
        The current ``[A, B, C]`` factor matrices; ``factors[mode]`` is
        replaced with the updated matrix.
    mode : int
        Which factor to update (index into ``factors``).
    S : np.ndarray
        The stacked compressed slices from :func:`project_data`.
    projections : list[np.ndarray] | None, default None
        The per-condition projections. Required for ``mode=2`` only.
    X : Any, keyword-only, default None
        The raw data matrix. Required for ``mode=2`` only.
    cond_slices : list[slice | np.ndarray] | None, keyword-only, default None
        Per-condition row selectors from :func:`condition_slices`. Required
        for ``mode=2`` only.
    slice_weights : np.ndarray | None, keyword-only, default None
        Optional per-condition scalar weights, as described above.

    Returns
    -------
    list[np.ndarray]
        ``factors``, with ``factors[mode]`` updated by solving the normal
        equations ``factors[mode] @ v = mttkrp`` for the Gram-matrix product
        ``v`` of the other factors (falling back to a least-squares solve if
        ``v`` is singular).

    Raises
    ------
    ValueError
        If ``mode=2`` is requested without ``projections``, ``X``, or
        ``cond_slices``.
    """
    A, B, _C = factors
    rank = B.shape[0]

    if mode == 0:
        mttkrp = np.einsum("kqr,qr->kr", S, B)
        if slice_weights is not None:
            mttkrp = mttkrp * slice_weights[:, np.newaxis]
    elif mode == 1:
        A_w = A if slice_weights is None else A * slice_weights[:, np.newaxis]
        mttkrp = np.einsum("kqr,kr->qr", S, A_w)
    else:
        if projections is None or X is None or cond_slices is None:
            raise ValueError(
                "mode=2 needs `projections`, `X`, and `cond_slices` to form its MTTKRP."
            )
        # Build H^T directly, in X's own dtype, so the dense operand of the
        # X^T @ H product needs no conversion on its way into the kernel.
        H_T = np.empty((rank, X.shape[0]), dtype=X.dtype)
        for k, sel in enumerate(cond_slices):
            w_k = 1.0 if slice_weights is None else slice_weights[k]
            H_T[:, sel] = (projections[k] @ (B * A[k]) * w_k).T

        mttkrp = np.asarray(H_T @ X, dtype=np.float64).T

    return solve_factors(factors, mttkrp, mode)

polar_factor(M)

Compute the nearest matrix with orthonormal columns to M.

Uses the thin SVD M = U S V^T, whose orthonormal factor U @ V^T is the (Frobenius-norm) nearest matrix with orthonormal columns to M -- unlike a näive M @ V / diag(S) reconstruction, this stays exactly orthonormal even when M is column-rank-deficient (some singular values are zero), since LAPACK's SVD always returns a fully orthonormal U regardless of M's rank, filling in arbitrary-but-orthonormal directions for the zero-singular-value columns.

Raises:

Type Description
ValueError

If M has fewer rows than columns: no matrix of that shape can have orthonormal columns (there is no room for that many independent unit vectors), so this is a genuine shape mismatch upstream (e.g. a PARAFAC2 condition with fewer cells than the fit rank) rather than something this function can paper over.

Source code in parafac2/utils.py
def polar_factor(M: np.ndarray) -> np.ndarray:
    """Compute the nearest matrix with orthonormal columns to M.

    Uses the thin SVD ``M = U S V^T``, whose orthonormal factor ``U @ V^T``
    is the (Frobenius-norm) nearest matrix with orthonormal columns to M --
    unlike a näive ``M @ V / diag(S)`` reconstruction, this stays exactly
    orthonormal even when M is column-rank-deficient (some singular values
    are zero), since LAPACK's SVD always returns a fully orthonormal ``U``
    regardless of M's rank, filling in arbitrary-but-orthonormal directions
    for the zero-singular-value columns.

    Raises
    ------
    ValueError
        If M has fewer rows than columns: no matrix of that shape can have
        orthonormal columns (there is no room for that many independent
        unit vectors), so this is a genuine shape mismatch upstream (e.g. a
        PARAFAC2 condition with fewer cells than the fit rank) rather than
        something this function can paper over.
    """
    n_rows, rank = M.shape
    if n_rows < rank:
        raise ValueError(
            f"Cannot form an orthonormal {n_rows}x{rank} matrix: orthonormal "
            f"columns require at least as many rows as columns, but only "
            f"{n_rows} are available for {rank} requested. This condition "
            f"has fewer cells than the fit rank; PARAFAC2 requires every "
            f"condition to have at least `rank` cells."
        )
    U, _S, Vt = np.linalg.svd(M, full_matrices=False)
    return U @ Vt

project_data(W, factors, cond_slices)

Compute each condition's projection matrix and compressed slice.

For condition k the projection P_k is the orthonormal polar factor of W_k diag(a_k) B^T, and the compressed slice is S_k = P_k^T W_k. Costs O(n_cells * rank^2) and touches no raw data, so it is roughly two orders of magnitude cheaper than :func:calc_W and can be repeated freely while W is cached.

Parameters:

Name Type Description Default
W ndarray

The cached (X - 1 mu^T) @ C from :func:calc_W.

required
factors list[ndarray]

The current [A, B, C] factor matrices.

required
cond_slices list[slice | ndarray]

Per-condition row selectors from :func:condition_slices.

required

Returns:

Type Description
tuple[list[ndarray], ndarray]

The per-condition projections P_k (each (n_k, rank) with orthonormal columns), and the stacked compressed slices S with shape (n_cond, rank, rank).

Source code in parafac2/utils.py
def project_data(
    W: np.ndarray,
    factors: list[np.ndarray],
    cond_slices: list[slice | np.ndarray],
) -> tuple[list[np.ndarray], np.ndarray]:
    """Compute each condition's projection matrix and compressed slice.

    For condition ``k`` the projection ``P_k`` is the orthonormal polar
    factor of ``W_k diag(a_k) B^T``, and the compressed slice is
    ``S_k = P_k^T W_k``. Costs ``O(n_cells * rank^2)`` and touches no raw
    data, so it is roughly two orders of magnitude cheaper than
    :func:`calc_W` and can be repeated freely while ``W`` is cached.

    Parameters
    ----------
    W : np.ndarray
        The cached ``(X - 1 mu^T) @ C`` from :func:`calc_W`.
    factors : list[np.ndarray]
        The current ``[A, B, C]`` factor matrices.
    cond_slices : list[slice | np.ndarray]
        Per-condition row selectors from :func:`condition_slices`.

    Returns
    -------
    tuple[list[np.ndarray], np.ndarray]
        The per-condition projections ``P_k`` (each ``(n_k, rank)`` with
        orthonormal columns), and the stacked compressed slices ``S`` with
        shape ``(n_cond, rank, rank)``.
    """
    A, B = factors[0], factors[1]
    rank = B.shape[0]

    projections: list[np.ndarray] = []
    S = np.empty((len(cond_slices), rank, rank))

    for i, sel in enumerate(cond_slices):
        W_i = W[sel]
        M = W_i @ (B * A[i]).T  # (n_k, rank)
        proj = polar_factor(M)
        projections.append(proj)
        S[i] = proj.T @ W_i

    return projections, S

randomized_svd_right(X, n_components, n_oversamples=0, n_power_iter=20, random_state=None, row_weights=None)

Compute the top right-singular vectors of the mean-centered matrix (X - 1 mu^T).

The data is wrapped as a linear operator (:func:~parafac2.matrix.as_linear_operator) and handed to :func:scipy.sparse.linalg.lobpcg, which is run against the Gram operator X^T X -- whose top eigenvectors are exactly the right-singular vectors being sought -- from a random orthonormal start. LOBPCG applies the operator to the whole block at once, so an iteration costs one pass over the data in each direction, the same as a power iteration, with a Rayleigh-Ritz step and a conjugate search direction on top. Its Rayleigh-Ritz step is also why the starting subspace barely matters: warm-starting it from a randomized decomposition was measured to reach the same answer as a random start at the same iteration count, while costing the decomposition on top.

Below 5 * n_components columns LOBPCG cannot run (it would fall back to densifying the operator, which for a data matrix is the one thing this may not do), so that case is solved exactly instead, via :func:_exact_right_vectors.

Parameters:

Name Type Description Default
X Any

The data matrix of shape (total_cells, n_genes), already accounting for any mean-centering (see :mod:parafac2.matrix).

required
n_components int

Number of right-singular vectors to return.

required
n_oversamples int

Extra directions to carry through the refinement before truncating to n_components. A wider block costs proportionally more per iteration and is rarely worth it here.

0
n_power_iter int

Maximum number of LOBPCG iterations; it stops early once the subspace has converged. Must be at least 1: unlike a randomized decomposition, the starting subspace here carries no information of its own, so there is no meaningful zero-iteration answer.

20
random_state int | Generator | None

Random seed or NumPy generator for the starting subspace.

None
row_weights ndarray | None

Per-row weights d; if given, the vectors are those of diag(d) (X - 1 mu^T).

None

Returns:

Type Description
ndarray

Array of shape (n_genes, n_components) with orthonormal columns.

Raises:

Type Description
ValueError

If n_components exceeds min(n_cells, n_genes), the maximum possible rank of X, and therefore the most orthonormal columns its row space can supply, or if n_power_iter is below 1.

Source code in parafac2/utils.py
def randomized_svd_right(
    X: Any,
    n_components: int,
    n_oversamples: int = 0,
    n_power_iter: int = 20,
    random_state: int | np.random.Generator | None = None,
    row_weights: np.ndarray | None = None,
) -> np.ndarray:
    """Compute the top right-singular vectors of the mean-centered matrix ``(X - 1 mu^T)``.

    The data is wrapped as a linear operator
    (:func:`~parafac2.matrix.as_linear_operator`) and handed to
    :func:`scipy.sparse.linalg.lobpcg`, which is run against the Gram
    operator ``X^T X`` -- whose top eigenvectors are exactly the
    right-singular vectors being sought -- from a random orthonormal start.
    LOBPCG applies the operator to the whole block at once, so an iteration
    costs one pass over the data in each direction, the same as a power
    iteration, with a Rayleigh-Ritz step and a conjugate search direction on
    top. Its Rayleigh-Ritz step is also why the starting subspace barely
    matters: warm-starting it from a randomized decomposition was measured to
    reach the same answer as a random start at the same iteration count,
    while costing the decomposition on top.

    Below ``5 * n_components`` columns LOBPCG cannot run (it would fall back
    to densifying the operator, which for a data matrix is the one thing this
    may not do), so that case is solved exactly instead, via
    :func:`_exact_right_vectors`.

    Parameters
    ----------
    X : Any
        The data matrix of shape ``(total_cells, n_genes)``, already
        accounting for any mean-centering (see :mod:`parafac2.matrix`).
    n_components : int
        Number of right-singular vectors to return.
    n_oversamples : int, default 0
        Extra directions to carry through the refinement before truncating
        to ``n_components``. A wider block costs proportionally more per
        iteration and is rarely worth it here.
    n_power_iter : int, default 20
        Maximum number of LOBPCG iterations; it stops early once the subspace
        has converged. Must be at least 1: unlike a randomized decomposition,
        the starting subspace here carries no information of its own, so
        there is no meaningful zero-iteration answer.
    random_state : int | np.random.Generator | None, default None
        Random seed or NumPy generator for the starting subspace.
    row_weights : np.ndarray | None, default None
        Per-row weights ``d``; if given, the vectors are those of
        ``diag(d) (X - 1 mu^T)``.

    Returns
    -------
    np.ndarray
        Array of shape ``(n_genes, n_components)`` with orthonormal columns.

    Raises
    ------
    ValueError
        If ``n_components`` exceeds ``min(n_cells, n_genes)``, the maximum
        possible rank of ``X``, and therefore the most orthonormal columns
        its row space can supply, or if ``n_power_iter`` is below 1.
    """
    n_cells, n_genes = X.shape
    max_components = min(n_cells, n_genes)
    if n_components > max_components:
        raise ValueError(
            f"n_components ({n_components}) cannot exceed the maximum "
            f"possible rank of a {n_cells}x{n_genes} matrix "
            f"({max_components})."
        )
    if n_power_iter < 1:
        raise ValueError(
            f"n_power_iter ({n_power_iter}) must be at least 1; the starting "
            "subspace is random, so no iterations means no answer."
        )

    op = as_linear_operator(X)
    if row_weights is not None:
        op = aslinearoperator(diags_array(row_weights)) @ op
    block_size = min(max_components, n_components + n_oversamples)
    if n_genes < 5 * block_size:
        return _exact_right_vectors(op, n_components)

    rng = np.random.default_rng(random_state)
    start, _ = np.linalg.qr(rng.normal(size=(n_genes, block_size)))

    with warnings.catch_warnings():
        # A fixed iteration budget is the point here, so LOBPCG stopping
        # short of its tolerance is expected rather than noteworthy.
        warnings.simplefilter("ignore", UserWarning)
        _eigenvalues, V = lobpcg(op.H @ op, start, largest=True, maxiter=n_power_iter)

    # LOBPCG can break down on a degenerate Gram operator (a matrix with no
    # signal at all, say); the orthonormal starting block is then as good an
    # answer as any, and is at least a valid one.
    if not np.all(np.isfinite(V)):
        V = start
    return np.ascontiguousarray(V[:, :n_components], dtype=np.float64)

solve_factors(factors, mttkrp, mode)

ALS factor update for a single mode using its precomputed MTTKRP.

Source code in parafac2/utils.py
def solve_factors(
    factors: list[np.ndarray],
    mttkrp: np.ndarray,
    mode: int,
) -> list[np.ndarray]:
    """ALS factor update for a single mode using its precomputed MTTKRP."""
    rank = factors[0].shape[1]
    v = np.ones((rank, rank))
    for i, factor in enumerate(factors):
        if i != mode:
            v *= factor.T @ factor

    try:
        factors[mode] = np.linalg.solve(v.T, mttkrp.T).T
    except np.linalg.LinAlgError:
        factors[mode] = np.linalg.lstsq(v.T, mttkrp.T, rcond=None)[0].T

    return factors

standardize_pf2(factors, projections)

Put a fitted PARAFAC2 model into a canonical, comparable form.

Reorders components by condition variance-to-mean ratio, normalizes and sign-flips the factors (via TensorLy's cp_normalize/cp_flip_sign), permutes components to maximize the diagonal of B (via linear-sum assignment), and flips signs so that B's diagonal is non-negative.

Parameters:

Name Type Description Default
factors list[ndarray]

The fitted [A, B, C] factor matrices.

required
projections list[ndarray]

The fitted per-condition projection matrices P_k.

required

Returns:

Type Description
tuple[ndarray, list[ndarray], list[ndarray]]

The (weights, factors, projections) triple after standardization, with components reordered/sign-flipped consistently across factors and projections.

Source code in parafac2/utils.py
def standardize_pf2(
    factors: list[np.ndarray], projections: list[np.ndarray]
) -> tuple[np.ndarray, list[np.ndarray], list[np.ndarray]]:
    """Put a fitted PARAFAC2 model into a canonical, comparable form.

    Reorders components by condition variance-to-mean ratio, normalizes and
    sign-flips the factors (via TensorLy's ``cp_normalize``/``cp_flip_sign``),
    permutes components to maximize the diagonal of ``B`` (via linear-sum
    assignment), and flips signs so that ``B``'s diagonal is non-negative.

    Parameters
    ----------
    factors : list[np.ndarray]
        The fitted ``[A, B, C]`` factor matrices.
    projections : list[np.ndarray]
        The fitted per-condition projection matrices ``P_k``.

    Returns
    -------
    tuple[np.ndarray, list[np.ndarray], list[np.ndarray]]
        The ``(weights, factors, projections)`` triple after standardization,
        with components reordered/sign-flipped consistently across
        ``factors`` and ``projections``.
    """
    # Order components by condition variance-to-mean ratio
    mean_a = np.mean(factors[0], axis=0)
    gini = np.divide(
        np.var(factors[0], axis=0),
        mean_a,
        out=np.zeros_like(mean_a),
        where=np.abs(mean_a) > 1e-12,
    )
    gini_idx = np.argsort(gini)
    factors = [f[:, gini_idx] for f in factors]

    weights, factors = cp_flip_sign(cp_normalize((None, factors)), mode=1)

    # Order eigen-cells to maximize the diagonal of B
    _, col_ind = linear_sum_assignment(np.abs(factors[1].T), maximize=True)
    factors[1] = factors[1][col_ind, :]
    projections = [p[:, col_ind] for p in projections]

    # Flip the sign based on B
    signn = np.sign(np.diag(factors[1]))
    factors[1] *= signn[:, np.newaxis]
    projections = [p * signn for p in projections]

    return weights, factors, projections

parafac2.backend

parafac2.backend

Low-level device primitives for CPU, Apple GPU (MLX), and NVIDIA GPU (CuPy).

This module knows about devices, not about matrices: it resolves which backend to run on, accounts for device memory, and provides the transfer and kernel routines for dense and CSR operands on each backend. Nothing here inspects the type of the user's data.

The matrix types that consume these primitives -- and the duck-typed contract the rest of the package talks to -- live in :mod:parafac2.matrix.

csr_device_bytes(mat_csr)

Bytes a SciPy CSR array will occupy on a CuPy device.

cupyx stores indices and indptr in one shared index dtype, so a nonzero count past the int32 limit widens both to 8 bytes per entry.

Source code in parafac2/backend.py
def csr_device_bytes(mat_csr: Any) -> int:
    """Bytes a SciPy CSR array will occupy on a CuPy device.

    ``cupyx`` stores ``indices`` and ``indptr`` in one shared index dtype, so
    a nonzero count past the int32 limit widens both to 8 bytes per entry.
    """
    nnz = int(mat_csr.data.size)
    int32_max = np.iinfo(np.int32).max
    idx_size = 8 if (max(mat_csr.shape) > int32_max or nnz > int32_max) else 4
    return int(mat_csr.data.nbytes + (nnz + mat_csr.shape[0] + 1) * idx_size)

cupy_csr_matmul(device_mat, rhs, shape)

Compute device_mat @ rhs (sparse CSR @ dense) via nvmath-python.

CuPy's own @ for a CSR-by-dense product prefers cuSPARSE's legacy csrmm2 routine, which only understands 32-bit indices: it hands the raw indices/indptr device pointers straight to that int32-only API with no dtype check, so once a matrix has more than 2**31 - 1 nonzeros (and therefore int64 indices), the call reads those buffers as the wrong width and silently corrupts the result. nvmath-python's nvmath.sparse.matmul goes through cuSPARSE's generic SpMM API instead, which is told the operands' actual index type (CUSPARSE_INDEX_64I when needed), so it stays correct at any nnz.

Source code in parafac2/backend.py
def cupy_csr_matmul(
    device_mat: Any, rhs: np.ndarray, shape: tuple[int, int]
) -> np.ndarray:
    """Compute ``device_mat @ rhs`` (sparse CSR @ dense) via nvmath-python.

    CuPy's own ``@`` for a CSR-by-dense product prefers cuSPARSE's legacy
    ``csrmm2`` routine, which only understands 32-bit indices: it hands the
    raw ``indices``/``indptr`` device pointers straight to that int32-only
    API with no dtype check, so once a matrix has more than ``2**31 - 1``
    nonzeros (and therefore int64 indices), the call reads those buffers as
    the wrong width and silently corrupts the result. nvmath-python's
    ``nvmath.sparse.matmul`` goes through cuSPARSE's *generic* SpMM API
    instead, which is told the operands' actual index type
    (``CUSPARSE_INDEX_64I`` when needed), so it stays correct at any ``nnz``.
    """
    import cupy as cp  # ty: ignore[unresolved-import]
    import nvmath  # ty: ignore[unresolved-import]

    cp_rhs = cp.asarray(rhs)
    rhs_2d = cp_rhs[:, None] if cp_rhs.ndim == 1 else cp_rhs
    out_dtype = cp.result_type(device_mat.dtype, cp_rhs.dtype)
    out = cp.zeros((device_mat.shape[0], rhs_2d.shape[1]), dtype=out_dtype)
    res = nvmath.sparse.matmul(device_mat, rhs_2d, out)
    return cp.asnumpy(res.ravel() if cp_rhs.ndim == 1 else res)

cupy_csr_rmatmul(lhs, device_mat, shape)

Compute lhs @ device_mat (dense @ sparse CSR) via nvmath-python.

nvmath's SpMM always takes the sparse operand first, so this computes the equivalent (device_mat.T @ lhs.T).T using the is_transpose matrix qualifier rather than materializing a transposed copy of device_mat. See :func:cupy_csr_matmul for why cuSPARSE's legacy routines (which CuPy's own @ would otherwise use here) are unsafe for int64-indexed matrices.

Source code in parafac2/backend.py
def cupy_csr_rmatmul(
    lhs: np.ndarray, device_mat: Any, shape: tuple[int, int]
) -> np.ndarray:
    """Compute ``lhs @ device_mat`` (dense @ sparse CSR) via nvmath-python.

    nvmath's SpMM always takes the sparse operand first, so this computes
    the equivalent ``(device_mat.T @ lhs.T).T`` using the ``is_transpose``
    matrix qualifier rather than materializing a transposed copy of
    ``device_mat``. See :func:`cupy_csr_matmul` for why cuSPARSE's legacy
    routines (which CuPy's own ``@`` would otherwise use here) are unsafe
    for int64-indexed matrices.
    """
    import cupy as cp  # ty: ignore[unresolved-import]
    import nvmath  # ty: ignore[unresolved-import]

    cp_lhs = cp.asarray(lhs)
    lhs_2d = cp_lhs[None, :] if cp_lhs.ndim == 1 else cp_lhs
    qualifiers = np.zeros(3, dtype=nvmath.sparse.matmul_matrix_qualifiers_dtype)
    qualifiers[0]["is_transpose"] = 1
    out_dtype = cp.result_type(device_mat.dtype, cp_lhs.dtype)
    out = cp.zeros((device_mat.shape[1], lhs_2d.shape[0]), dtype=out_dtype)
    res = nvmath.sparse.matmul(
        device_mat, cp.asfortranarray(lhs_2d.T), out, qualifiers=qualifiers
    ).T
    return cp.asnumpy(res.ravel() if cp_lhs.ndim == 1 else res)

cupy_dense_matmul(device_mat, rhs, shape)

Compute device_mat @ rhs for a dense CuPy-resident matrix.

Dense products go through cuBLAS's plain @, which has no int32 index limitation to work around.

Source code in parafac2/backend.py
def cupy_dense_matmul(
    device_mat: Any, rhs: np.ndarray, shape: tuple[int, int]
) -> np.ndarray:
    """Compute ``device_mat @ rhs`` for a dense CuPy-resident matrix.

    Dense products go through cuBLAS's plain ``@``, which has no int32 index
    limitation to work around.
    """
    import cupy as cp  # ty: ignore[unresolved-import]

    return cp.asnumpy(device_mat @ cp.asarray(rhs))

cupy_dense_rmatmul(lhs, device_mat, shape)

Compute lhs @ device_mat for a dense CuPy-resident matrix.

Source code in parafac2/backend.py
def cupy_dense_rmatmul(
    lhs: np.ndarray, device_mat: Any, shape: tuple[int, int]
) -> np.ndarray:
    """Compute ``lhs @ device_mat`` for a dense CuPy-resident matrix."""
    import cupy as cp  # ty: ignore[unresolved-import]

    return cp.asnumpy(cp.asarray(lhs) @ device_mat)

ensure_device_capacity(nbytes, what='matrix')

Install the managed-memory allocator if nbytes will not fit.

Raises:

Type Description
MemoryError

If the transfer does not fit and the device cannot oversubscribe, with the sizes involved and a pointer at PARAFAC2_BACKEND=cpu.

Source code in parafac2/backend.py
def ensure_device_capacity(nbytes: int, what: str = "matrix") -> bool:
    """Install the managed-memory allocator if ``nbytes`` will not fit.

    Raises
    ------
    MemoryError
        If the transfer does not fit and the device cannot oversubscribe, with
        the sizes involved and a pointer at ``PARAFAC2_BACKEND=cpu``.
    """
    global _managed_allocator_installed
    import cupy as cp  # ty: ignore[unresolved-import]

    if _managed_allocator_installed:
        return True

    free, total = cp.cuda.Device().mem_info
    if nbytes <= free * DEVICE_MEMORY_HEADROOM:
        return False

    if not _managed_memory_supported():
        raise MemoryError(
            f"The {what} needs {nbytes / 1e9:.1f} GB on the device but only "
            f"{free / 1e9:.1f} GB of {total / 1e9:.1f} GB is free, and this "
            "device cannot oversubscribe its memory (managed memory "
            "unsupported). Run on the CPU instead, either with "
            f"backend='cpu' or {BACKEND_ENV_VAR}=cpu."
        )

    cp.cuda.set_allocator(cp.cuda.MemoryPool(cp.cuda.malloc_managed).malloc)
    _managed_allocator_installed = True
    return True

get_backend(backend=None)

Return the requested backend, or auto-detect the first available one.

Parameters:

Name Type Description Default
backend str

One of 'mlx', 'cupy', or 'cpu'. None consults PARAFAC2_BACKEND and then auto-detects.

None

Returns:

Type Description
str

The resolved backend name: 'mlx', 'cupy', or 'cpu'.

Source code in parafac2/backend.py
def get_backend(backend: str | None = None) -> str:
    """Return the requested backend, or auto-detect the first available one.

    Parameters
    ----------
    backend : str, optional
        One of ``'mlx'``, ``'cupy'``, or ``'cpu'``. ``None`` consults
        ``PARAFAC2_BACKEND`` and then auto-detects.

    Returns
    -------
    str
        The resolved backend name: ``'mlx'``, ``'cupy'``, or ``'cpu'``.
    """
    if backend is None:
        backend = os.environ.get(BACKEND_ENV_VAR) or None
        source = f"{BACKEND_ENV_VAR}="
    else:
        source = "backend="

    if backend is not None:
        backend_lower = backend.strip().lower()
        if backend_lower in _VALID_BACKENDS:
            return backend_lower
        raise ValueError(
            f"Unknown backend '{backend}' (from {source}{backend!r}). "
            f"Supported backends: 'mlx', 'cupy', 'cpu'."
        )

    if _cuda_is_usable():
        return "cupy"

    try:
        import mlx.core  # noqa: F401  # ty: ignore[unresolved-import]

        return "mlx"
    except ImportError:
        pass

    return "cpu"

mkl_dot()

Return sparse_dot_mkl.dot_product_mkl if importable, else None.

SciPy's sparse-times-dense kernels are single-threaded, which dominates the PARAFAC2 fit on large datasets. When the optional sparse-dot-mkl package is installed (pip install 'parafac2[mkl]') its multithreaded MKL kernels are used instead. The lookup is cached in the module-level _MKL_DOT global.

Source code in parafac2/backend.py
def mkl_dot() -> Any:
    """Return ``sparse_dot_mkl.dot_product_mkl`` if importable, else ``None``.

    SciPy's sparse-times-dense kernels are single-threaded, which dominates
    the PARAFAC2 fit on large datasets. When the optional ``sparse-dot-mkl``
    package is installed (``pip install 'parafac2[mkl]'``) its multithreaded
    MKL kernels are used instead. The lookup is cached in the module-level
    ``_MKL_DOT`` global.
    """
    global _MKL_DOT
    if _MKL_DOT is False:
        try:
            from sparse_dot_mkl import (  # ty: ignore[unresolved-import]
                dot_product_mkl,
            )

            _MKL_DOT = dot_product_mkl
        except ImportError:
            _MKL_DOT = None
    return _MKL_DOT

mlx_csr_matmul(device_mat, rhs, shape)

Compute device_mat @ rhs via the MLX CSR sparse-matmul kernel.

Parameters:

Name Type Description Default
device_mat tuple[Any, Any, Any]

The (data, indices, indptr) MLX arrays from :func:to_mlx_csr.

required
rhs ndarray

The right-hand operand (1-D or 2-D NumPy array).

required
shape tuple[int, int]

The logical (rows, cols) shape of the sparse matrix.

required
Source code in parafac2/backend.py
def mlx_csr_matmul(
    device_mat: tuple[Any, Any, Any], rhs: np.ndarray, shape: tuple[int, int]
) -> np.ndarray:
    """Compute ``device_mat @ rhs`` via the MLX CSR sparse-matmul kernel.

    Parameters
    ----------
    device_mat : tuple[Any, Any, Any]
        The ``(data, indices, indptr)`` MLX arrays from :func:`to_mlx_csr`.
    rhs : np.ndarray
        The right-hand operand (1-D or 2-D NumPy array).
    shape : tuple[int, int]
        The logical ``(rows, cols)`` shape of the sparse matrix.
    """
    import mlx.core as mx  # ty: ignore[unresolved-import]

    M, _N = shape
    mx_data, mx_indices, mx_indptr = device_mat
    rhs_2d = rhs[:, None] if rhs.ndim == 1 else rhs
    K = rhs_2d.shape[1]

    mx_rhs = mx.array(rhs_2d.astype(np.float32, copy=False))
    out = _get_mlx_csr_spmm_kernel()(
        inputs=[mx_data, mx_indices, mx_indptr, mx_rhs],
        template=[("T", mx.float32), ("Idx", mx.int32), ("M", M), ("K", K)],
        grid=(M, K, 1),
        threadgroup=(min(M, 16), min(K, 16), 1),
        output_shapes=[(M, K)],
        output_dtypes=[mx.float32],
    )
    return _mlx_to_numpy(out[0], rhs.ndim == 1)

mlx_csr_rmatmul(lhs, device_mat, shape)

Compute lhs @ device_mat via the atomic MLX CSR sparse-matmul kernel.

Parameters:

Name Type Description Default
lhs ndarray

The left-hand operand (1-D or 2-D NumPy array).

required
device_mat tuple[Any, Any, Any]

The (data, indices, indptr) MLX arrays from :func:to_mlx_csr.

required
shape tuple[int, int]

The logical (rows, cols) shape of the sparse matrix.

required
Source code in parafac2/backend.py
def mlx_csr_rmatmul(
    lhs: np.ndarray, device_mat: tuple[Any, Any, Any], shape: tuple[int, int]
) -> np.ndarray:
    """Compute ``lhs @ device_mat`` via the atomic MLX CSR sparse-matmul kernel.

    Parameters
    ----------
    lhs : np.ndarray
        The left-hand operand (1-D or 2-D NumPy array).
    device_mat : tuple[Any, Any, Any]
        The ``(data, indices, indptr)`` MLX arrays from :func:`to_mlx_csr`.
    shape : tuple[int, int]
        The logical ``(rows, cols)`` shape of the sparse matrix.
    """
    import mlx.core as mx  # ty: ignore[unresolved-import]

    M, N = shape
    mx_data, mx_indices, mx_indptr = device_mat
    lhs_2d = lhs[None, :] if lhs.ndim == 1 else lhs
    K = lhs_2d.shape[0]

    mx_lhs = mx.array(lhs_2d.astype(np.float32, copy=False))
    out = _get_mlx_csr_atomic_rspmm_kernel()(
        inputs=[mx_lhs, mx_data, mx_indices, mx_indptr],
        template=[
            ("T", mx.float32),
            ("Idx", mx.int32),
            ("K", K),
            ("M", M),
            ("N", N),
        ],
        grid=(K, M, 1),
        threadgroup=(min(K, 16), min(M, 16), 1),
        output_shapes=[(K, N)],
        output_dtypes=[mx.float32],
        init_value=0.0,
    )
    return _mlx_to_numpy(out[0], lhs.ndim == 1)

mlx_dense_matmul(device_mat, rhs, shape)

Compute device_mat @ rhs for a dense MLX-resident matrix.

Source code in parafac2/backend.py
def mlx_dense_matmul(
    device_mat: Any, rhs: np.ndarray, shape: tuple[int, int]
) -> np.ndarray:
    """Compute ``device_mat @ rhs`` for a dense MLX-resident matrix."""
    import mlx.core as mx  # ty: ignore[unresolved-import]

    return _mlx_to_numpy(device_mat @ mx.array(rhs), rhs.ndim == 1)

mlx_dense_rmatmul(lhs, device_mat, shape)

Compute lhs @ device_mat for a dense MLX-resident matrix.

Source code in parafac2/backend.py
def mlx_dense_rmatmul(
    lhs: np.ndarray, device_mat: Any, shape: tuple[int, int]
) -> np.ndarray:
    """Compute ``lhs @ device_mat`` for a dense MLX-resident matrix."""
    import mlx.core as mx  # ty: ignore[unresolved-import]

    return _mlx_to_numpy(mx.array(lhs) @ device_mat, lhs.ndim == 1)

to_cupy_csr(mat_csr)

Move a SciPy CSR array onto the CuPy device.

Switches to managed memory first when the matrix is larger than free device memory, so a dataset bigger than the card is paged rather than refused.

Source code in parafac2/backend.py
def to_cupy_csr(mat_csr: Any) -> Any:
    """Move a SciPy CSR array onto the CuPy device.

    Switches to managed memory first when the matrix is larger than free
    device memory, so a dataset bigger than the card is paged rather than
    refused.
    """
    import cupy as cp  # ty: ignore[unresolved-import]
    import cupyx.scipy.sparse as cpsparse  # ty: ignore[unresolved-import]

    ensure_device_capacity(csr_device_bytes(mat_csr), what="data matrix")

    return cpsparse.csr_matrix(
        (
            cp.asarray(mat_csr.data),
            cp.asarray(mat_csr.indices),
            cp.asarray(mat_csr.indptr),
        ),
        shape=mat_csr.shape,
    )

to_cupy_dense(mat)

Move a dense matrix onto the CuPy device.

Source code in parafac2/backend.py
def to_cupy_dense(mat: np.ndarray) -> Any:
    """Move a dense matrix onto the CuPy device."""
    import cupy as cp  # ty: ignore[unresolved-import]

    ensure_device_capacity(int(mat.nbytes), what="data matrix")
    return cp.asarray(mat)

to_mlx_csr(mat_csr)

Move a SciPy CSR array's components onto the MLX device.

Parameters:

Name Type Description Default
mat_csr csr_array

The sparse matrix to transfer.

required

Returns:

Type Description
tuple[Any, Any, Any]

The (data, indices, indptr) MLX arrays backing the CSR matrix.

Source code in parafac2/backend.py
def to_mlx_csr(mat_csr: Any) -> tuple[Any, Any, Any]:
    """Move a SciPy CSR array's components onto the MLX device.

    Parameters
    ----------
    mat_csr : csr_array
        The sparse matrix to transfer.

    Returns
    -------
    tuple[Any, Any, Any]
        The ``(data, indices, indptr)`` MLX arrays backing the CSR matrix.
    """
    import mlx.core as mx  # ty: ignore[unresolved-import]

    mx_data = mx.array(mat_csr.data.astype(np.float32, copy=False))
    mx_indices = mx.array(mat_csr.indices.astype(np.int32, copy=False))
    mx_indptr = mx.array(mat_csr.indptr.astype(np.int32, copy=False))
    return mx_data, mx_indices, mx_indptr

to_mlx_dense(mat)

Move a dense matrix onto the MLX device.

Source code in parafac2/backend.py
def to_mlx_dense(mat: np.ndarray) -> Any:
    """Move a dense matrix onto the MLX device."""
    import mlx.core as mx  # ty: ignore[unresolved-import]

    return mx.array(mat)