scvi.external.drvi.DRVIModule

class scvi.external.drvi.DRVIModule(n_input, n_split_latent=None, split_method='split_map', n_split_output='auto', split_aggregation='logsumexp', decoder_reuse_weights='everywhere', n_latent=128, n_hidden=256, n_layers=1, dropout_rate=0.1, n_continuous_cov=0, n_cats_per_cov=None, dispersion='gene', gene_likelihood='pnb', deeply_inject_covariates=False, use_batch_norm='none', use_layer_norm='both', activation_fn='elu', mean_activation=None, extra_encoder_kwargs=None, extra_decoder_kwargs=None, **kwargs)

Bases: VAE

PyTorch module for DRVI: a disentangled-representation VAE with an additive split decoder.

Subclasses VAE, reusing its encoder, inference, loss (reconstruction + KL(qz || N(0, I))) and likelihoods unchanged. The only deviation is the decoder: the latent is split into n_split_latent groups that are decoded independently and aggregated, which is what gives DRVI its interpretable latent factors. See DecoderDRVI.

Parameters:

• n_input (int) – Number of input genes.

• n_split_latent (int | None (default: None)) – Number of latent splits. None or -1 splits every latent dimension (n_latent), which is the default disentangled setting.

• split_method (Literal['split_mask', 'split_map'] (default: 'split_map')) – Latent-to-split mapping, one of "split_mask" or "split_map". See DecoderDRVI.

• n_split_output (Union[int, Literal['auto']] (default: 'auto')) – Per-split projection output width, i.e. the input dimension to each split’s decoder body. "auto" (default) uses n_latent. For "split_map" this is the learned per-split projection size; for "split_mask" it must equal n_latent. See DecoderDRVI.

• split_aggregation (Literal['mean', 'logsumexp'] (default: 'logsumexp')) – Per-split aggregation, one of "mean" or "logsumexp". See DecoderDRVI.

• decoder_reuse_weights (Literal['everywhere', 'last', 'hidden', 'nowhere', 'hidden_except_first'] (default: 'everywhere')) – Decoder weight-sharing policy across splits, one of "everywhere" (default), "hidden", "last", "hidden_except_first" or "nowhere". See DecoderDRVI.

• n_latent (int (default: 128)) – Dimensionality of the latent space.

• dropout_rate (float (default: 0.1)) – Dropout rate for the encoder hidden layers. The decoder uses no dropout.

• gene_likelihood (Literal['nb', 'pnb', 'zinb', 'poisson', 'normal', 'normal_unit_var'] (default: 'pnb')) –

  Reconstruction likelihood. One of:

  • "nb" (default) - negative binomial (mean = library * softmax(decoder)).

  • "pnb" - parametrized negative binomial: same mean, but modeled in log space via LogNegativeBinomial. This is the numerically stable, additive form that composes the per-split log contributions of the decoder (recommended with split_aggregation="logsumexp").

  • "zinb" - zero-inflated negative binomial.

  • "poisson" - Poisson.

  • "normal" - Gaussian with the mean modeled directly (no library/softmax) and per-gene variance modeled in log space; use with continuous (e.g. log-normalized) data.

  • "normal_unit_var" - Gaussian with unit variance.

• activation_fn (str | type[Module] (default: 'elu')) – Hidden-layer activation for both the encoder and the split decoder. Either a name (one of "elu" (default, DRVI’s choice),``”relu”, or an ``nn.Module subclass.

• mean_activation (str | type[Module] | Module | None (default: None)) – Activation applied to the encoder’s latent mean q_m. None (default) is a no-op; a non-identity activation (e.g. "ReLU") constrains the latent space (e.g. non-negative means). Accepts the name of a torch.nn class with an optional positional argument after an underscore (e.g. "ReLU", "GELU", "ELU_0.5", "LeakyReLU_0.2"), an nn.Module subclass, or an instance. Applied only to the latent encoder, not the library encoder.

• extra_encoder_kwargs (dict | None (default: None)) – Extra keyword arguments for the encoder FCLayers.

• extra_decoder_kwargs (dict | None (default: None)) – Extra keyword arguments for the decoder SplitFCLayers.

• **kwargs – Additional keyword arguments for VAE.

Attributes table

training

Methods table

generative(z, library, batch_index[, ...])

Run the generative process via the additive decoder.

Attributes

DRVIModule.training: bool

Methods

DRVIModule.generative(z, library, batch_index, cont_covs=None, cat_covs=None, size_factor=None, y=None, transform_batch=None)

Run the generative process via the additive decoder.

Mirrors scvi.module.VAE.generative() but passes continuous covariates to the decoder separately (so the split transformation only sees the latent dimensions). With the embedding batch representation, the learned batch embedding is injected into each split as an extra continuous covariate.

Return type:

dict[str, Distribution | Tensor | None]