Skip to content

recipes

Simulators composed from a marginal, a copula, and spatial terms.

PenalizedBernoulliCopula(mean_formula='~ 1', copula_formula='~ 1', *, penalties=(), estimator=None, top_k=None, device=None)

A Bernoulli copula simulator with user-specified coefficient penalties.

Parameters:

Name Type Description Default
mean_formula str

Formula for the logit of the success probability.

'~ 1'
copula_formula str
'~ 1'
penalties sequence of CoefficientPenalty

See :mod:scdesigner.distributions.penalties.

()
estimator

Passed to :class:StandardCopula.

None
top_k

Passed to :class:StandardCopula.

None
device device or str

Marginal device.

None

Examples:

>>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
>>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
>>> sim = PenalizedBernoulliCopula("~ x", penalties=[penalty])
>>> sim.fit(adata)
Source code in scdesigner/src/scdesigner/simulators/recipes.py
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
def PenalizedBernoulliCopula(
    mean_formula: str = "~ 1",
    copula_formula: str = "~ 1",
    *,
    penalties: Sequence[CoefficientPenalty] = (),
    estimator=None,
    top_k: Optional[int] = None,
    device=None,
) -> SCD3Simulator:
    """A Bernoulli copula simulator with user-specified coefficient penalties.

    Parameters
    ----------
    mean_formula : str
        Formula for the logit of the success probability.
    copula_formula : str
    penalties : sequence of CoefficientPenalty
        See :mod:`scdesigner.distributions.penalties`.
    estimator, top_k
        Passed to :class:`StandardCopula`.
    device : torch.device or str, optional
        Marginal device.

    Examples
    --------
    >>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
    >>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
    >>> sim = PenalizedBernoulliCopula("~ x", penalties=[penalty])
    >>> sim.fit(adata)  # doctest: +SKIP
    """
    marginal = PenalizedBernoulli({"mean": mean_formula}, penalties=penalties, device=device)
    copula = StandardCopula(copula_formula, estimator=estimator, top_k=top_k)
    return SCD3Simulator(marginal, copula)

PenalizedNegBinCopula(mean_formula='~ 1', dispersion_formula='~ 1', copula_formula='~ 1', *, penalties=(), cap_at_observed_max=True, estimator=None, top_k=None, device=None)

A regularized negative binomial simulator

The simulator is well-suited to count data with many covariates relative to the number of cells.

Parameters:

Name Type Description Default
mean_formula str
'~ 1'
dispersion_formula str
'~ 1'
copula_formula str
'~ 1'
penalties sequence of CoefficientPenalty

See :mod:scdesigner.distributions.penalties.

()
cap_at_observed_max bool

Cap samples with :class:~scdesigner.simulators.output.ObservedMaxCap.

True
estimator

Passed to :class:StandardCopula.

None
top_k

Passed to :class:StandardCopula.

None
device device or str

Marginal device.

None

Examples:

>>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
>>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
>>> sim = PenalizedNegBinCopula("~ x", penalties=[penalty])
>>> sim.fit(adata)
Source code in scdesigner/src/scdesigner/simulators/recipes.py
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
def PenalizedNegBinCopula(
    mean_formula: str = "~ 1",
    dispersion_formula: str = "~ 1",
    copula_formula: str = "~ 1",
    *,
    penalties: Sequence[CoefficientPenalty] = (),
    cap_at_observed_max: bool = True,
    estimator=None,
    top_k: Optional[int] = None,
    device=None,
) -> SCD3Simulator:
    """A regularized negative binomial simulator

    The simulator is well-suited to count data with many covariates relative to
    the number of cells.

    Parameters
    ----------
    mean_formula, dispersion_formula, copula_formula : str
    penalties : sequence of CoefficientPenalty
        See :mod:`scdesigner.distributions.penalties`.
    cap_at_observed_max : bool
        Cap samples with :class:`~scdesigner.simulators.output.ObservedMaxCap`.
    estimator, top_k
        Passed to :class:`StandardCopula`.
    device : torch.device or str, optional
        Marginal device.

    Examples
    --------
    >>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
    >>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
    >>> sim = PenalizedNegBinCopula("~ x", penalties=[penalty])
    >>> sim.fit(adata)  # doctest: +SKIP
    """
    marginal = PenalizedNegBin(
        {"mean": mean_formula, "dispersion": dispersion_formula},
        penalties=penalties,
        device=device,
    )
    copula = StandardCopula(copula_formula, estimator=estimator, top_k=top_k)
    return SCD3Simulator(
        marginal,
        copula,
        output_transform=ObservedMaxCap() if cap_at_observed_max else None,
    )

