spateo.external.MERFISHVI._module

Attributes

logger

Classes

VAE	Variational auto-encoder :cite:p:`Lopez18`.
LDVAE	Linear-decoded Variational auto-encoder model.

Module Contents

spateo.external.MERFISHVI._module.logger = None

class spateo.external.MERFISHVI._module.VAE(n_input: int, n_batch: int = 0, n_labels: int = 0, n_hidden: int = 128, n_latent: int = 10, n_layers: int = 1, n_continuous_cov: int = 0, n_cats_per_cov: list[int] | None = None, dropout_rate: float = 0.1, dispersion: Literal['gene', 'gene-batch', 'gene-label', 'gene-cell'] = 'gene', log_variational: bool = True, gene_likelihood: Literal['zinb', 'nb', 'poisson'] = 'zinb', latent_distribution: Literal['normal', 'ln'] = 'normal', encode_covariates: bool = False, deeply_inject_covariates: bool = True, batch_representation: Literal['one-hot', 'embedding'] = 'one-hot', use_batch_norm: Literal['encoder', 'decoder', 'none', 'both'] = 'both', use_layer_norm: Literal['encoder', 'decoder', 'none', 'both'] = 'none', use_size_factor_key: bool = False, use_observed_lib_size: bool = True, extra_payload_autotune: bool = False, library_log_means: numpy.ndarray | None = None, library_log_vars: numpy.ndarray | None = None, var_activation: collections.abc.Callable[[torch.Tensor], torch.Tensor] = None, extra_encoder_kwargs: dict | None = None, extra_decoder_kwargs: dict | None = None, batch_embedding_kwargs: dict | None = None)

Bases: scvi.module.base.EmbeddingModuleMixin, scvi.module.base.BaseMinifiedModeModuleClass

Variational auto-encoder :cite:p:`Lopez18`.

Parameters:

n_input

Number of input features.

n_batch

Number of batches. If 0, no batch correction is performed.

n_labels

Number of labels.

n_hidden

Number of nodes per hidden layer. Passed into Encoder and DecoderSCVI.

n_latent

Dimensionality of the latent space.

n_layers

Number of hidden layers. Passed into Encoder and DecoderSCVI.

n_continuous_cov

Number of continuous covariates.

n_cats_per_cov

A list of integers containing the number of categories for each categorical covariate.

dropout_rate

Dropout rate. Passed into Encoder but not DecoderSCVI.

dispersion

Flexibility of the dispersion parameter when gene_likelihood is either "nb" or "zinb". One of the following:

• "gene": parameter is constant per gene across cells.

• "gene-batch": parameter is constant per gene per batch.

• "gene-label": parameter is constant per gene per label.

• "gene-cell": parameter is constant per gene per cell.

log_variational

If True, use log1p() on input data before encoding for numerical stability (not normalization).

gene_likelihood

Distribution to use for reconstruction in the generative process. One of the following:

• "nb": NegativeBinomial.

• "zinb": ZeroInflatedNegativeBinomial.

• "poisson": Poisson.

• "normal": Normal.

latent_distribution

Distribution to use for the latent space. One of the following:

• "normal": isotropic normal.

• "ln": logistic normal with normal params N(0, 1).

encode_covariates

If True, covariates are concatenated to gene expression prior to passing through the encoder(s). Else, only gene expression is used.

deeply_inject_covariates

If True and n_layers > 1, covariates are concatenated to the outputs of hidden layers in the encoder(s) (if encoder_covariates is True) and the decoder prior to passing through the next layer.

batch_representation

EXPERIMENTAL Method for encoding batch information. One of the following:

• "one-hot": represent batches with one-hot encodings.

• "embedding": represent batches with continuously-valued embeddings using Embedding.

Note that batch representations are only passed into the encoder(s) if encode_covariates is True.

use_batch_norm

Specifies where to use BatchNorm1d in the model. One of the following:

• "none": don’t use batch norm in either encoder(s) or decoder.

• "encoder": use batch norm only in the encoder(s).

• "decoder": use batch norm only in the decoder.

• "both": use batch norm in both encoder(s) and decoder.

Note: if use_layer_norm is also specified, both will be applied (first BatchNorm1d, then LayerNorm).

use_layer_norm

Specifies where to use LayerNorm in the model. One of the following:

• "none": don’t use layer norm in either encoder(s) or decoder.

• "encoder": use layer norm only in the encoder(s).

• "decoder": use layer norm only in the decoder.

• "both": use layer norm in both encoder(s) and decoder.

Note: if use_batch_norm is also specified, both will be applied (first BatchNorm1d, then LayerNorm).

use_size_factor_key

If True, use the obs column as defined by the size_factor_key parameter in the model’s setup_anndata method as the scaling factor in the mean of the conditional distribution. Takes priority over use_observed_lib_size.

