Skip to content

zero_inflated_negbin

ZeroInflatedNegBin

Bases: Marginal

Zero-inflated negative-binomial marginal estimator

Feature j's zero inflation probability is pi_j(x). If not zero-ed, the draw is NB(mu_j(x), r_j(x)). The 'mean' formula models the marginal mean λ_j(x) = (1−π_j)μ_j. During likelihood calculation, μ_j is set to λ_j/(1−π_j).

The allowed formula keys are 'mean', 'dispersion', and 'zero_inflation'.

Examples:

>>> from scdesigner.distributions import ZeroInflatedNegBin
>>> import scdesigner.datasets
>>>
>>> pancreas = scdesigner.datasets.pancreas()
>>>
>>> sim = ZeroInflatedNegBin(formula={"mean": "~ pseudotime", "dispersion": "~ 1", "zero_inflation": "~ pseudotime"})
>>> sim.setup_data(pancreas)
>>> sim.fit(max_epochs=1, verbose=False)
>>>
>>> # evaluate p(y | x) and model parameters
>>> 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/zero_inflated_negbin.py
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 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 ZeroInflatedNegBin(Marginal):
    """Zero-inflated negative-binomial marginal estimator

    Feature j's zero inflation probability is `pi_j(x)`.  If not zero-ed, the
    draw is NB(mu_j(x), r_j(x)). The 'mean' formula models the marginal mean
    λ_j(x) = (1−π_j)μ_j. During likelihood calculation, μ_j is set to
    λ_j/(1−π_j).

    The allowed formula keys are 'mean', 'dispersion', and 'zero_inflation'.

    Examples
    --------
    >>> from scdesigner.distributions import ZeroInflatedNegBin
    >>> import scdesigner.datasets
    >>>
    >>> pancreas = scdesigner.datasets.pancreas()
    >>>
    >>> sim = ZeroInflatedNegBin(formula={"mean": "~ pseudotime", "dispersion": "~ 1", "zero_inflation": "~ pseudotime"})
    >>> sim.setup_data(pancreas)
    >>> sim.fit(max_epochs=1, verbose=False)
    >>>
    >>> # evaluate p(y | x) and model parameters
    >>> 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', 'zero_inflation'])
        super().__init__(formula, **kwargs)

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

        link_funs = {
            "mean": torch.exp,
            "dispersion": torch.exp,
            "zero_inflation": torch.sigmoid,
        }
        def nll(batch):
            return -self.likelihood(batch).sum()
        self.predict = GLMPredictor(
            n_outcomes=self.n_outcomes,
            feature_dims=self.feature_dims,
            link_fns=link_funs,
            loss_fn=nll,
            optimizer_class=optimizer_class,
            optimizer_kwargs=optimizer_kwargs,
            device=self.device,
        )

    def _initialize_parameters(self, **kwargs):
        beta, gamma = initialize_parameters(
            self.train_loader,
            self.n_outcomes,
            self.feature_dims["mean"],
            self.feature_dims["dispersion"],
        )
        self.predict.coefs["mean"].data.copy_(beta)
        self.predict.coefs["dispersion"].data.copy_(gamma)

        logit_pi = _initialize_zi_intercept_nb(
            self.train_loader, beta, gamma, self.n_outcomes
        )
        self.predict.coefs["zero_inflation"].data[0].copy_(logit_pi)

    def likelihood(self, batch) -> torch.Tensor:
        """Compute the negative log-likelihood"""
        y, x = batch
        params = self.predict(x)
        lam = params.get("mean")
        r = params.get("dispersion")
        pi = params.get("zero_inflation")
        mu = _lam_to_mu(lam, pi)

        # negative binomial component
        negbin_loglikelihood = (
            torch.lgamma(y + r)
            - torch.lgamma(r)
            - torch.lgamma(y + 1)
            + r * torch.log(r)
            + y * torch.log(mu)
            - (r + y) * torch.log(r + mu)
        )

        # return the mixture, with an offset to prevent log(0)
        return torch.log(pi * (y == 0) + (1 - pi) * torch.exp(negbin_loglikelihood) + 1e-10)

    def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
        """Invert pseudoobservations."""
        mu, r, pi, u = self._local_params(x, u)
        conditional_u = np.where(u > pi, (u - pi) / (1 - pi + 1e-10), 0.0)
        y = nbinom(n=r, p=r / (r + mu)).ppf(conditional_u)
        delta = (u > pi).astype(float)
        return torch.from_numpy(y * delta).float()

    def uniformize(self, y: torch.Tensor, x: Dict[str, torch.Tensor], epsilon=1e-6) -> torch.Tensor:
        """Return uniformized pseudo-observations for counts y given covariates x."""
        # cdf values using scipy's parameterization
        mu, r, pi, y = self._local_params(x, y)
        nb_distn = nbinom(n=r, p=r / (r + mu))
        u1 = pi + (1 - pi) * nb_distn.cdf(y)
        u2 = np.where(y > 0, pi + (1 - pi) * nb_distn.cdf(y-1), 0)

        # randomize within discrete mass to get uniform(0,1)
        v = np.random.uniform(size=y.shape)
        u = np.clip(v * u1 + (1 - v) * u2, epsilon, 1 - epsilon)
        return torch.from_numpy(u).float()

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

invert(u, x)

Invert pseudoobservations.

Source code in scdesigner/src/scdesigner/distributions/zero_inflated_negbin.py
107
108
109
110
111
112
113
def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
    """Invert pseudoobservations."""
    mu, r, pi, u = self._local_params(x, u)
    conditional_u = np.where(u > pi, (u - pi) / (1 - pi + 1e-10), 0.0)
    y = nbinom(n=r, p=r / (r + mu)).ppf(conditional_u)
    delta = (u > pi).astype(float)
    return torch.from_numpy(y * delta).float()

likelihood(batch)

Compute the negative log-likelihood

Source code in scdesigner/src/scdesigner/distributions/zero_inflated_negbin.py
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def likelihood(self, batch) -> torch.Tensor:
    """Compute the negative log-likelihood"""
    y, x = batch
    params = self.predict(x)
    lam = params.get("mean")
    r = params.get("dispersion")
    pi = params.get("zero_inflation")
    mu = _lam_to_mu(lam, pi)

    # negative binomial component
    negbin_loglikelihood = (
        torch.lgamma(y + r)
        - torch.lgamma(r)
        - torch.lgamma(y + 1)
        + r * torch.log(r)
        + y * torch.log(mu)
        - (r + y) * torch.log(r + mu)
    )

    # return the mixture, with an offset to prevent log(0)
    return torch.log(pi * (y == 0) + (1 - pi) * torch.exp(negbin_loglikelihood) + 1e-10)

uniformize(y, x, epsilon=1e-06)

Return uniformized pseudo-observations for counts y given covariates x.

Source code in scdesigner/src/scdesigner/distributions/zero_inflated_negbin.py
115
116
117
118
119
120
121
122
123
124
125
126
def uniformize(self, y: torch.Tensor, x: Dict[str, torch.Tensor], epsilon=1e-6) -> torch.Tensor:
    """Return uniformized pseudo-observations for counts y given covariates x."""
    # cdf values using scipy's parameterization
    mu, r, pi, y = self._local_params(x, y)
    nb_distn = nbinom(n=r, p=r / (r + mu))
    u1 = pi + (1 - pi) * nb_distn.cdf(y)
    u2 = np.where(y > 0, pi + (1 - pi) * nb_distn.cdf(y-1), 0)

    # randomize within discrete mass to get uniform(0,1)
    v = np.random.uniform(size=y.shape)
    u = np.clip(v * u1 + (1 - v) * u2, epsilon, 1 - epsilon)
    return torch.from_numpy(u).float()