PenalizedZeroInflatedTruncatedGaussianCopula(mean_formula='~ 1', sdev_formula='~ 1', zero_inflation_formula='~ 1', copula_formula='~ 1', *, penalties=(), prior_alpha=1.1, cap_at_observed_max=False, estimator=None, top_k=None, device=None)

A regularized zero-inflated truncated Gaussian model

This can be used for nonnegative continuous data and when there are many covariates relative to the number of cells.

Parameters:

Name Type Description Default
mean_formula str
'~ 1'
sdev_formula str
'~ 1'
zero_inflation_formula str
'~ 1'
copula_formula str
'~ 1'
penalties sequence of CoefficientPenalty

See :mod:scdesigner.distributions.penalties.

()
prior_alpha float

See :class:ZeroInflatedTruncatedGaussian.

1.1
cap_at_observed_max bool

Cap samples with :class:~scdesigner.simulators.output.ObservedMaxCap.

False
estimator

Passed to :class:StandardCopula.

None
top_k

Passed to :class:StandardCopula.

None
device device or str

Marginal device.

None

Examples:

>>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
>>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
>>> sim = PenalizedZeroInflatedTruncatedGaussianCopula("~ x", penalties=[penalty])
>>> sim.fit(adata)
Source code in scdesigner/src/scdesigner/simulators/recipes.py
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
def PenalizedZeroInflatedTruncatedGaussianCopula(
    mean_formula: str = "~ 1",
    sdev_formula: str = "~ 1",
    zero_inflation_formula: str = "~ 1",
    copula_formula: str = "~ 1",
    *,
    penalties: Sequence[CoefficientPenalty] = (),
    prior_alpha: float = 1.1,
    cap_at_observed_max: bool = False,
    estimator=None,
    top_k: Optional[int] = None,
    device=None,
) -> SCD3Simulator:
    """A regularized zero-inflated truncated Gaussian model

    This can be used for nonnegative continuous data and when there are many
    covariates relative to the number of cells.

    Parameters
    ----------
    mean_formula, sdev_formula, zero_inflation_formula, copula_formula : str
    penalties : sequence of CoefficientPenalty
        See :mod:`scdesigner.distributions.penalties`.
    prior_alpha : float
        See :class:`ZeroInflatedTruncatedGaussian`.
    cap_at_observed_max : bool
        Cap samples with :class:`~scdesigner.simulators.output.ObservedMaxCap`.
    estimator, top_k
        Passed to :class:`StandardCopula`.
    device : torch.device or str, optional
        Marginal device.

    Examples
    --------
    >>> from scdesigner.distributions.penalties import CoefficientPenalty, QuadraticPenalty
    >>> penalty = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
    >>> sim = PenalizedZeroInflatedTruncatedGaussianCopula("~ x", penalties=[penalty])
    >>> sim.fit(adata)  # doctest: +SKIP
    """
    marginal = PenalizedZeroInflatedTruncatedGaussian(
        {"mean": mean_formula, "sdev": sdev_formula, "zero_inflation": zero_inflation_formula},
        prior_alpha=prior_alpha,
        penalties=penalties,
        device=device,
    )
    copula = StandardCopula(copula_formula, estimator=estimator, top_k=top_k)
    return SCD3Simulator(
        marginal,
        copula,
        output_transform=ObservedMaxCap() if cap_at_observed_max else None,
    )

