Skip to content

Index

Marginal distribution implementations.

Bernoulli

Bases: Marginal

Bernoulli marginal estimator

This subclass behaves like Marginal but assumes each feature follows a Bernoulli distribution with success probability theta_j(x) that depends on covariates x through the formula argument.

The allowed formula keys are 'mean' (interpreted as the logit of the success probability when used with a GLM link). If a string formula is provided, it is taken to specify the mean model.

Examples:

>>> from scdesigner.distributions import Bernoulli
>>> import scdesigner.datasets
>>>
>>> pancreas = scdesigner.datasets.pancreas()
>>>
>>> sim = Bernoulli(formula="~ pseudotime")
>>> sim.setup_data(pancreas)
>>> sim.fit(max_epochs=1, verbose=False)
>>>
>>> # evaluate p(y | x) and theta(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/bernoulli.py
 9
10
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
class Bernoulli(Marginal):
    """Bernoulli marginal estimator

    This subclass behaves like `Marginal` but assumes each feature follows a
    Bernoulli distribution with success probability `theta_j(x)` that depends
    on covariates `x` through the `formula` argument.

    The allowed formula keys are 'mean' (interpreted as the logit of the
    success probability when used with a GLM link). If a string formula is
    provided, it is taken to specify the `mean` model.

    Examples
    --------
    >>> from scdesigner.distributions import Bernoulli
    >>> import scdesigner.datasets
    >>>
    >>> pancreas = scdesigner.datasets.pancreas()
    >>>
    >>> sim = Bernoulli(formula="~ pseudotime")
    >>> sim.setup_data(pancreas)
    >>> sim.fit(max_epochs=1, verbose=False)
    >>>
    >>> # evaluate p(y | x) and theta(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'])
        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_fns = {"mean": 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_fns,
            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)
        theta = params.get("mean")
        return y * torch.log(theta) + (1 - y) * torch.log(1 - theta)

    def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
        """Invert pseudoobservations."""
        theta, u = self._local_params(x, u)
        y = bernoulli(theta).ppf(u)
        return torch.from_numpy(y).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."""
        theta, y = self._local_params(x, y)
        u1 =  bernoulli(theta).cdf(y)
        u2 = np.where(y > 0,  bernoulli(theta).cdf(y - 1), 0)
        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)
        theta = params.get('mean')
        if y is None:
            return _to_numpy(theta)
        return _to_numpy(theta, y)

invert(u, x)

Invert pseudoobservations.

Source code in scdesigner/src/scdesigner/distributions/bernoulli.py
72
73
74
75
76
def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
    """Invert pseudoobservations."""
    theta, u = self._local_params(x, u)
    y = bernoulli(theta).ppf(u)
    return torch.from_numpy(y).float()

likelihood(batch)

Compute the log-likelihood

Source code in scdesigner/src/scdesigner/distributions/bernoulli.py
65
66
67
68
69
70
def likelihood(self, batch) -> torch.Tensor:
    """Compute the log-likelihood"""
    y, x = batch
    params = self.predict(x)
    theta = params.get("mean")
    return y * torch.log(theta) + (1 - y) * torch.log(1 - theta)

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

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

