# Copyright Contributors to the Cellarium project.
# SPDX-License-Identifier: BSD-3-Clause
from collections.abc import Sequence
from typing import ClassVar
import torch
from torch.distributions import Binomial
from .base import CellariumTransform, Stage
from .randomize import Randomize
[docs]
class BinomialResample(CellariumTransform):
"""
Binomial resampling of gene counts.
For each count, the parameter to the binomial distribution
is independently and uniformly sampled according to the
bounding parameters, yielding the parameter matrix p_ng.
.. math::
y_{ng} = Binomial(n=x_{ng}, p=p_{ng})
If ``total_mrna_umis_n`` is given, it is reduced by the counts that the resampling removed,
so that it remains consistent with the resampled gene counts. Only the counts of the genes in
``x_ng`` change, so counts of genes that are not in ``x_ng`` stay in the total.
By default the transform is active only in the ``"train"`` stage of a
:class:`~cellarium.ml.core.CellariumPipeline`.
Args:
p_binom_min:
Lower bound on binomial distribution parameter.
p_binom_max:
Upper bound on binomial distribution parameter.
p_apply:
Probability of applying transform to each sample.
stages:
The stages in which the transform is active. If ``None`` (default), it is active only in
``"train"``. Otherwise this replaces that default.
"""
default_stages: ClassVar[frozenset[Stage]] = frozenset({"train"})
def __init__(
self,
p_binom_min: float,
p_binom_max: float,
p_apply: float,
stages: Sequence[Stage] | None = None,
):
super().__init__(stages)
self.p_binom_min = p_binom_min
self.p_binom_max = p_binom_max
self.randomize = Randomize(p_apply)
[docs]
def forward(self, x_ng: torch.Tensor, total_mrna_umis_n: torch.Tensor | None = None) -> dict[str, torch.Tensor]:
"""
Args:
x_ng: Gene counts.
total_mrna_umis_n: Total mRNA UMIs per cell (optional).
Returns:
Binomially resampled gene counts, and, if ``total_mrna_umis_n`` was given,
the total mRNA UMIs per cell reduced by the removed counts.
"""
p_binom_ng = torch.empty_like(x_ng).uniform_(self.p_binom_min, self.p_binom_max)
x_aug = Binomial(total_count=x_ng, probs=p_binom_ng).sample()
y_ng = self.randomize(x_aug, x_ng)
output = {"x_ng": y_ng}
if total_mrna_umis_n is not None:
removed_n = (x_ng - y_ng).sum(dim=-1)
output["total_mrna_umis_n"] = total_mrna_umis_n - removed_n.to(total_mrna_umis_n.dtype)
return output