SpatialBernoulliCopula(mean_formula='~ 1', copula_formula='~ 1', *, mean_df=15, basis='gp', standardize=True, lam=1.0, spatial_cols=('spatial1', 'spatial2'), estimator=None, top_k=None, device=None, **basis_kwargs)

A Bernoulli simulator with a penalized spatial logit of success probability.

Parameters:

Name Type Description Default
mean_formula str

Nonspatial part of the logit formula.

'~ 1'
copula_formula str
'~ 1'
mean_df int

Number of spatial basis columns.

15
basis (gp, tps)
"gp"
standardize bool

Rescale basis columns by their training standard deviations.

True
lam float

Strength of the inverse-mean-weighted quadratic penalty; see :mod:scdesigner.distributions.penalties.

1.0
spatial_cols tuple of str

Coordinate columns in adata.obs.

('spatial1', 'spatial2')
estimator

Passed to :class:StandardCopula.

None
top_k

Passed to :class:StandardCopula.

None
device device or str

Marginal device.

None
**basis_kwargs

Passed to the basis, e.g. n_landmarks or length_scale.

{}

Examples:

>>> sim = SpatialBernoulliCopula("~ 0 + cell_type", basis="tps")
>>> sim.fit(adata)
Source code in scdesigner/src/scdesigner/simulators/recipes.py
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
def SpatialBernoulliCopula(
    mean_formula: str = "~ 1",
    copula_formula: str = "~ 1",
    *,
    mean_df: int = 15,
    basis: str = "gp",
    standardize: bool = True,
    lam: float = 1.0,
    spatial_cols: Tuple[str, str] = ("spatial1", "spatial2"),
    estimator=None,
    top_k: Optional[int] = None,
    device=None,
    **basis_kwargs,
) -> SCD3Simulator:
    """A Bernoulli simulator with a penalized spatial logit of success probability.

    Parameters
    ----------
    mean_formula : str
        Nonspatial part of the logit formula.
    copula_formula : str
    mean_df : int
        Number of spatial basis columns.
    basis : {"gp", "tps"}
    standardize : bool
        Rescale basis columns by their training standard deviations.
    lam : float
        Strength of the inverse-mean-weighted quadratic penalty; see
        :mod:`scdesigner.distributions.penalties`.
    spatial_cols : tuple of str
        Coordinate columns in ``adata.obs``.
    estimator, top_k
        Passed to :class:`StandardCopula`.
    device : torch.device or str, optional
        Marginal device.
    **basis_kwargs
        Passed to the basis, e.g. ``n_landmarks`` or ``length_scale``.

    Examples
    --------
    >>> sim = SpatialBernoulliCopula("~ 0 + cell_type", basis="tps")
    >>> sim.fit(adata)  # doctest: +SKIP
    """
    terms = {"mean": SpatialTerm(
        BASES[basis](df=mean_df, standardize=standardize, **basis_kwargs),
        QuadraticPenalty(lam=lam, weighting="inverse_mean"),
    )}
    marginal = Bernoulli({"mean": mean_formula}, device=device)
    copula = StandardCopula(copula_formula, estimator=estimator, top_k=top_k)
    return spatial_copula(marginal, terms, copula=copula, spatial_cols=spatial_cols)

SpatialNegBinCopula(mean_formula='~ 1', dispersion_formula='~ 1', copula_formula='~ 1', *, mean_df=100, disp_df=None, basis='gp', standardize=True, lam=1.0, lam_disp=1.0, spatial_cols=('spatial1', 'spatial2'), cap_at_observed_max=True, estimator=None, top_k=None, device=None, **basis_kwargs)

A negative binomial simulator suited to spatial data

This is a convenience wrapper of spatial_copula specialized to negative binomial marginal models. It automatically constructs the design matrix and applies regularization terms in a way that suits spatial count data.

Internally, we construct SpatialTerm(basis(df, standardize, **basis_kwargs), QuadraticPenalty(lam, "inverse_mean")) objects, which are then fed in to :func:spatial_copula.

