Source code for cellarium.ml.transforms.dropout

# Copyright Contributors to the Cellarium project.
# SPDX-License-Identifier: BSD-3-Clause


from collections.abc import Sequence
from typing import ClassVar

import torch

from .base import CellariumTransform, Stage
from .randomize import Randomize


[docs] class Dropout(CellariumTransform): """ Applies random dropout to gene counts. For each count, the dropout parameter is independently and uniformly sampled according to the bounding parameters, yielding the parameter matrix p_ng. .. math:: y_{ng} = x_{ng} * (1 - Bernoulli(p_ng)) If ``total_mrna_umis_n`` is given, it is reduced by the counts that the dropout removed, so that it remains consistent with the 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_dropout_min: Lower bound on dropout parameter. p_dropout_max: Upper bound on dropout 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_dropout_min, p_dropout_max, p_apply, stages: Sequence[Stage] | None = None, ): super().__init__(stages) self.p_dropout_min = p_dropout_min self.p_dropout_max = p_dropout_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: Gene counts with random dropout, and, if ``total_mrna_umis_n`` was given, the total mRNA UMIs per cell reduced by the removed counts. """ p_dropout_ng = torch.empty_like(x_ng).uniform_(self.p_dropout_min, self.p_dropout_max) x_aug = torch.where(torch.bernoulli(p_dropout_ng).bool(), 0, x_ng) 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