use_observed_lib_size

If True, use the observed library size for RNA as the scaling factor in the mean of the conditional distribution.

extra_payload_autotune

If True, will return extra matrices in the loss output to be used during autotune

library_log_means

ndarray of shape (1, n_batch) of means of the log library sizes that parameterize the prior on library size if use_size_factor_key is False and use_observed_lib_size is False.

library_log_vars

ndarray of shape (1, n_batch) of variances of the log library sizes that parameterize the prior on library size if use_size_factor_key is False and use_observed_lib_size is False.

var_activation

Callable used to ensure positivity of the variance of the variational distribution. Passed into Encoder. Defaults to exp().

extra_encoder_kwargs

Additional keyword arguments passed into Encoder.

extra_decoder_kwargs

Additional keyword arguments passed into DecoderSCVI.

batch_embedding_kwargs

Keyword arguments passed into Embedding if batch_representation is set to "embedding".

Notes

Lifecycle: argument batch_representation is experimental in v1.2.

dispersion = 'gene'

n_latent = 10

log_variational = True

gene_likelihood = 'zinb'

n_batch = 0

n_labels = 0

latent_distribution = 'normal'

encode_covariates = False

use_size_factor_key = False

use_observed_lib_size = True

extra_payload_autotune = False

batch_representation = 'one-hot'

z_encoder

l_encoder

decoder

_get_inference_input(tensors: dict[str, torch.Tensor | None], full_forward_pass: bool = False) → dict[str, torch.Tensor | None]

Get input tensors required for the inference process.

Parameters:

tensors

Input data tensors

full_forward_pass

Whether to execute full forward pass

Returns:

Input dictionary for inference process

_get_generative_input(tensors: dict[str, torch.Tensor], inference_outputs: dict[str, torch.Tensor | torch.distributions.Distribution | None]) → dict[str, torch.Tensor | None]

Get input tensors for the generative process.

Combine outputs from the inference step with original data to prepare inputs for the generative network.

Parameters:

tensors

Original data tensors

inference_outputs

Outputs from the inference process

Returns:

Input dictionary required for the generative process

_compute_local_library_params(batch_index: torch.Tensor) → tuple[torch.Tensor, torch.Tensor]

Compute local library parameters.

Calculate mean and variance parameters for library size for each cell, which depend on the batch the cell belongs to.

Parameters:

batch_index

Batch index tensor of shape (batch_size, 1)

Returns:

Contains two tensors, log library size means and variances respectively

Return type:

tuple

_regular_inference(x: torch.Tensor, batch_index: torch.Tensor, cont_covs: torch.Tensor | None = None, cat_covs: torch.Tensor | None = None, n_samples: int = 1) → dict[str, torch.Tensor | torch.distributions.Distribution | None]

Run regular inference process to obtain latent representations of data.

Parameters:

x

Gene expression data

batch_index

Batch indices

cont_covs

Continuous covariates

cat_covs

Categorical covariates

n_samples

Number of samples

Returns:

Dictionary containing latent variables and distributions

_cached_inference(qzm: torch.Tensor, qzv: torch.Tensor, observed_lib_size: torch.Tensor, n_samples: int = 1) → dict[str, torch.Tensor | None]

Perform inference using cached latent variable distribution parameters.

This method is mainly used when latent variable distributions have already been computed and stored, which can speed up inference without re-running the encoder network.

Parameters:

qzm

Latent variable means

qzv

Latent variable variances

observed_lib_size

Observed library size

n_samples

Number of samples

Returns:

Dictionary containing latent variables and distributions

generative(z: torch.Tensor, library: torch.Tensor, batch_index: torch.Tensor, cont_covs: torch.Tensor | None = None, cat_covs: torch.Tensor | None = None, size_factor: torch.Tensor | None = None, y: torch.Tensor | None = None, transform_batch: torch.Tensor | None = None) → dict[str, torch.distributions.Distribution | None]

Run the generative process to get distribution parameters.

This method takes latent representations and covariates to generate the parameters of the data distribution.

Parameters:

z torch.Tensor

Latent space representation

library torch.Tensor

Library size factors

batch_index torch.Tensor

Batch indices for each cell

cont_covs torch.Tensor, optional

Continuous covariates

cat_covs torch.Tensor, optional

Categorical covariates

size_factor torch.Tensor, optional

Size factors (if not using library)

y torch.Tensor, optional

Labels for each cell

transform_batch torch.Tensor, optional

Batch to transform to (for batch correction)

Returns:

Dictionary with distribution objects for data, library size, and latent space

Return type:

dict

loss(tensors: dict[str, torch.Tensor], inference_outputs: dict[str, torch.Tensor | torch.distributions.Distribution | None], generative_outputs: dict[str, torch.distributions.Distribution | None], kl_weight: torch.tensor | float = 1.0) → scvi.module.base.LossOutput