We do not use a Poisson IRLS initialization for spatial models. This is because the spatial basis greatly increases the problem dimension, which destabilizes ordinary regression fits. To use this initialization, you may set max_iter larger than zero in your call to :meth:fit.

Parameters:

Name Type Description Default
mean_formula str

Nonspatial part of each parameter's formula.

'~ 1'
dispersion_formula str

Nonspatial part of each parameter's formula.

'~ 1'
copula_formula str
'~ 1'
mean_df int

Level of complexity for the mean and dispersion functions. Larger df corresponds to higher complexity. Setting disp_df=None means that the dispersion does not depend on the spatial coordinate.

100
disp_df int

Level of complexity for the mean and dispersion functions. Larger df corresponds to higher complexity. Setting disp_df=None means that the dispersion does not depend on the spatial coordinate.

100
basis (gp, tps)

Whether to use a Gaussian process (:class:GPBasis) or thin-plate spline (:class:TPSBasis) basis for the mean and (optionally) dispersion parameters

"gp"
standardize bool
True
lam float

Penalty strength for the mean and dispersion terms.

1.0
lam_disp float

Penalty strength for the mean and dispersion terms.

1.0
spatial_cols tuple of str
('spatial1', 'spatial2')
cap_at_observed_max bool
True
estimator

Passed to :class:StandardCopula.

None
top_k

Passed to :class:StandardCopula.

None
device device or str

Marginal device.

None
**basis_kwargs

Passed to both bases, e.g. n_landmarks or length_fraction.

{}

Examples:

>>> sim = SpatialNegBinCopula("~ 0 + cell_type", basis="tps", disp_df=5)
>>> sim.fit(adata)
Source code in scdesigner/src/scdesigner/simulators/recipes.py
 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
def SpatialNegBinCopula(
    mean_formula: str = "~ 1",
    dispersion_formula: str = "~ 1",
    copula_formula: str = "~ 1",
    *,
    mean_df: int = 100,
    disp_df: Optional[int] = None,
    basis: str = "gp",
    standardize: bool = True,
    lam: float = 1.0,
    lam_disp: float = 1.0,
    spatial_cols: Tuple[str, str] = ("spatial1", "spatial2"),
    cap_at_observed_max: bool = True,
    estimator=None,
    top_k: Optional[int] = None,
    device=None,
    **basis_kwargs,
) -> SCD3Simulator:
    """A negative binomial simulator suited to spatial data

    This is a convenience wrapper of `spatial_copula` specialized to negative
    binomial marginal models. It automatically constructs the design matrix and
    applies regularization terms in a way that suits spatial count data.

    Internally, we construct ``SpatialTerm(basis(df, standardize,
    **basis_kwargs), QuadraticPenalty(lam, "inverse_mean"))`` objects, which are
    then fed in to :func:`spatial_copula`.

    We do not use a Poisson IRLS initialization for spatial models. This is
    because the spatial basis greatly increases the problem dimension, which
    destabilizes ordinary regression fits. To use this initialization, you may
    set ``max_iter`` larger than zero in your call to :meth:`fit`.

    Parameters
    ----------
    mean_formula, dispersion_formula : str
        Nonspatial part of each parameter's formula.
    copula_formula : str
    mean_df, disp_df : int
        Level of complexity for the mean and dispersion functions. Larger ``df``
        corresponds to higher complexity.  Setting ``disp_df=None`` means that
        the dispersion does not depend on the spatial coordinate.
    basis : {"gp", "tps"}
       Whether to use a Gaussian process  (:class:`GPBasis`) or thin-plate
       spline (:class:`TPSBasis`) basis for the mean and (optionally) dispersion
       parameters
    standardize : bool
    lam, lam_disp : float
        Penalty strength for the mean and dispersion terms.
    spatial_cols : tuple of str
    cap_at_observed_max : bool
    estimator, top_k
        Passed to :class:`StandardCopula`.
    device : torch.device or str, optional
        Marginal device.
    **basis_kwargs
        Passed to both bases, e.g. ``n_landmarks`` or ``length_fraction``.

    Examples
    --------
    >>> sim = SpatialNegBinCopula("~ 0 + cell_type", basis="tps", disp_df=5)
    >>> sim.fit(adata)  # doctest: +SKIP
    """

    def term(df, strength):
        return SpatialTerm(
            BASES[basis](df=df, standardize=standardize, **basis_kwargs),
            QuadraticPenalty(lam=strength, weighting="inverse_mean"),
        )

    terms = {"mean": term(mean_df, lam)}
    if disp_df is not None:
        terms["dispersion"] = term(disp_df, lam_disp)

    marginal = NegBin({"mean": mean_formula, "dispersion": dispersion_formula}, device=device)
    copula = StandardCopula(copula_formula, estimator=estimator, top_k=top_k)
    return spatial_copula(
        marginal,
        terms,
        copula=copula,
        spatial_cols=spatial_cols,
        cap_at_observed_max=cap_at_observed_max,
    )