Source code in scdesigner/src/scdesigner/distributions/bernoulli.py
78
79
80
81
82
83
84
85
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."""
    theta, y = self._local_params(x, y)
    u1 =  bernoulli(theta).cdf(y)
    u2 = np.where(y > 0,  bernoulli(theta).cdf(y - 1), 0)
    v = np.random.uniform(size=y.shape)
    u = np.clip(v * u1 + (1 - v) * u2, epsilon, 1 - epsilon)
    return torch.from_numpy(u).float()

Gaussian

Bases: Marginal

Gaussian marginal estimator

This subclass behaves like Marginal but assuming that each gene follows a normal N(muj, sigma[j]^2(x)) distribution. The parameters muj and sigma[j]^2(x) depend on experimental or biological features x through the formula object.

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

Examples:

>>> from scdesigner.distributions import Gaussian
>>> import scdesigner.datasets
>>>
>>> pancreas = scdesigner.datasets.pancreas()
>>>
>>> sim = Gaussian(formula={"mean": "~ bs(pseudotime, df=5)", "sdev": "~ 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/gaussian.py
  9
 10
 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
class Gaussian(Marginal):
    """Gaussian marginal estimator

    This subclass behaves like `Marginal` but assuming that each gene follows a
    normal N(mu[j](x), sigma[j]^2(x)) distribution. The parameters mu[j](x) and
    sigma[j]^2(x) depend on experimental or biological features x through the
    formula object.

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

    Examples
    --------
    >>> from scdesigner.distributions import Gaussian
    >>> import scdesigner.datasets
    >>>
    >>> pancreas = scdesigner.datasets.pancreas()
    >>>
    >>> sim = Gaussian(formula={"mean": "~ bs(pseudotime, df=5)", "sdev": "~ 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', 'sdev'])
        super().__init__(formula, **kwargs)

    def setup_optimizer(
            self,
            optimizer_class: Optional[callable] = torch.optim.Adam,
            **optimizer_kwargs,
    ):
        """
        Gaussian Model Optimizer

        By default optimization is done using Adam. This can be customized using
        the `optimizer_class` argument. The link function for the mean is an
        identity link.

        Parameters
        ----------
        optimizer_class : Optional[callable]
            We optimize the negative log likelihood using the Adam optimizer by
            default. Alternative torch.optim.* optimizer can be passed in
            through this argument.
        **optimizer_kwargs :
            Arguments that are passed to the optimizer during estimation.

        Returns
        -------
            Does not return anything, but modifies the self.predict attribute to
            refer to the new optimizer object.
        """
        if self.loader is None:
            raise RuntimeError("self.loader is not set (call setup_data first)")

        def nll(batch):
            return -self.likelihood(batch).sum()
        link_fns = {"mean": lambda x: x}
        self.predict = GLMPredictor(
            n_outcomes=self.n_outcomes,
            feature_dims=self.feature_dims,
            link_fns=link_fns,
            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)
        mu = params.get("mean")
        sigma = params.get("sdev")

        # log likelihood for Gaussian
        log_likelihood = -0.5 * (torch.log(2 * torch.pi * sigma ** 2) + ((y - mu) ** 2) / (sigma ** 2))
        return log_likelihood

    def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
        """Invert pseudoobservations."""
        mu, sdev, u = self._local_params(x, u)
        y = norm(loc=mu, scale=sdev).ppf(u)
        return torch.from_numpy(y).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, sdev, y = self._local_params(x, y)
        u = norm.cdf(y, loc=mu, scale=sdev)
        u = np.clip(u, epsilon, 1 - epsilon)
        return torch.from_numpy(u).float()

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

invert(u, x)

Invert pseudoobservations.

Source code in scdesigner/src/scdesigner/distributions/gaussian.py
 97
 98
 99
100
101
def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
    """Invert pseudoobservations."""
    mu, sdev, u = self._local_params(x, u)
    y = norm(loc=mu, scale=sdev).ppf(u)
    return torch.from_numpy(y).float()

likelihood(batch)

Compute the log-likelihood

Source code in scdesigner/src/scdesigner/distributions/gaussian.py
86
87
88
89
90
91
92
93
94
95
def likelihood(self, batch) -> torch.Tensor:
    """Compute the log-likelihood"""
    y, x = batch
    params = self.predict(x)
    mu = params.get("mean")
    sigma = params.get("sdev")

    # log likelihood for Gaussian
    log_likelihood = -0.5 * (torch.log(2 * torch.pi * sigma ** 2) + ((y - mu) ** 2) / (sigma ** 2))
    return log_likelihood

setup_optimizer(optimizer_class=torch.optim.Adam, **optimizer_kwargs)

Gaussian Model Optimizer

By default optimization is done using Adam. This can be customized using the optimizer_class argument. The link function for the mean is an identity link.

Parameters:

Name Type Description Default
optimizer_class Optional[callable]

We optimize the negative log likelihood using the Adam optimizer by default. Alternative torch.optim.* optimizer can be passed in through this argument.

Adam
**optimizer_kwargs

Arguments that are passed to the optimizer during estimation.

{}

Returns:

Type Description
Does not return anything, but modifies the self.predict attribute to

refer to the new optimizer object.

Source code in scdesigner/src/scdesigner/distributions/gaussian.py
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
def setup_optimizer(
        self,
        optimizer_class: Optional[callable] = torch.optim.Adam,
        **optimizer_kwargs,
):
    """
    Gaussian Model Optimizer

    By default optimization is done using Adam. This can be customized using
    the `optimizer_class` argument. The link function for the mean is an
    identity link.

    Parameters
    ----------
    optimizer_class : Optional[callable]
        We optimize the negative log likelihood using the Adam optimizer by
        default. Alternative torch.optim.* optimizer can be passed in
        through this argument.
    **optimizer_kwargs :
        Arguments that are passed to the optimizer during estimation.

    Returns
    -------
        Does not return anything, but modifies the self.predict attribute to
        refer to the new optimizer object.
    """
    if self.loader is None:
        raise RuntimeError("self.loader is not set (call setup_data first)")

    def nll(batch):
        return -self.likelihood(batch).sum()
    link_fns = {"mean": lambda x: x}
    self.predict = GLMPredictor(
        n_outcomes=self.n_outcomes,
        feature_dims=self.feature_dims,
        link_fns=link_fns,
        loss_fn=nll,
        optimizer_class=optimizer_class,
        optimizer_kwargs=optimizer_kwargs,
        device=self.device,
    )

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

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

Source code in scdesigner/src/scdesigner/distributions/gaussian.py
103
104
105
106
107
108
109
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, sdev, y = self._local_params(x, y)
    u = norm.cdf(y, loc=mu, scale=sdev)
    u = np.clip(u, epsilon, 1 - epsilon)
    return torch.from_numpy(u).float()

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'))

NegBinEQTL

Bases: NegBin

Negative-binomial marginal for single-cell eQTL data.

This provides an alternative to the ordinary negative binomial marginal model that's suitable for single-cell eQTL studies. It supports donor-level random intercepts that are integrated out in an EM step. It also ensures that different SNPs can be used as genotype predictors for every response gene without having to store all SNPs in the same design matrix.

We still use a Poisson model for the initialization, But we further use the method of moments to initialize random effects of specific hyperparameters.

Parameters:

Name Type Description Default
formula dict or str

Dictionary giving the formula for "mean" and "dispersion". The mean formula uses lme4-style syntax. It must include the reserved term genotype, which stands for each gene's SNP dosages, and one donor-level random intercept, e.g. (1 | donor), where donor is the column of adata.obs with donor IDs. Terms like genotype * cell_type define cell-type-specific eQTLs and genotype * bs(pseudotime, df=5) defines dynamic eQTLs. The dispersion formula cannot use genotype or random effects.

required
dosage DataFrame

An n_donor x SNP table giving variant counts per donor. Donor order in all later estimates is determined by the row indices from this matrix.

required
snp_map dict[str, list[str]]

Association between the gene names and adata.var_names to the column names of snps in dosage. This is used to understand which SNPs are potentially related to which genes.

required
estimate_sigma2 bool

Whether to re-estimate the random intercept variances after each epoch. This is also used as the regularization strength lam_j.

True
em_warmup_epochs int

How many epochs across which we fix lam. This is necessary because the first few epochs don't really give reliable estimates for U.

3
sigma2_method (laplace, edgeworth)

Strategy for estimating the posterior moments for the donor variance in the EM update See donor_moments.py for more details. Laplace is similar to what packages like glmmTMB implement, Edgeworth is a high-order correction that does well for sparse genes.

"laplace"
mode_polish bool

After each epoch, should we apply a Newton step to improve estimation for U? This can accelerate convergence and lead to better donor variance estimates.

True
sigma2_bounds tuple of float

Minimum and maximum values for sigma_j^2 to use to stabilize estimates during the EM updates.

(0.0001, 10.0)
donor_blocked bool or None

Should we first order the cells by donor rather than randomly sampling them? If sorted by donor, the data structure representing each batch is much more memory efficient.

None

Examples:

>>> from scdesigner import datasets
>>> from scdesigner.distributions import NegBinEQTL
>>>
>>> adata = datasets.dong_eqtl()
>>> snp_map = {gene: [snp] for gene, snp in adata.var["snp"].items()}
>>> model = NegBinEQTL(
...     {"mean": "~ genotype * cell_type + (1 | indiv)", "dispersion": "~ 1"},
...     dosage=adata.uns["dosage"],
...     snp_map=snp_map,
... )
>>> model.setup_data(adata)
>>> model.fit(max_epochs=5, verbose=False)
>>> sigma2 = model.sigma2  # per-gene donor variance
Source code in scdesigner/src/scdesigner/distributions/negbin_eqtl.py
 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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
class NegBinEQTL(NegBin):
    """Negative-binomial marginal for single-cell eQTL data.

    This provides an alternative to the ordinary negative binomial marginal
    model that's suitable for single-cell eQTL studies. It supports donor-level
    random intercepts that are integrated out in an EM step. It also ensures
    that different SNPs can be used as genotype predictors for every response
    gene without having to store all SNPs in the same design matrix.

    We still use a Poisson model for the initialization, But we further use the
    method of moments to initialize random effects of specific hyperparameters.

    Parameters
    ----------
    formula : dict or str
        Dictionary giving the formula for "mean" and "dispersion".  The mean
        formula uses lme4-style syntax.  It must include the reserved term
        ``genotype``, which stands for each gene's SNP dosages, and one
        donor-level random intercept, e.g. ``(1 | donor)``, where ``donor`` is
        the column of `adata.obs` with donor IDs. Terms like ``genotype *
        cell_type`` define cell-type-specific eQTLs and ``genotype *
        bs(pseudotime, df=5)`` defines dynamic eQTLs. The dispersion formula
        cannot use ``genotype`` or random effects.
    dosage : pandas.DataFrame
        An n_donor x SNP table giving variant counts per donor. Donor order in
        all later estimates is determined by the row indices from this matrix.
    snp_map : dict[str, list[str]]
        Association between the gene names and `adata.var_names` to the column
        names of snps in dosage. This is used to understand which SNPs are
        potentially related to which genes.
    estimate_sigma2 : bool
        Whether to re-estimate the random intercept variances after each epoch.
        This is also used as the regularization strength lam_j.
    em_warmup_epochs : int
        How many epochs across which we fix `lam`. This is necessary because the
        first few epochs don't really give reliable estimates for U.
    sigma2_method : {"laplace", "edgeworth"}
        Strategy for estimating the posterior moments for the donor variance in
        the EM update See donor_moments.py for more details. Laplace is similar
        to what packages like glmmTMB implement, Edgeworth is a high-order
        correction that does well for sparse genes.
    mode_polish : bool
        After each epoch, should we apply a Newton step to improve estimation
        for U? This can accelerate convergence and lead to better donor variance
        estimates.
    sigma2_bounds : tuple of float
        Minimum and maximum values for `sigma_j^2` to use to stabilize estimates
        during the EM updates.
    donor_blocked : bool or None
        Should we first order the cells by donor rather than randomly sampling
        them? If sorted by donor, the data structure representing each batch is
        much more memory efficient.

    Examples
    --------
    >>> from scdesigner import datasets
    >>> from scdesigner.distributions import NegBinEQTL
    >>>
    >>> adata = datasets.dong_eqtl()
    >>> snp_map = {gene: [snp] for gene, snp in adata.var["snp"].items()}
    >>> model = NegBinEQTL(
    ...     {"mean": "~ genotype * cell_type + (1 | indiv)", "dispersion": "~ 1"},
    ...     dosage=adata.uns["dosage"],
    ...     snp_map=snp_map,
    ... )
    >>> model.setup_data(adata)
    >>> model.fit(max_epochs=5, verbose=False)
    >>> sigma2 = model.sigma2  # per-gene donor variance
    """

    def __init__(
        self,
        formula: Union[Dict, str],
        *,
        dosage: pd.DataFrame,
        snp_map: Dict[str, List[str]],
        estimate_sigma2: bool = True,
        em_warmup_epochs: int = 3,
        sigma2_method: str = "laplace",
        sigma2_bounds: tuple = (1e-4, 10.0),
        mode_polish: bool = True,
        donor_blocked=None,
        **kwargs,
    ):
        formula = standardize_formula(formula, allowed_keys=["mean", "dispersion"])
        formula, self.donor_col = parse_eqtl_formula(formula)
        Marginal.__init__(self, formula, **kwargs)

        self.dosage = dosage
        self.snp_map = snp_map
        self._estimate_sigma2 = estimate_sigma2
        self._em_warmup_epochs = em_warmup_epochs
        self._sigma2_method = sigma2_method
        self._sigma2_bounds = sigma2_bounds
        self._mode_polish = mode_polish
        self._donor_blocked = donor_blocked
        self.donor_order = list(dosage.index.astype(str))
        self.donor_to_code = {name: i for i, name in enumerate(self.donor_order)}
        self.D = None
        self.mask = None

    def _augment_obs(self, obs: pd.DataFrame) -> pd.DataFrame:
        """Return a copy of `obs` with a donor ID column."""
        donor_names = obs[self.donor_col].astype(str)
        obs = obs.copy()
        obs["_donor_code"] = donor_names.map(self.donor_to_code).astype(float)
        return obs

    def _build_dosage_tensors(self, var_names: List[str]):
        """Gather per-gene SNP dosages into the (K, J, K_max) tensor + mask."""
        # Number of SNPs considered per gene.
        k_max = max((len(v) for v in self.snp_map.values()), default=1)
        k_max = max(k_max, 1)
        n_individuals, n_genes = len(self.donor_order), len(var_names)

        # Build the dosage matrix, gene by gene and snp by snp.
        D = torch.zeros(n_individuals, n_genes, k_max)
        mask = torch.zeros(n_genes, k_max)
        dosage = self.dosage.loc[self.donor_order]
        for j, gene in enumerate(var_names):
            snp_cols = self.snp_map.get(gene, [])
            if snp_cols:
                D[:, j, : len(snp_cols)] = torch.tensor(
                    dosage[snp_cols].values, dtype=torch.float32
                )
                mask[j, : len(snp_cols)] = 1.0
        return D, mask

    def setup_data(self, adata: AnnData, batch_size: int = 1024, **kwargs):
        new_obs = self._augment_obs(adata.obs)
        adata = AnnData(X=adata.X, obs=new_obs, var=adata.var)

        self.D, self.mask = self._build_dosage_tensors(list(adata.var_names))
        if self._donor_blocked is None:
            self._donor_blocked = self.D.shape[2] > 1

        # By sorting cells by donor, the dosage lookup gets simplified
        # during data loading.
        if self._donor_blocked:
            order = np.argsort(new_obs["_donor_code"].values, kind="stable")
            adata = adata[order].copy()

        super().setup_data(adata, batch_size=batch_size, **kwargs)

    def _subset_loader(self, indices, training: bool):
        # Split the data loader into train and test loaders
        if self._donor_blocked:
            indices = np.sort(indices)
        return super()._subset_loader(indices, training)

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

        n_train = len(self.train_loader.dataset)

        def penalized_nll(batch):
            # [Explain: why one forward pass serves all three consumers.]
            y, x = batch
            params = self.predict(x)
            mu, r = params["mean"], params["dispersion"]
            nll = -nb_loglik(y, mu, r).sum()

            donor_idx = x["genotype"][:, 0].long()
            accumulators = self.predict.accumulators
            if accumulators:
                # The score is the derivative of the ordinary log likelihood,
                # while the higher order moments are derivatives of the negative
                # log likelihood.
                with torch.no_grad():
                    p = mu / (mu + r)
                    q = (y + r) * p * (1.0 - p)
                    score = r * (y - mu) / (r + mu)
                    accumulators["score"].index_add_(0, donor_idx, score)
                    accumulators["observed"].index_add_(0, donor_idx, q)
                    third = q * (1.0 - 2.0 * p)
                    accumulators["third"].index_add_(0, donor_idx, third)
                    if "fourth" in accumulators:
                        fourth = q * (1.0 - 6.0 * p + 6.0 * p.square())
                        accumulators["fourth"].index_add_(0, donor_idx, fourth)

            # rescale the penalty to the current batch
            penalty = 0.5 * (self.predict.lam * self.predict.U ** 2).sum()
            return nll + penalty * (y.shape[0] / n_train)

        # Summary statistics to accumulate for the sigma2 estimation strategy
        sigma2_accumulators = {
            "laplace": ("score", "observed", "third"),
            "edgeworth": ("score", "observed", "third", "fourth"),
        }
        accumulator_names = (
            sigma2_accumulators[self._sigma2_method]
            if self._estimate_sigma2
            else ()
        )
        self.predict = EQTLPredictor(
            n_outcomes=self.n_outcomes,
            feature_dims=self.feature_dims,
            dosage=self.D,
            mask=self.mask,
            interaction_dim=self.feature_dims.get("interaction", 1) - 1,
            accumulator_names=accumulator_names,
            loss_fn=penalized_nll,
            optimizer_class=optimizer_class,
            optimizer_kwargs=optimizer_kwargs,
            device=self.device,
        )

    def _center_random_effects(self):
        """Center each gene's mean donor effect

        The intercept term and the donor effects are linearly dependent, though
        the donor effects are regularized (via the prior) to be closer to 0.
        This centering makes sure that shifts in U due to the intercept are not
        going to inflate sigma_j^2.
        """
        with torch.no_grad():
            if self.predictor_names["mean"][0] == "Intercept":
                offset = self.predict.U.mean(dim=0)
                self.predict.U.sub_(offset.unsqueeze(0))
                self.predict.coefs["mean"][0].add_(offset)

    def _em_update_sigma2(self) -> torch.Tensor:
        """Update the random-intercept variance and return posterior means.

        These are approximations to ``E[u_kj | y]`` and ``E[u_kj**2 | y]``,
        which are necessary for the EM update,

            sigma_j^2 = (1/K) sum_k E[u_kj**2 | y].

        See donor_moments.py for more details.
        """
        with torch.no_grad():
            accumulators = self.predict.accumulators
            info = (
                self.predict.lam.unsqueeze(0)
                + accumulators["observed"]
            )
            mean, m2 = POSTERIOR_MOMENTS[self._sigma2_method](
                self.predict.U,
                info,
                accumulators.get("third"),
                accumulators.get("fourth"),
            )

            # Only the edgeworth variance can ever be negative.
            invalid = (
                (m2 < mean.square()).sum()
                if self._sigma2_method == "edgeworth"
                else torch.zeros((), dtype=torch.long, device=m2.device)
            )
            self.predict.invalid_variances.copy_(invalid)

            sigma2 = m2.mean(dim=0).clamp(*self._sigma2_bounds)
            self.predict.lam.copy_(1.0 / sigma2)
            return mean

    def _newton_step(self) -> torch.Tensor:
        """Newton update of `U`

        We can prove the estimate of U after each epoch by taking a Newton step.
        The necessary information is already accumulated in the previous
        training data pass. The specific form of the update is,


            delta_kj = (score_kj - lam_j U_kj) / (observed_kj + lam_j)
        """
        info = self.predict.lam.unsqueeze(0) + self.predict.accumulators["observed"]
        return (
            self.predict.accumulators["score"]
            - self.predict.lam * self.predict.U
        ) / info

    def _polish_mode(self, delta: torch.Tensor):
        """Move `U` toward the conditional mode

        Writing, `A(u) = sum_i (y_i + r) p(1-p)`, it's possible to show that the
        curvature `-l'' = A + lam` satisfies,

            |A'| = |sum_i (y_i + r) p(1-p)(1-2p)| <= A
            =>  |d/du log(-l'')| = |A'| / (A + lam) <= 1

        because `|1 - 2p| < 1`. This bounds the change in curvature in a step of
        size t by `e^t`, so

            l'(u+t) >= (-l''(u)) [ delta - (e^t - 1) ]

        B y setting `t - log(1  + |delta|)`, we can ensure that `l` strictly
        increases. Therefore we choose step sizes,

            step = sign(delta) * log1p(|delta|)

        which are the largest steps guaranteed not to overshoot.
        """
        self.predict.U.add_(delta.sign() * delta.abs().log1p())

    def _on_epoch_end(self, epoch: int):
        if self._estimate_sigma2 and epoch > self._em_warmup_epochs:
            self._center_random_effects()
            with torch.no_grad():
                delta = self._newton_step()
                self.predict.mode_gap.copy_(delta.abs().amax(dim=0))
                self._em_update_sigma2()
                if self._mode_polish:
                    self._polish_mode(delta)
        self.predict.zero_accumulators()

    def _mom_sigma2(self) -> torch.Tensor:
        """Method-of-moments initialization for sigma_j^2.

        Using the delta method we can show,

            sigma_j^2 ~= [ Var_k(m_kj) - E_k(m_kj / n_k) ] / (E_k m_kj)^2
        """
        n_donors = len(self.donor_order)
        sums = torch.zeros(n_donors, self.n_outcomes, device=self.device)
        counts = torch.zeros(n_donors, device=self.device)

        with torch.no_grad():
            for batch in self.train_loader:
                y, x = self._move_batch_to_device(batch)
                donor_idx = x["genotype"][:, 0].long()
                sums.index_add_(0, donor_idx, y)
                counts.index_add_(0, donor_idx, torch.ones_like(donor_idx, dtype=sums.dtype))

        present = counts > 0
        m = sums[present] / counts[present].unsqueeze(1)
        n = counts[present].unsqueeze(1)

        between = m.var(dim=0, unbiased=True)
        within = (m / n).mean(dim=0)
        denom = m.mean(dim=0).clamp(min=1e-8) ** 2
        return ((between - within) / denom).clamp(*self._sigma2_bounds)

    def _mom_beta(self):
        """Initialize the genotype effect from the three dosage groups.

        The SNP dosages can only take on values {0, 1, 2}. We can estimate the
        associated genotype effects in a single pass through the data using the
        method of moments,

            log m_d = alpha + beta * d,   d in {0, 1, 2}

        This only estimate the dosage for d = {0}, but that's enough of a warm
        start.

        Returns
        -------
        beta : torch.Tensor
            (J,) effects across gene.
        mean_dose : torch.Tensor
            (J,) mean dosages per cell. This is just used during centering.
        """
        n = torch.zeros(3, self.n_outcomes, device=self.device)
        sum_y = torch.zeros(3, self.n_outcomes, device=self.device)
        dose_sum = torch.zeros(self.n_outcomes, device=self.device)
        n_cells = 0

        lead = self.predict.D[:, :, 0] * self.predict.mask[:, 0]

        with torch.no_grad():
            for batch in self.train_loader:
                y, x = self._move_batch_to_device(batch)
                dose = lead[x["genotype"][:, 0].long()]
                dose_sum += dose.sum(dim=0)
                n_cells += y.shape[0]
                for d in range(3):
                    in_group = (dose == d).to(y.dtype)
                    n[d] += in_group.sum(dim=0)
                    sum_y[d] += (y * in_group).sum(dim=0)

        # weighted least squares of group mean on dosage. The weights are the
        # group sizes.
        group_mean = sum_y / n.clamp(min=1.0)
        log_mean = torch.log(group_mean.clamp(min=1e-6))
        levels = torch.arange(3, device=self.device, dtype=n.dtype).unsqueeze(1)

        w = n
        sw = w.sum(dim=0).clamp(min=1e-8)
        mean_d = (w * levels).sum(dim=0) / sw
        mean_l = (w * log_mean).sum(dim=0) / sw
        cov = (w * (levels - mean_d) * (log_mean - mean_l)).sum(dim=0)
        var_d = (w * (levels - mean_d) ** 2).sum(dim=0)

        beta = torch.where(var_d > 1e-8, cov / var_d.clamp(min=1e-8),
                           torch.zeros_like(cov))
        return beta, dose_sum / max(n_cells, 1)

    def _initialize_parameters(self, **kwargs):
        super()._initialize_parameters(**kwargs)

        beta, mean_dose = self._mom_beta()
        with torch.no_grad():
            self.predict.beta[:, 0].copy_(beta)
            if self.predictor_names["mean"][0] == "Intercept":
                self.predict.coefs["mean"][0, :] -= beta * mean_dose

        sigma2 = self._mom_sigma2()
        with torch.no_grad():
            self.predict.lam.copy_(1.0 / sigma2.clamp(*self._sigma2_bounds))

    @property
    def sigma2(self) -> torch.Tensor:
        """Current per-gene random-intercept variance, `1 / lam`."""
        return (1.0 / self.predict.lam).detach()

    @contextmanager
    def simulated_donor_effects(self, seed=None):
        """Generate new donor effects `u ~ N(0, sigma_j^2)`

        If we don't use this method, then all simulation is based on the
        estimated `U` from the observed donors. If you want to imagine a brand
        new set cohort, then we should use this method. Especially important for
        power analysis.

        Args:
            seed: optional integer for a reproducible draw. With `None` the
                ambient torch RNG is used, so repeated blocks differ.
        """
        predict = self.predict
        previous_flag = predict.use_simulated_donor_effects
        previous_draw = predict.U_sim.clone()
        try:
            with torch.no_grad():
                generator = None
                if seed is not None:
                    generator = torch.Generator(device=predict.U_sim.device)
                    generator.manual_seed(int(seed))
                noise = torch.randn(
                    predict.U_sim.shape,
                    generator=generator,
                    device=predict.U_sim.device,
                    dtype=predict.U_sim.dtype,
                )
                predict.U_sim.copy_(noise * self.sigma2.sqrt().unsqueeze(0))
            predict.use_simulated_donor_effects = True
            yield self
        finally:
            predict.use_simulated_donor_effects = previous_flag
            with torch.no_grad():
                predict.U_sim.copy_(previous_draw)

    @property
    def invalid_posterior_variance_count(self) -> int:
        """Donor-gene pairs with negative Edgeworth variances"""
        return int(self.predict.invalid_variances.item())

    @property
    def mode_gap(self) -> torch.Tensor:
        """Per-gene max `|Newton step|` for `U` at the last EM update, `(J,)`.

        This shows how far U was from the true posterior mode. This gets at the
        skewness in the posterior for sigma^2_j.
        """
        return self.predict.mode_gap.detach()

invalid_posterior_variance_count property

Donor-gene pairs with negative Edgeworth variances

mode_gap property

Per-gene max |Newton step| for U at the last EM update, (J,).

This shows how far U was from the true posterior mode. This gets at the skewness in the posterior for sigma^2_j.

sigma2 property

Current per-gene random-intercept variance, 1 / lam.

simulated_donor_effects(seed=None)

Generate new donor effects u ~ N(0, sigma_j^2)

If we don't use this method, then all simulation is based on the estimated U from the observed donors. If you want to imagine a brand new set cohort, then we should use this method. Especially important for power analysis.

Args: seed: optional integer for a reproducible draw. With None the ambient torch RNG is used, so repeated blocks differ.

Source code in scdesigner/src/scdesigner/distributions/negbin_eqtl.py
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
@contextmanager
def simulated_donor_effects(self, seed=None):
    """Generate new donor effects `u ~ N(0, sigma_j^2)`

    If we don't use this method, then all simulation is based on the
    estimated `U` from the observed donors. If you want to imagine a brand
    new set cohort, then we should use this method. Especially important for
    power analysis.

    Args:
        seed: optional integer for a reproducible draw. With `None` the
            ambient torch RNG is used, so repeated blocks differ.
    """
    predict = self.predict
    previous_flag = predict.use_simulated_donor_effects
    previous_draw = predict.U_sim.clone()
    try:
        with torch.no_grad():
            generator = None
            if seed is not None:
                generator = torch.Generator(device=predict.U_sim.device)
                generator.manual_seed(int(seed))
            noise = torch.randn(
                predict.U_sim.shape,
                generator=generator,
                device=predict.U_sim.device,
                dtype=predict.U_sim.dtype,
            )
            predict.U_sim.copy_(noise * self.sigma2.sqrt().unsqueeze(0))
        predict.use_simulated_donor_effects = True
        yield self
    finally:
        predict.use_simulated_donor_effects = previous_flag
        with torch.no_grad():
            predict.U_sim.copy_(previous_draw)

NegBinIRLS

Bases: NegBin

Negative-Binomial Marginal using Stochastic IRLS with active response tracking and log-likelihood convergence.

Source code in scdesigner/src/scdesigner/distributions/negbin_irls.py
  9
 10
 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
class NegBinIRLS(NegBin):
    """
    Negative-Binomial Marginal using Stochastic IRLS with
    active response tracking and log-likelihood convergence.
    """
    def __init__(self, formula: Union[Dict, str], **kwargs):
        formula = standardize_formula(formula, allowed_keys=['mean', 'dispersion'])
        super().__init__(formula, device="cpu")


    def fit(
        self,
        max_epochs=10,
        tol=1e-4,
        eta=0.1,
        verbose=True,
        disp_ridge=1e-4,
        val_frac: float = 0.1,
        min_epochs: int = 10,
        loss_tol: float = 1e-4,
        patience: int = 40,
        validation_seed: int = 0,
        **kwargs,
    ):
        self.train_loader = self.loader
        self.validation_loader = None
        self._validation_split_config = None

        if self.predict is None:
            self.setup_optimizer(**kwargs)

        # 1. Initialization using poisson fit
        initialize_kwargs = _filter_kwargs(kwargs, DEFAULT_ALLOWED_KWARGS['initialize'])
        beta_init, gamma_init = initialize_parameters(
            self.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)

        # 2. All genes are active at the start
        active_mask = torch.ones(self.n_outcomes, dtype=torch.bool)
        ll_ = - 1e9 * torch.ones(self.n_outcomes, dtype=torch.float32)

        self.fit_history = []
        self.best_epoch = None
        self.best_validation_loss = None
        self.stopped_epoch = None

        for epoch in range(max_epochs):
            if not active_mask.any():
                break
            ll, n_batches = 0.0, 0

            with torch.no_grad():
                for y_batch, x_dict in self.loader:

                    # Slice active genes
                    idx = torch.where(active_mask)[0]
                    y_act = y_batch[:, active_mask]
                    X = x_dict['mean']
                    Z = x_dict['dispersion']

                    # Fetch current coefficients and update
                    b_curr = self.predict.coefs['mean'][:, active_mask]
                    g_curr = self.predict.coefs['dispersion'][:, active_mask]
                    b_next, g_next, conv_mask, ll_cur = step_stochastic_irls(y_act, X, Z, b_curr, g_curr, eta, tol, ll_[active_mask],
                                                                                 disp_ridge=disp_ridge)
                    ll_[active_mask] = ll_cur

                    # Update Parameters and de-activate converged genes
                    with torch.no_grad():
                        self.predict.coefs['mean'][:, active_mask] = b_next
                        self.predict.coefs['dispersion'][:, active_mask] = g_next
                        active_mask[idx[conv_mask]] = False

                    # Accumulate batch log-likelihood using `ll` from the IRLS step
                    ll += ll_.sum().item()
                    n_batches += 1

                train_loss = -ll / n_batches if n_batches > 0 else float("nan")
                self.fit_history.append(
                    {
                        "epoch": epoch + 1,
                        "train_loss": train_loss,
                        "val_loss": None,
                        "best": False,
                        "stopped": False,
                    }
                )

                if verbose and ((epoch + 1) % 10) == 0:
                    print(f"Epoch {epoch+1}/{max_epochs} | Genes remaining: {active_mask.sum().item()} | Loss: {train_loss:.4f}", end='\r')

            if not active_mask.any():
                break

        if verbose:
            print() # Maintain the loss output

        self.parameters = self.format_parameters()

Poisson

Bases: Marginal

Poisson marginal estimator

This subclass behaves like Marginal but assumes each gene follows a Poisson distribution with mean mu_j(x) that depends on covariates x via the provided formula object.

The allowed formula keys are 'mean', defaulting to a single mean term if a string formula is supplied.

Examples:

>>> from scdesigner.distributions import Poisson
>>> import scdesigner.datasets
>>>
>>> pancreas = scdesigner.datasets.pancreas()
>>>
>>> sim = Poisson(formula="~ bs(pseudotime, df=5)")
>>> 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/poisson.py
 10
 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
class Poisson(Marginal):
    """Poisson marginal estimator

    This subclass behaves like `Marginal` but assumes each gene follows a
    Poisson distribution with mean `mu_j(x)` that depends on covariates `x`
    via the provided `formula` object.

    The allowed formula keys are 'mean', defaulting to a single `mean` term
    if a string formula is supplied.

    Examples
    --------
    >>> from scdesigner.distributions import Poisson
    >>> import scdesigner.datasets
    >>>
    >>> pancreas = scdesigner.datasets.pancreas()
    >>>
    >>> sim = Poisson(formula="~ bs(pseudotime, df=5)")
    >>> 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'])
        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)")

        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 _initialize_parameters(self, **kwargs):
        beta, _ = initialize_parameters(
            self.train_loader,
            self.n_outcomes,
            self.feature_dims["mean"],
            p_disp=1,
        )
        self.predict.coefs["mean"].data.copy_(beta)

    def likelihood(self, batch) -> torch.Tensor:
        """Compute the log-likelihood"""
        y, x = batch
        params = self.predict(x)
        mu = params.get("mean")
        return y * torch.log(mu) - mu - torch.lgamma(y + 1)

    def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
        """Invert pseudoobservations."""
        mu, u = self._local_params(x, u)
        y = poisson(mu).ppf(u)
        return torch.from_numpy(y).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, y = self._local_params(x, y)
        u1 = poisson(mu).cdf(y)
        u2 = np.where(y > 0, poisson(mu).cdf(y - 1), 0)
        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) -> Union[np.ndarray, Tuple[np.ndarray, np.ndarray]]:
        params = self.predict(x)
        mu = params.get('mean')
        if y is None:
            return _to_numpy(mu)
        return _to_numpy(mu, y)

invert(u, x)

Invert pseudoobservations.

Source code in scdesigner/src/scdesigner/distributions/poisson.py
80
81
82
83
84
def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
    """Invert pseudoobservations."""
    mu, u = self._local_params(x, u)
    y = poisson(mu).ppf(u)
    return torch.from_numpy(y).float()

likelihood(batch)

Compute the log-likelihood

Source code in scdesigner/src/scdesigner/distributions/poisson.py
73
74
75
76
77
78
def likelihood(self, batch) -> torch.Tensor:
    """Compute the log-likelihood"""
    y, x = batch
    params = self.predict(x)
    mu = params.get("mean")
    return y * torch.log(mu) - mu - torch.lgamma(y + 1)

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

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

Source code in scdesigner/src/scdesigner/distributions/poisson.py
86
87
88
89
90
91
92
93
94
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, y = self._local_params(x, y)
    u1 = poisson(mu).cdf(y)
    u2 = np.where(y > 0, poisson(mu).cdf(y - 1), 0)
    v = np.random.uniform(size=y.shape)
    u = np.clip(v * u1 + (1 - v) * u2, epsilon, 1 - epsilon)
    return torch.from_numpy(u).float()

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()

ZeroInflatedPoisson

Bases: Marginal

Zero-Inflated Poisson marginal estimator

Feature j's zero inflation probability is pi_j(x). If not zero-ed, the draw is Poi(mu_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' and 'zero_inflation'. If a string formula is supplied it is taken to specify the mean by default.

Examples:

>>> from scdesigner.distributions import ZeroInflatedPoisson
>>> import scdesigner.datasets
>>>
>>> pancreas = scdesigner.datasets.pancreas()
>>>
>>> sim = ZeroInflatedPoisson(formula={"mean": "~ pseudotime", "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_poisson.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
class ZeroInflatedPoisson(Marginal):
    """Zero-Inflated Poisson marginal estimator

    Feature j's zero inflation probability is `pi_j(x)`.  If not zero-ed, the
    draw is Poi(mu_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' and 'zero_inflation'. If a string
    formula is supplied it is taken to specify the `mean` by default.

    Examples
    --------
    >>> from scdesigner.distributions import ZeroInflatedPoisson
    >>> import scdesigner.datasets
    >>>
    >>> pancreas = scdesigner.datasets.pancreas()
    >>>
    >>> sim = ZeroInflatedPoisson(formula={"mean": "~ pseudotime", "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', '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,
            "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, _ = initialize_parameters(
            self.train_loader,
            self.n_outcomes,
            self.feature_dims["mean"],
            p_disp=1,
        )
        self.predict.coefs["mean"].data.copy_(beta)

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

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

        poisson_loglikelihood = y * torch.log(mu + 1e-10) - mu - torch.lgamma(y + 1)
        return torch.log(
            pi * (y == 0) + (1 - pi) * torch.exp(poisson_loglikelihood) + 1e-10
        )

    def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
        """Invert pseudoobservations."""
        mu, pi, u = self._local_params(x, u)
        conditional_u = np.where(u > pi, (u - pi) / (1 - pi + 1e-10), 0.0)
        y = poisson(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, pi, y = self._local_params(x, y)
        nb_distn = poisson(mu)
        u1 = pi + (1 - pi) * nb_distn.cdf(y)
        u2 = np.where(y > 0, pi + (1 - pi) * nb_distn.cdf(y-1), 0)
        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')
        pi = params.get('zero_inflation')
        mu = _lam_to_mu(lam, pi)
        if y is None:
            return _to_numpy(mu, pi)
        return _to_numpy(mu, pi, y)

invert(u, x)

Invert pseudoobservations.

Source code in scdesigner/src/scdesigner/distributions/zero_inflated_poisson.py
 97
 98
 99
100
101
102
103
def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
    """Invert pseudoobservations."""
    mu, pi, u = self._local_params(x, u)
    conditional_u = np.where(u > pi, (u - pi) / (1 - pi + 1e-10), 0.0)
    y = poisson(mu).ppf(conditional_u)
    delta = (u > pi).astype(float)
    return torch.from_numpy(y * delta).float()

likelihood(batch)

Compute the log-likelihood

Source code in scdesigner/src/scdesigner/distributions/zero_inflated_poisson.py
84
85
86
87
88
89
90
91
92
93
94
95
def likelihood(self, batch) -> torch.Tensor:
    """Compute the log-likelihood"""
    y, x = batch
    params = self.predict(x)
    lam = params.get("mean")
    pi = params.get("zero_inflation")
    mu = _lam_to_mu(lam, pi)

    poisson_loglikelihood = y * torch.log(mu + 1e-10) - mu - torch.lgamma(y + 1)
    return torch.log(
        pi * (y == 0) + (1 - pi) * torch.exp(poisson_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_poisson.py
105
106
107
108
109
110
111
112
113
114
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, pi, y = self._local_params(x, y)
    nb_distn = poisson(mu)
    u1 = pi + (1 - pi) * nb_distn.cdf(y)
    u2 = np.where(y > 0, pi + (1 - pi) * nb_distn.cdf(y-1), 0)
    v = np.random.uniform(size=y.shape)
    u = np.clip(v * u1 + (1 - v) * u2, epsilon, 1 - epsilon)
    return torch.from_numpy(u).float()

ZeroInflatedTruncatedGaussian

Bases: Marginal

Zero-Inflated Truncated Gaussian marginal estimator.

For each feature j, the distribution is a mixture: - with probability π_j(x), Y_j = 0 (point mass), - with probability 1-π_j(x), Y_j ~ N(μ_j(x), σ_j(x)^2) truncated to (0, ∞).

This yields a density on {0} ∪ (0, ∞). The mean formula models the latent Gaussian mean μ_j(x), not the marginal mean.

Allowed formula keys: mean, sdev, zero_inflation. A string formula is treated as the mean formula.

Examples:

>>> from scdesigner.distributions import ZeroInflatedTruncatedGaussian
>>> import scdesigner.datasets
>>>
>>> pancreas = scdesigner.datasets.pancreas()
>>>
>>> sim = ZeroInflatedTruncatedGaussian(formula={
...     "mean": "~ pseudotime",
...     "sdev": "~ pseudotime",
...     "zero_inflation": "~ pseudotime",
... })
>>> sim.setup_data(pancreas)
>>> sim.fit(max_epochs=1, verbose=False)
>>>
>>> y, x = next(iter(sim.loader))
>>> l = sim.likelihood((y, x))
>>> y_hat = sim.predict(x)
>>>
>>> u = sim.uniformize(y, x)
>>> x_star = sim.invert(u, x)
Source code in scdesigner/src/scdesigner/distributions/zero_inflated_truncated_gaussian.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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
class ZeroInflatedTruncatedGaussian(Marginal):
    """Zero-Inflated Truncated Gaussian marginal estimator.

    For each feature j, the distribution is a mixture:
      - with probability π_j(x), Y_j = 0 (point mass),
      - with probability 1-π_j(x), Y_j ~ N(μ_j(x), σ_j(x)^2) truncated to (0, ∞).

    This yields a density on {0} ∪ (0, ∞). The `mean` formula models the latent
    Gaussian mean μ_j(x), not the marginal mean.

    Allowed formula keys: `mean`, `sdev`, `zero_inflation`. A string formula is
    treated as the `mean` formula.

    Examples
    --------
    >>> from scdesigner.distributions import ZeroInflatedTruncatedGaussian
    >>> import scdesigner.datasets
    >>>
    >>> pancreas = scdesigner.datasets.pancreas()
    >>>
    >>> sim = ZeroInflatedTruncatedGaussian(formula={
    ...     "mean": "~ pseudotime",
    ...     "sdev": "~ pseudotime",
    ...     "zero_inflation": "~ pseudotime",
    ... })
    >>> sim.setup_data(pancreas)
    >>> sim.fit(max_epochs=1, verbose=False)
    >>>
    >>> y, x = next(iter(sim.loader))
    >>> l = sim.likelihood((y, x))
    >>> y_hat = sim.predict(x)
    >>>
    >>> u = sim.uniformize(y, x)
    >>> x_star = sim.invert(u, x)
    """
    def __init__(self, formula: Union[Dict, str], prior_alpha: float = 1.1, **kwargs):
        """
        Parameters
        ----------
        formula : Union[Dict, str]
            Model formulas for 'mean', 'sdev', and 'zero_inflation'.
        prior_alpha : float, default=1.1
            Alpha for Beta(alpha, alpha) prior on zero-inflation probabilities.
            Values > 1 discourage extreme π, improving generalization for sparse genes.
        **kwargs
            Additional arguments passed to the Marginal base class.
        """
        formula = standardize_formula(
            formula, allowed_keys=['mean', 'sdev', 'zero_inflation']
        )
        self.prior_alpha = prior_alpha
        # Remove prior_alpha from kwargs before passing to parent
        kwargs.pop('prior_alpha', None)
        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_fns = {
            "mean": lambda x: x,
            "sdev": torch.exp,
            "zero_inflation": torch.sigmoid,
        }

        def nll(batch):
            ll = -self.likelihood(batch).sum()

            # negative Beta(alpha, alpha) prior on zero-inflation probabilities
            pi = self.predict(batch[1]).get("zero_inflation")
            beta_penalty = (1 - self.prior_alpha) * (
                torch.log(pi.clamp(min=1e-10)) +
                torch.log((1 - pi).clamp(min=1e-10))
            ).sum()

            # -(likelihood + prior)
            return ll + beta_penalty

        self.predict = GLMPredictor(
            n_outcomes=self.n_outcomes,
            feature_dims=self.feature_dims,
            link_fns=link_fns,
            loss_fn=nll,
            optimizer_class=optimizer_class,
            optimizer_kwargs=optimizer_kwargs,
            device=self.device,
        )

    def _initialize_parameters(self, **kwargs):
        mean_init, log_sdev_init, logit_pi_init = _initialize_zitg_intercepts(
            self.train_loader, self.n_outcomes
        )
        self.predict.coefs["mean"].data[0].copy_(mean_init)
        self.predict.coefs["sdev"].data[0].copy_(log_sdev_init)
        self.predict.coefs["zero_inflation"].data[0].copy_(logit_pi_init)

    def likelihood(self, batch) -> torch.Tensor:
        """Compute the log-likelihood.

        For y == 0: log(pi).
        For y > 0: log(1 - pi) + log N(y; mu, sigma) - log Phi(mu / sigma),
        where the last term is the log-normalizer of the truncated normal on
        (0, inf). Computed via the standard-normal CDF; for nonnegative
        data mu / sigma should stay in a numerically benign range.
        """
        y, x = batch
        params = self.predict(x)
        mu = params.get("mean")
        sigma = params.get("sdev")
        pi = params.get("zero_inflation")

        # zero inflation component
        log_pi = torch.log(pi.clamp(min=1e-10))
        log_1mpi = torch.log((1 - pi).clamp(min=1e-10))

        # truncated gaussian component
        gaussian_logpdf = -0.5 * (torch.log(2 * torch.pi * sigma ** 2) + ((y - mu) ** 2) / (sigma ** 2))
        std_normal = torch.distributions.Normal(0.0, 1.0)
        log_trunc_norm = torch.log(std_normal.cdf(mu / sigma).clamp(min=1e-30))  # log Phi(mu / sigma)
        tn_logpdf = gaussian_logpdf - log_trunc_norm

        # combine
        return torch.where((y == 0), log_pi, log_1mpi + tn_logpdf)

    def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
        """Invert pseudoobservations.

        u <= pi maps to the atom at zero; u > pi maps through the truncated
        normal quantile function via `scipy.stats.truncnorm`.
        """
        mu, sdev, pi, u = self._local_params(x, u)
        q = np.clip((u - pi) / (1 - pi + 1e-10), 1e-6, 1 - 1e-6)
        a = -mu / sdev

        # invert using these truncated normal parameters
        y_pos = truncnorm.ppf(q, a=a, b=np.inf, loc=mu, scale=sdev)
        delta = (u > pi).astype(float)
        return torch.from_numpy(y_pos * delta).float()

    def uniformize(self, y: torch.Tensor, x: Dict[str, torch.Tensor], epsilon=1e-6) -> torch.Tensor:
        """Return uniformized pseudo-observations for y given covariates x.

        The CDF is 0 for y < 0, equals pi at y = 0 (atom), and
        pi + (1 - pi) * F_TN(y) for y > 0, where F_TN is the CDF of a normal
        N(mu, sigma^2) truncated to (0, inf). Values y == 0 are randomized
        uniformly within the atom [0, pi]; values y > 0 are deterministic.
        """
        mu, sdev, pi, y = self._local_params(x, y)
        Phi_neg = norm.cdf(0.0, loc=mu, scale=sdev)  # = Phi(-mu / sigma)
        denom = 1.0 - Phi_neg                         # = Phi(mu / sigma)

        gsn = (norm.cdf(y, loc=mu, scale=sdev) - Phi_neg) / (denom + 1e-12)
        F_tn = np.where(y > 0, gsn, 0.0)

        # right and left CDF limits at y; equal for y > 0, separated by the
        # atom of width pi at y == 0.
        u1 = pi + (1 - pi) * F_tn
        u2 = np.where(y > 0, u1, 0.0)
        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)
        mu = params.get("mean")
        sdev = params.get("sdev")
        pi = params.get("zero_inflation")
        if y is None:
            return _to_numpy(mu, sdev, pi)
        return _to_numpy(mu, sdev, pi, y)

__init__(formula, prior_alpha=1.1, **kwargs)

Parameters:

Name Type Description Default
formula Union[Dict, str]

Model formulas for 'mean', 'sdev', and 'zero_inflation'.

required
prior_alpha float

Alpha for Beta(alpha, alpha) prior on zero-inflation probabilities. Values > 1 discourage extreme π, improving generalization for sparse genes.

1.1
**kwargs

Additional arguments passed to the Marginal base class.

{}
Source code in scdesigner/src/scdesigner/distributions/zero_inflated_truncated_gaussian.py
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def __init__(self, formula: Union[Dict, str], prior_alpha: float = 1.1, **kwargs):
    """
    Parameters
    ----------
    formula : Union[Dict, str]
        Model formulas for 'mean', 'sdev', and 'zero_inflation'.
    prior_alpha : float, default=1.1
        Alpha for Beta(alpha, alpha) prior on zero-inflation probabilities.
        Values > 1 discourage extreme π, improving generalization for sparse genes.
    **kwargs
        Additional arguments passed to the Marginal base class.
    """
    formula = standardize_formula(
        formula, allowed_keys=['mean', 'sdev', 'zero_inflation']
    )
    self.prior_alpha = prior_alpha
    # Remove prior_alpha from kwargs before passing to parent
    kwargs.pop('prior_alpha', None)
    super().__init__(formula, **kwargs)

invert(u, x)

Invert pseudoobservations.

u <= pi maps to the atom at zero; u > pi maps through the truncated normal quantile function via scipy.stats.truncnorm.

Source code in scdesigner/src/scdesigner/distributions/zero_inflated_truncated_gaussian.py
139
140
141
142
143
144
145
146
147
148
149
150
151
152
def invert(self, u: torch.Tensor, x: Dict[str, torch.Tensor]) -> torch.Tensor:
    """Invert pseudoobservations.

    u <= pi maps to the atom at zero; u > pi maps through the truncated
    normal quantile function via `scipy.stats.truncnorm`.
    """
    mu, sdev, pi, u = self._local_params(x, u)
    q = np.clip((u - pi) / (1 - pi + 1e-10), 1e-6, 1 - 1e-6)
    a = -mu / sdev

    # invert using these truncated normal parameters
    y_pos = truncnorm.ppf(q, a=a, b=np.inf, loc=mu, scale=sdev)
    delta = (u > pi).astype(float)
    return torch.from_numpy(y_pos * delta).float()

likelihood(batch)

Compute the log-likelihood.

For y == 0: log(pi). For y > 0: log(1 - pi) + log N(y; mu, sigma) - log Phi(mu / sigma), where the last term is the log-normalizer of the truncated normal on (0, inf). Computed via the standard-normal CDF; for nonnegative data mu / sigma should stay in a numerically benign range.

Source code in scdesigner/src/scdesigner/distributions/zero_inflated_truncated_gaussian.py
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
137
def likelihood(self, batch) -> torch.Tensor:
    """Compute the log-likelihood.

    For y == 0: log(pi).
    For y > 0: log(1 - pi) + log N(y; mu, sigma) - log Phi(mu / sigma),
    where the last term is the log-normalizer of the truncated normal on
    (0, inf). Computed via the standard-normal CDF; for nonnegative
    data mu / sigma should stay in a numerically benign range.
    """
    y, x = batch
    params = self.predict(x)
    mu = params.get("mean")
    sigma = params.get("sdev")
    pi = params.get("zero_inflation")

    # zero inflation component
    log_pi = torch.log(pi.clamp(min=1e-10))
    log_1mpi = torch.log((1 - pi).clamp(min=1e-10))

    # truncated gaussian component
    gaussian_logpdf = -0.5 * (torch.log(2 * torch.pi * sigma ** 2) + ((y - mu) ** 2) / (sigma ** 2))
    std_normal = torch.distributions.Normal(0.0, 1.0)
    log_trunc_norm = torch.log(std_normal.cdf(mu / sigma).clamp(min=1e-30))  # log Phi(mu / sigma)
    tn_logpdf = gaussian_logpdf - log_trunc_norm

    # combine
    return torch.where((y == 0), log_pi, log_1mpi + tn_logpdf)

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

Return uniformized pseudo-observations for y given covariates x.

The CDF is 0 for y < 0, equals pi at y = 0 (atom), and pi + (1 - pi) * F_TN(y) for y > 0, where F_TN is the CDF of a normal N(mu, sigma^2) truncated to (0, inf). Values y == 0 are randomized uniformly within the atom [0, pi]; values y > 0 are deterministic.

Source code in scdesigner/src/scdesigner/distributions/zero_inflated_truncated_gaussian.py
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
def uniformize(self, y: torch.Tensor, x: Dict[str, torch.Tensor], epsilon=1e-6) -> torch.Tensor:
    """Return uniformized pseudo-observations for y given covariates x.

    The CDF is 0 for y < 0, equals pi at y = 0 (atom), and
    pi + (1 - pi) * F_TN(y) for y > 0, where F_TN is the CDF of a normal
    N(mu, sigma^2) truncated to (0, inf). Values y == 0 are randomized
    uniformly within the atom [0, pi]; values y > 0 are deterministic.
    """
    mu, sdev, pi, y = self._local_params(x, y)
    Phi_neg = norm.cdf(0.0, loc=mu, scale=sdev)  # = Phi(-mu / sigma)
    denom = 1.0 - Phi_neg                         # = Phi(mu / sigma)

    gsn = (norm.cdf(y, loc=mu, scale=sdev) - Phi_neg) / (denom + 1e-12)
    F_tn = np.where(y > 0, gsn, 0.0)

    # right and left CDF limits at y; equal for y > 0, separated by the
    # atom of width pi at y == 0.
    u1 = pi + (1 - pi) * F_tn
    u2 = np.where(y > 0, u1, 0.0)
    v = np.random.uniform(size=y.shape)

    u = np.clip(v * u1 + (1 - v) * u2, epsilon, 1 - epsilon)
    return torch.from_numpy(u).float()

PenalizedBernoulli(formula, *, penalties=(), device=None)

A Bernoulli marginal with coefficient penalties added to its training loss.

Parameters:

Name Type Description Default
formula dict of str to str, or str

Formula for the logit of the success probability.

required
penalties sequence of CoefficientPenalty

See :mod:scdesigner.distributions.penalties.

()
device device or str
None

Examples:

>>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
>>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
>>> model = PenalizedBernoulli("~ x", penalties=[penalty])
Source code in scdesigner/src/scdesigner/distributions/penalized_bernoulli.py
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
def PenalizedBernoulli(
    formula: Union[Dict[str, str], str],
    *,
    penalties: Sequence[CoefficientPenalty] = (),
    device=None,
) -> Bernoulli:
    """A Bernoulli marginal with coefficient penalties added to its training loss.

    Parameters
    ----------
    formula : dict of str to str, or str
        Formula for the logit of the success probability.
    penalties : sequence of CoefficientPenalty
        See :mod:`scdesigner.distributions.penalties`.
    device : torch.device or str, optional

    Examples
    --------
    >>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
    >>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
    >>> model = PenalizedBernoulli("~ x", penalties=[penalty])
    """
    return Bernoulli(formula, penalties=penalties, device=device)

PenalizedNegBin(formula, *, penalties=(), device=None)

:class:NegBin with penalty P added to the training loss

This is a regularized form of the NegBin marginal model. By default, this does not use Poisson IRLS during initialization, since regularized settings typically have high-dimensional covariates, which are unstable in an ordinary linear model. These initial Poisson IRLS steps can be added back by passing max_iter to fit.

Parameters:

Name Type Description Default
formula dict of str to str, or str
required
penalties sequence of CoefficientPenalty

See :mod:scdesigner.distributions.penalties.

()
device device or str
None

Examples:

>>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
>>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
>>> model = PenalizedNegBin({"mean": "~ x", "dispersion": "~ 1"}, penalties=[penalty])
>>> type(model).__name__
'NegBin'
Source code in scdesigner/src/scdesigner/distributions/penalized_negbin.py
 9
10
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
def PenalizedNegBin(
    formula: Union[Dict[str, str], str],
    *,
    penalties: Sequence[CoefficientPenalty] = (),
    device=None,
) -> NegBin:
    """:class:`NegBin` with penalty ``P`` added to the training loss

    This is a regularized form of the NegBin marginal model.  By default, this
    does not use Poisson IRLS during initialization, since regularized settings
    typically have high-dimensional covariates, which are unstable in an
    ordinary linear model. These initial Poisson IRLS steps can be added back by
    passing ``max_iter`` to ``fit``.

    Parameters
    ----------
    formula : dict of str to str, or str
    penalties : sequence of CoefficientPenalty
        See :mod:`scdesigner.distributions.penalties`.
    device : torch.device or str, optional

    Examples
    --------
    >>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
    >>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
    >>> model = PenalizedNegBin({"mean": "~ x", "dispersion": "~ 1"}, penalties=[penalty])
    >>> type(model).__name__
    'NegBin'
    """
    return NegBin(formula, penalties=penalties, device=device)

PenalizedZeroInflatedTruncatedGaussian(formula, *, prior_alpha=1.1, penalties=(), device=None)

A regularized zero-inflated truncated Gaussian marginal

The penalty P is added to the training loss, together with a Beta(prior_alpha, prior_alpha) prior term already present in :class:ZeroInflatedTruncatedGaussian.

Parameters:

Name Type Description Default
formula dict of str to str, or str
required
prior_alpha float

See :class:ZeroInflatedTruncatedGaussian.

1.1
penalties sequence of CoefficientPenalty

See :mod:scdesigner.distributions.penalties.

()
device device or str
None

Examples:

>>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
>>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
>>> model = PenalizedZeroInflatedTruncatedGaussian({"mean": "~ x"}, penalties=[penalty])
>>> type(model).__name__
'ZeroInflatedTruncatedGaussian'
Source code in scdesigner/src/scdesigner/distributions/penalized_zero_inflated_truncated_gaussian.py
 9
10
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
def PenalizedZeroInflatedTruncatedGaussian(
    formula: Union[Dict[str, str], str],
    *,
    prior_alpha: float = 1.1,
    penalties: Sequence[CoefficientPenalty] = (),
    device=None,
) -> ZeroInflatedTruncatedGaussian:
    """A regularized zero-inflated truncated Gaussian marginal

    The penalty ``P`` is added to the training loss, together with a
    Beta(``prior_alpha``, ``prior_alpha``) prior term already present in
    :class:`ZeroInflatedTruncatedGaussian`.

    Parameters
    ----------
    formula : dict of str to str, or str
    prior_alpha : float
        See :class:`ZeroInflatedTruncatedGaussian`.
    penalties : sequence of CoefficientPenalty
        See :mod:`scdesigner.distributions.penalties`.
    device : torch.device or str, optional

    Examples
    --------
    >>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
    >>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
    >>> model = PenalizedZeroInflatedTruncatedGaussian({"mean": "~ x"}, penalties=[penalty])
    >>> type(model).__name__
    'ZeroInflatedTruncatedGaussian'
    """
    return ZeroInflatedTruncatedGaussian(
        formula, prior_alpha=prior_alpha, penalties=penalties, device=device
    )