# Copyright Contributors to the Cellarium project.
# SPDX-License-Identifier: BSD-3-Clause
from collections.abc import Callable
import numpy as np
import scipy.sparse
import torch
from torch import nn
from cellarium.ml.utilities.data import sparse_tensor_to_scipy_csr, to_torch_sparse_coo, to_torch_sparse_csr
from cellarium.ml.utilities.testing import (
assert_nonnegative,
assert_positive,
)
[docs]
class NormalizeTotal(nn.Module):
"""
Normalize total gene counts per cell to target count.
.. math::
\\mathrm{total\\_mrna\\_umis}_n = \\sum_{g=1}^G x_{ng}
y_{ng} = \\frac{\\mathrm{target\\_count} \\times x_{ng}}{\\mathrm{total\\_mrna\\_umis}_n + \\mathrm{eps}}
Args:
target_count:
Target gene epxression count.
eps:
A value added to the denominator for numerical stability.
"""
def __init__(
self,
target_count: int = 10_000,
eps: float = 1e-6,
) -> None:
super().__init__()
assert_positive("target_count", target_count)
self.target_count = target_count
assert_nonnegative("eps", eps)
self.eps = eps
[docs]
def forward(
self,
x_ng: torch.Tensor | scipy.sparse.spmatrix,
total_mrna_umis_n: torch.Tensor | None = None,
) -> dict[str, torch.Tensor]:
"""
.. note::
When used with :class:`~cellarium.ml.core.CellariumModule` or :class:`~cellarium.ml.core.CellariumPipeline`,
``x_ng`` key in the input dictionary will be overwritten with the normalized values.
When ``x_ng`` is a :class:`scipy.sparse.spmatrix`, a CPU :class:`torch.sparse_csr_tensor` or a CPU
:class:`torch.sparse_coo_tensor` (the layouts a dataloader produces, see
:func:`~cellarium.ml.utilities.data.to_torch_sparse_csr`), so that this transform can be the first
``cpu_transform`` (before a :class:`~cellarium.ml.transforms.Filter`), the normalization is done with
scipy (torch cannot reduce or broadcast over a sparse CSR tensor) and the result is returned in the
same torch sparse layout it arrived in (CSR stays CSR, COO stays COO; scipy input becomes CSR). The
input is not modified.
Args:
x_ng:
Gene counts. A dense :class:`torch.Tensor`, a scipy sparse matrix, or a CPU sparse CSR or COO
:class:`torch.Tensor`.
total_mrna_umis_n:
Total mRNA UMI counts per cell. If ``None``, it is computed from ``x_ng``.
Returns:
A dictionary with the following keys:
- ``x_ng``: The gene counts normalized to target count.
"""
if scipy.sparse.issparse(x_ng):
return self._forward_sparse(
scipy.sparse.csr_matrix(x_ng), total_mrna_umis_n, to_torch_sparse_fn=to_torch_sparse_csr
)
if isinstance(x_ng, torch.Tensor) and x_ng.layout in (torch.sparse_csr, torch.sparse_coo):
to_torch_sparse_fn = to_torch_sparse_csr if x_ng.layout == torch.sparse_csr else to_torch_sparse_coo
return self._forward_sparse(
sparse_tensor_to_scipy_csr(x_ng), total_mrna_umis_n, to_torch_sparse_fn=to_torch_sparse_fn
)
if total_mrna_umis_n is None:
total_mrna_umis_n = x_ng.sum(dim=-1)
x_ng = self.target_count * x_ng / (total_mrna_umis_n[:, None].float() + self.eps)
return {"x_ng": x_ng}
def _forward_sparse(
self,
x_ng: scipy.sparse.csr_matrix,
total_mrna_umis_n: torch.Tensor | None,
to_torch_sparse_fn: Callable[[scipy.sparse.spmatrix], torch.Tensor],
) -> dict[str, torch.Tensor]:
"""Sparse-input path for :meth:`forward`, with the same arithmetic as the dense path (in float32)."""
data = x_ng.data.astype(np.float32, copy=False)
if total_mrna_umis_n is None:
total_n = np.asarray(x_ng.sum(axis=1), dtype=np.float32).ravel()
else:
total_n = total_mrna_umis_n.detach().cpu().numpy().astype(np.float32, copy=False)
denominator_n = total_n + np.float32(self.eps)
normalized_data = self.target_count * data / np.repeat(denominator_n, np.diff(x_ng.indptr))
normalized = scipy.sparse.csr_matrix((normalized_data, x_ng.indices, x_ng.indptr), shape=x_ng.shape)
return {"x_ng": to_torch_sparse_fn(normalized)}
def __repr__(self) -> str:
return f"{self.__class__.__name__}(target_count={self.target_count}, eps={self.eps})"