SpatialZeroInflatedTruncatedGaussianCopula(mean_formula='~ 1', sdev_formula='~ 1', zero_inflation_formula='~ 1', copula_formula='~ 1', *, mean_df=100, sdev_df=None, zi_df=15, basis='gp', standardize=True, lam=1.0, lam_sdev=1.0, lam_zi=1.0, prior_alpha=1.1, spatial_cols=('spatial1', 'spatial2'), cap_at_observed_max=False, estimator=None, top_k=None, device=None, **basis_kwargs)

A zero-inflated truncated gaussian model for spatial data

This applies :func:spatial_copula to a :class:ZeroInflatedTruncatedGaussian marginal. It is appropriate for spatial modeling of already normalized data. The spatial coordinates can enter into the mean, dispersion, or zero-inflation parameters.

Parameters:

Name Type Description Default
mean_formula str

Nonspatial part of each parameter's formula.

'~ 1'
sdev_formula str

Nonspatial part of each parameter's formula.

'~ 1'
zero_inflation_formula str

Nonspatial part of each parameter's formula.

'~ 1'
copula_formula str
'~ 1'
mean_df int

Basis columns of the latent-mean term.

100
sdev_df int or None

Basis columns of the standard-deviation and zero-inflation terms; None omits the term. zi_df is set by default because zeros arise only from the zero-inflation probability.

None
zi_df int or None

Basis columns of the standard-deviation and zero-inflation terms; None omits the term. zi_df is set by default because zeros arise only from the zero-inflation probability.

None
basis (gp, tps)

:class:GPBasis or :class:TPSBasis, for every term.

"gp"
standardize bool

Divide basis columns by their training standard deviations.

True
lam float

Penalty strength of each term; see :mod:scdesigner.distributions.penalties.

1.0
lam_sdev float

Penalty strength of each term; see :mod:scdesigner.distributions.penalties.

1.0
lam_zi float

Penalty strength of each term; see :mod:scdesigner.distributions.penalties.

1.0
prior_alpha float

See :class:ZeroInflatedTruncatedGaussian.

1.1
spatial_cols tuple of str

Coordinate columns of adata.obs.

('spatial1', 'spatial2')
cap_at_observed_max bool

Cap samples with :class:~scdesigner.simulators.output.ObservedMaxCap.

False
estimator

Passed to :class:StandardCopula.

None
top_k

Passed to :class:StandardCopula.

None
device device or str

Marginal device.

None
**basis_kwargs

Passed to every basis, e.g. n_landmarks or length_fraction.

{}

Examples:

