Skip to content

negbin

NegBin

Bases: Marginal

Negative-binomial marginal estimator with poisson initialization

This subclass behaves like Marginal but assumes each gene follows a negative binomial distribution NB(mu_j(x), r_j(x)) parameterized via a mean mu_j(x) and dispersion r_j(x) that depend on covariates x through the provided formula object.

The allowed formula keys are 'mean' and 'dispersion', defaulting to 'mean' with a fixed dispersion if only a string formula is passed in.

Examples:

>>> from scdesigner.distributions import NegBin
>>> import scdesigner.datasets
>>>
>>> pancreas = scdesigner.datasets.pancreas()
>>>
>>> sim = NegBin(formula={"mean": "~ bs(pseudotime, df=5)", "dispersion": "~ pseudotime"})
>>> sim.setup_data(pancreas)
>>> sim.fit(max_epochs=1, verbose=False)
>>>
>>> # evaluate p(y | x) and mu(x)
>>> y, x = next(iter(sim.loader))
>>> l = sim.likelihood((y, x))
>>> y_hat = sim.predict(x)
>>>
>>> # convert to quantiles and back
>>> u = sim.uniformize(y, x)
>>> x_star = sim.invert(u, x)
Source code in scdesigner/src/scdesigner/distributions/negbin.py
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
class NegBin(Marginal):
    """Negative-binomial marginal estimator with poisson initialization

    This subclass behaves like `Marginal` but assumes each gene follows a
    negative binomial distribution NB(mu_j(x), r_j(x)) parameterized via a mean
    `mu_j(x)` and dispersion `r_j(x)` that depend on covariates `x` through the
    provided `formula` object.

    The allowed formula keys are 'mean' and 'dispersion', defaulting to
    'mean' with a fixed dispersion if only a string formula is passed in.

    Examples
    --------
    >>> from scdesigner.distributions import NegBin
    >>> import scdesigner.datasets
    >>>
    >>> pancreas = scdesigner.datasets.pancreas()
    >>>
    >>> sim = NegBin(formula={"mean": "~ bs(pseudotime, df=5)", "dispersion": "~ pseudotime"})
    >>> sim.setup_data(pancreas)
    >>> sim.fit(max_epochs=1, verbose=False)
    >>>
    >>> # evaluate p(y | x) and mu(x)
    >>> y, x = next(iter(sim.loader))
    >>> l = sim.likelihood((y, x))
    >>> y_hat = sim.predict(x)
    >>>
    >>> # convert to quantiles and back
    >>> u = sim.uniformize(y, x)
    >>> x_star = sim.invert(u, x)
    """
    def __init__(self, formula: Union[Dict, str], **kwargs):
        formula = standardize_formula(formula, allowed_keys=['mean', 'dispersion'])
        super().__init__(formula, **kwargs)

    def setup_optimizer(
            self,
            optimizer_class: Optional[callable] = torch.optim.AdamW,
            **optimizer_kwargs,
    ):
        if self.loader is None:
            raise RuntimeError("self.loader is not set (call setup_data first)")

        def nll(batch):
            return -self.likelihood(batch).sum()
        self.predict = GLMPredictor(
            n_outcomes=self.n_outcomes,
            feature_dims=self.feature_dims,
            loss_fn=nll,
            optimizer_class=optimizer_class,
            optimizer_kwargs=optimizer_kwargs,
            device=self.device
        )

    def likelihood(self, batch) -> torch.Tensor:
        """Compute the log-likelihood"""
        y, x = batch
        params = self.predict(x)
        return nb_loglik(y, params.get('mean'), params.get('dispersion'))

    def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor],
               r_min: float = 1e-3, r_max: float = 1e3, mu_min: float = 1e-5,
               mu_max: float = 1e4) -> torch.Tensor:
        mu, r, u = self._local_params(x, u)
        r = np.clip(r, r_min, r_max)
        mu = np.clip(mu, mu_min, mu_max)

        p = r / (r + mu)
        y = nbinom(n=r, p=p).ppf(u)
        return torch.from_numpy(y).float()

    def uniformize(self, y: torch.Tensor, x: Dict[str, torch.Tensor],
                   epsilon: float =1e-6, r_min: float = 1e-3, r_max: float = 1e3,
                   mu_min: float = 1e-5, mu_max: float = 1e5) -> torch.Tensor:
        # extractl ocal parameters
        mu, r, y = self._local_params(x, y)
        r = np.clip(r, r_min, r_max)
        mu = np.clip(mu, mu_min, mu_max)
        p = r / (r + mu)

        # generate associated quantiles
        u1 = nbinom(n=r, p=p).cdf(y)
        u2 = np.where(y > 0, nbinom(n=r, p=p).cdf(y - 1), 0.0)
        v = np.random.uniform(size=y.shape)
        u = np.clip(v * u1 + (1.0 - v) * u2, epsilon, 1.0 - epsilon)
        return torch.from_numpy(u).float()

    def _local_params(self, x, y=None) -> Tuple:
        params = self.predict(x)
        mu = params.get('mean')
        r = params.get('dispersion')
        if y is None:
            return _to_numpy(mu, r)
        return _to_numpy(mu, r, y)

    def _initialize_parameters(self, **kwargs):
        initialize_kwargs = _filter_kwargs(kwargs, DEFAULT_ALLOWED_KWARGS['initialize'])
        if any(spec.penalty.lam > 0 for spec in self.penalties):
            # We don't use poisson IRLS for regularized models (since that
            # initialization behaves poorly in high dimensions)
            initialize_kwargs.setdefault('max_iter', 0)
        beta_init, gamma_init = initialize_parameters(
            self.train_loader, self.n_outcomes, self.feature_dims['mean'],
            self.feature_dims['dispersion'],
            **initialize_kwargs
        )
        with torch.no_grad():
            self.predict.coefs['mean'].copy_(beta_init)
            self.predict.coefs['dispersion'].copy_(gamma_init)

likelihood(batch)

Compute the log-likelihood

Source code in scdesigner/src/scdesigner/distributions/negbin.py
82
83
84
85
86
def likelihood(self, batch) -> torch.Tensor:
    """Compute the log-likelihood"""
    y, x = batch
    params = self.predict(x)
    return nb_loglik(y, params.get('mean'), params.get('dispersion'))

nb_loglik(y, mu, r)

Negative-binomial log likelihood.

This is a negative binomial density using the mean-size parameterization: Var(y) = mu + mu^2 / r

Source code in scdesigner/src/scdesigner/distributions/negbin.py
12
13
14
15
16
17
18
19
20
21
22
23
24
25
def nb_loglik(y: torch.Tensor, mu: torch.Tensor, r: torch.Tensor) -> torch.Tensor:
    """Negative-binomial log likelihood.

    This is a negative binomial density using the mean-size parameterization:
    Var(y) = mu + mu^2 / r
    """
    return (
        torch.lgamma(y + r)
        - torch.lgamma(r)
        - torch.lgamma(y + 1.0)
        + r * torch.log(r)
        + y * torch.log(mu)
        - (r + y) * torch.log(r + mu)
    )