Compute the loss function for the variational autoencoder.

The loss function consists of two parts: reconstruction loss and KL divergence: 1. Reconstruction loss: measures how well the generated data matches the original data 2. KL divergence: measures the difference between posterior and prior distributions, acting as regularization

Parameters:

tensors

Original data tensors

inference_outputs

Outputs from the inference process

generative_outputs

Outputs from the generative process

kl_weight

Weight coefficient for KL divergence term (used for KL annealing)

Returns:

Object containing total loss and individual loss components

sample(tensors: dict[str, torch.Tensor], n_samples: int = 1, max_poisson_rate: float = 100000000.0) → torch.Tensor

Generate predictive samples from the posterior predictive distribution.

The posterior predictive distribution is denoted as \(p(\hat{x} \mid x)\), where \(x\) is the input data and \(\hat{x}\) is the sampled data.

We sample from this distribution by first sampling n_samples times from the posterior distribution \(q(z \mid x)\) for a given observation, and then sampling from the likelihood \(p(\hat{x} \mid z)\) for each of these.

Parameters:

tensors

Dictionary of tensors passed into forward().

n_samples

Number of Monte Carlo samples to draw from the distribution for each observation.

max_poisson_rate

The maximum value to which to clip the rate parameter of Poisson. Avoids numerical sampling issues when the parameter is very large due to the variance of the distribution.

Returns:

• Tensor on CPU with shape (n_obs, n_vars) if n_samples == 1, else

• (n_obs, n_vars,).

marginal_ll(tensors: dict[str, torch.Tensor], n_mc_samples: int, return_mean: bool = False, n_mc_samples_per_pass: int = 1)

Compute the marginal log-likelihood of the data under the model.

Parameters:

tensors

Dictionary of tensors passed into forward().

n_mc_samples

Number of Monte Carlo samples to use for the estimation of the marginal log-likelihood.

return_mean

Whether to return the mean of marginal likelihoods over cells.

n_mc_samples_per_pass

Number of Monte Carlo samples to use per pass. This is useful to avoid memory issues.

get_loadings() → numpy.ndarray

Extract per-gene weights in the linear decoder.

Returns:

A matrix of weights showing how each latent dimension

contributes to each gene’s expression level.

Return type:

numpy.ndarray

class spateo.external.MERFISHVI._module.LDVAE(n_input: int, n_batch: int = 0, n_labels: int = 0, n_hidden: int = 128, n_latent: int = 10, n_layers_encoder: int = 1, dropout_rate: float = 0.1, dispersion: str = 'gene', log_variational: bool = True, gene_likelihood: str = 'nb', use_batch_norm: bool = True, bias: bool = False, latent_distribution: str = 'normal', use_observed_lib_size: bool = False, **kwargs)

Bases: VAE

Linear-decoded Variational auto-encoder model.

Implementation of :cite:p:`Svensson20`.

This model uses a linear decoder, directly mapping the latent representation to gene expression levels. It still uses a deep neural network to encode the latent representation.

Compared to standard VAE, this model is less powerful, but can be used to inspect which genes contribute to variation in the dataset. It may also be used for all scVI tasks, like differential expression, batch correction, imputation, etc. However, batch correction may be less powerful as it assumes a linear model.

Parameters:

n_input

Number of input genes

n_batch

Number of batches

n_labels

Number of labels

n_hidden

Number of nodes per hidden layer (for encoder)

n_latent

Dimensionality of the latent space

n_layers_encoder

Number of hidden layers used for encoder NNs

dropout_rate

Dropout rate for neural networks

dispersion

One of the following

• 'gene' - dispersion parameter of NB is constant per gene across cells

• 'gene-batch' - dispersion can differ between different batches

• 'gene-label' - dispersion can differ between different labels

• 'gene-cell' - dispersion can differ for every gene in every cell

log_variational

Log(data+1) prior to encoding for numerical stability. Not normalization.

gene_likelihood

One of

• 'nb' - Negative binomial distribution

• 'zinb' - Zero-inflated negative binomial distribution

• 'poisson' - Poisson distribution

use_batch_norm

Bool whether to use batch norm in decoder

bias

Bool whether to have bias term in linear decoder

latent_distribution

One of

• 'normal' - Isotropic normal

• 'ln' - Logistic normal with normal params N(0, 1)

use_observed_lib_size

Use observed library size for RNA as scaling factor in mean of conditional distribution.

**kwargs

use_batch_norm = True

z_encoder

l_encoder

decoder

get_loadings() → numpy.ndarray

Extract per-gene weights in the linear decoder.

Returns:

A matrix of weights showing how each latent dimension

contributes to each gene’s expression level.

Return type:

numpy.ndarray