>>> from scdesigner import datasets
>>> sim = SpatialZeroInflatedTruncatedGaussianCopula(
...     spatial_cols=("UMAP1_integrated", "UMAP2_integrated"))
>>> sim.fit(datasets.scgemrna())
Source code in scdesigner/src/scdesigner/simulators/recipes.py
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
def SpatialZeroInflatedTruncatedGaussianCopula(
    mean_formula: str = "~ 1",
    sdev_formula: str = "~ 1",
    zero_inflation_formula: str = "~ 1",
    copula_formula: str = "~ 1",
    *,
    mean_df: int = 100,
    sdev_df: Optional[int] = None,
    zi_df: Optional[int] = 15,
    basis: str = "gp",
    standardize: bool = True,
    lam: float = 1.0,
    lam_sdev: float = 1.0,
    lam_zi: float = 1.0,
    prior_alpha: float = 1.1,
    spatial_cols: Tuple[str, str] = ("spatial1", "spatial2"),
    cap_at_observed_max: bool = False,
    estimator=None,
    top_k: Optional[int] = None,
    device=None,
    **basis_kwargs,
) -> SCD3Simulator:
    """A zero-inflated truncated gaussian model for spatial data

    This applies :func:`spatial_copula` to a
    :class:`ZeroInflatedTruncatedGaussian` marginal. It is appropriate for
    spatial modeling of already normalized data. The spatial coordinates can
    enter into the mean, dispersion, or zero-inflation parameters.

    Parameters
    ----------
    mean_formula, sdev_formula, zero_inflation_formula : str
        Nonspatial part of each parameter's formula.
    copula_formula : str
    mean_df : int
        Basis columns of the latent-mean term.
    sdev_df, zi_df : int or None
        Basis columns of the standard-deviation and zero-inflation terms;
        ``None`` omits the term. ``zi_df`` is set by default because zeros
        arise only from the zero-inflation probability.
    basis : {"gp", "tps"}
        :class:`GPBasis` or :class:`TPSBasis`, for every term.
    standardize : bool
        Divide basis columns by their training standard deviations.
    lam, lam_sdev, lam_zi : float
        Penalty strength of each term; see
        :mod:`scdesigner.distributions.penalties`.
    prior_alpha : float
        See :class:`ZeroInflatedTruncatedGaussian`.
    spatial_cols : tuple of str
        Coordinate columns of ``adata.obs``.
    cap_at_observed_max : bool
        Cap samples with :class:`~scdesigner.simulators.output.ObservedMaxCap`.
    estimator, top_k
        Passed to :class:`StandardCopula`.
    device : torch.device or str, optional
        Marginal device.
    **basis_kwargs
        Passed to every basis, e.g. ``n_landmarks`` or ``length_fraction``.

    Examples
    --------
    >>> from scdesigner import datasets
    >>> sim = SpatialZeroInflatedTruncatedGaussianCopula(
    ...     spatial_cols=("UMAP1_integrated", "UMAP2_integrated"))
    >>> sim.fit(datasets.scgemrna())  # doctest: +SKIP
    """

    def term(df, strength):
        return SpatialTerm(
            BASES[basis](df=df, standardize=standardize, **basis_kwargs),
            QuadraticPenalty(lam=strength, weighting="inverse_mean"),
        )

    terms = {"mean": term(mean_df, lam)}
    if sdev_df is not None:
        terms["sdev"] = term(sdev_df, lam_sdev)
    if zi_df is not None:
        terms["zero_inflation"] = term(zi_df, lam_zi)

    marginal = ZeroInflatedTruncatedGaussian(
        {"mean": mean_formula, "sdev": sdev_formula, "zero_inflation": zero_inflation_formula},
        prior_alpha=prior_alpha,
        device=device,
    )
    copula = StandardCopula(copula_formula, estimator=estimator, top_k=top_k)
    return spatial_copula(
        marginal,
        terms,
        copula=copula,
        spatial_cols=spatial_cols,
        cap_at_observed_max=cap_at_observed_max,
    )

spatial_copula(marginal, terms, *, copula=None, spatial_cols=('spatial1', 'spatial2'), cap_at_observed_max=False)

:class:SCD3Simulator with spatial basis columns added

This is a light wrapper of the SCD3Simulator that adds spatial design columns. Philosophically, we think of this as a part of a "recipe" approach to combining simulation properties. Earlier, we layered penalties onto the marginal model. At this step, we layer on spatial design matrices.

Parameters:

Name Type Description Default
marginal NegBin, Bernoulli, or ZeroInflatedTruncatedGaussian

Copied; its formula and penalties are the nonspatial base.

required
terms mapping of str to SpatialTerm

Term per marginal parameter; see :class:~scdesigner.data.spatial.SpatialDesign.

required
copula Copula

Copied. Defaults to StandardCopula("~ 1").

None
spatial_cols tuple of str
('spatial1', 'spatial2')
cap_at_observed_max bool

Cap samples with :class:~scdesigner.simulators.output.ObservedMaxCap. In earlier experiments, we found that this prevented extreme outliers that happen in high-dimensional negbin models. Must be False for Bernoulli marginals.

False

Examples:

>>> from scdesigner.data import GPBasis, SpatialTerm
>>> from scdesigner.distributions import NegBin
>>> from scdesigner.distributions.penalties import QuadraticPenalty
>>> term = SpatialTerm(GPBasis(df=15, standardize=True), QuadraticPenalty(lam=1.0))
>>> sim = spatial_copula(NegBin({"mean": "~ 1", "dispersion": "~ 1"}), {"mean": term})
>>> sim.fit(adata)
Source code in scdesigner/src/scdesigner/simulators/recipes.py
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
def spatial_copula(
    marginal: NegBin | Bernoulli | ZeroInflatedTruncatedGaussian,
    terms: Mapping[str, SpatialTerm],
    *,
    copula: Optional[Copula] = None,
    spatial_cols: Tuple[str, str] = ("spatial1", "spatial2"),
    cap_at_observed_max: bool = False,
) -> SCD3Simulator:
    """:class:`SCD3Simulator` with spatial basis columns added

    This is a light wrapper of the SCD3Simulator that adds spatial design
    columns. Philosophically, we think of this as a part of a "recipe" approach
    to combining simulation properties. Earlier, we layered penalties onto the
    marginal model. At this step, we layer on spatial design matrices.

    Parameters
    ----------
    marginal : NegBin, Bernoulli, or ZeroInflatedTruncatedGaussian
        Copied; its formula and penalties are the nonspatial base.
    terms : mapping of str to SpatialTerm
        Term per marginal parameter; see
        :class:`~scdesigner.data.spatial.SpatialDesign`.
    copula : Copula, optional
        Copied. Defaults to ``StandardCopula("~ 1")``.
    spatial_cols : tuple of str
    cap_at_observed_max : bool
        Cap samples with
        :class:`~scdesigner.simulators.output.ObservedMaxCap`. In earlier
        experiments, we found that this prevented extreme outliers that happen
        in high-dimensional negbin models. Must be False for Bernoulli marginals.

    Examples
    --------
    >>> from scdesigner.data import GPBasis, SpatialTerm
    >>> from scdesigner.distributions import NegBin
    >>> from scdesigner.distributions.penalties import QuadraticPenalty
    >>> term = SpatialTerm(GPBasis(df=15, standardize=True), QuadraticPenalty(lam=1.0))
    >>> sim = spatial_copula(NegBin({"mean": "~ 1", "dispersion": "~ 1"}), {"mean": term})
    >>> sim.fit(adata)  # doctest: +SKIP
    """
    if type(marginal) not in (NegBin, Bernoulli, ZeroInflatedTruncatedGaussian):
        raise NotImplementedError(
            "spatial_copula currently supports only NegBin, Bernoulli, and "
            "ZeroInflatedTruncatedGaussian marginals."
        )

    marginal = copy.deepcopy(marginal)
    copula = StandardCopula("~ 1") if copula is None else copy.deepcopy(copula)
    return SCD3Simulator(
        marginal,
        copula,
        observation_transform=SpatialDesign(marginal.formula, terms, spatial_cols),
        output_transform=ObservedMaxCap() if cap_at_observed_max else None,
    )