spateo.external.MERFISHVI._module ================================= .. py:module:: spateo.external.MERFISHVI._module Attributes ---------- .. autoapisummary:: spateo.external.MERFISHVI._module.logger Classes ------- .. autoapisummary:: spateo.external.MERFISHVI._module.VAE spateo.external.MERFISHVI._module.LDVAE Module Contents --------------- .. py:data:: logger :value: None .. py:class:: 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: :py:obj:`scvi.module.base.EmbeddingModuleMixin`, :py:obj:`scvi.module.base.BaseMinifiedModeModuleClass` Variational auto-encoder :cite:p:`Lopez18`. :param n_input: Number of input features. :param n_batch: Number of batches. If ``0``, no batch correction is performed. :param n_labels: Number of labels. :param n_hidden: Number of nodes per hidden layer. Passed into :class:`~scvi.nn.Encoder` and :class:`~scvi.nn.DecoderSCVI`. :param n_latent: Dimensionality of the latent space. :param n_layers: Number of hidden layers. Passed into :class:`~scvi.nn.Encoder` and :class:`~scvi.nn.DecoderSCVI`. :param n_continuous_cov: Number of continuous covariates. :param n_cats_per_cov: A list of integers containing the number of categories for each categorical covariate. :param dropout_rate: Dropout rate. Passed into :class:`~scvi.nn.Encoder` but not :class:`~scvi.nn.DecoderSCVI`. :param 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. :param log_variational: If ``True``, use :func:`~torch.log1p` on input data before encoding for numerical stability (not normalization). :param gene_likelihood: Distribution to use for reconstruction in the generative process. One of the following: * ``"nb"``: :class:`~scvi.distributions.NegativeBinomial`. * ``"zinb"``: :class:`~scvi.distributions.ZeroInflatedNegativeBinomial`. * ``"poisson"``: :class:`~scvi.distributions.Poisson`. * ``"normal"``: :class:`~torch.distributions.Normal`. :param 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). :param encode_covariates: If ``True``, covariates are concatenated to gene expression prior to passing through the encoder(s). Else, only gene expression is used. :param 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. :param 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 :class:`~scvi.nn.Embedding`. Note that batch representations are only passed into the encoder(s) if ``encode_covariates`` is ``True``. :param use_batch_norm: Specifies where to use :class:`~torch.nn.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 :class:`~torch.nn.BatchNorm1d`, then :class:`~torch.nn.LayerNorm`). :param use_layer_norm: Specifies where to use :class:`~torch.nn.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 :class:`~torch.nn.BatchNorm1d`, then :class:`~torch.nn.LayerNorm`). :param use_size_factor_key: If ``True``, use the :attr:`~anndata.AnnData.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``. :param use_observed_lib_size: If ``True``, use the observed library size for RNA as the scaling factor in the mean of the conditional distribution. :param extra_payload_autotune: If ``True``, will return extra matrices in the loss output to be used during autotune :param library_log_means: :class:`~numpy.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``. :param library_log_vars: :class:`~numpy.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``. :param var_activation: Callable used to ensure positivity of the variance of the variational distribution. Passed into :class:`~scvi.nn.Encoder`. Defaults to :func:`~torch.exp`. :param extra_encoder_kwargs: Additional keyword arguments passed into :class:`~scvi.nn.Encoder`. :param extra_decoder_kwargs: Additional keyword arguments passed into :class:`~scvi.nn.DecoderSCVI`. :param batch_embedding_kwargs: Keyword arguments passed into :class:`~scvi.nn.Embedding` if ``batch_representation`` is set to ``"embedding"``. .. rubric:: Notes Lifecycle: argument ``batch_representation`` is experimental in v1.2. .. py:attribute:: dispersion :value: 'gene' .. py:attribute:: n_latent :value: 10 .. py:attribute:: log_variational :value: True .. py:attribute:: gene_likelihood :value: 'zinb' .. py:attribute:: n_batch :value: 0 .. py:attribute:: n_labels :value: 0 .. py:attribute:: latent_distribution :value: 'normal' .. py:attribute:: encode_covariates :value: False .. py:attribute:: use_size_factor_key :value: False .. py:attribute:: use_observed_lib_size :value: True .. py:attribute:: extra_payload_autotune :value: False .. py:attribute:: batch_representation :value: 'one-hot' .. py:attribute:: z_encoder .. py:attribute:: l_encoder .. py:attribute:: decoder .. py:method:: _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. :param tensors: Input data tensors :param full_forward_pass: Whether to execute full forward pass :returns: Input dictionary for inference process .. py:method:: _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. :param tensors: Original data tensors :param inference_outputs: Outputs from the inference process :returns: Input dictionary required for the generative process .. py:method:: _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. :param batch_index: Batch index tensor of shape (batch_size, 1) :returns: Contains two tensors, log library size means and variances respectively :rtype: tuple .. py:method:: _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. :param x: Gene expression data :param batch_index: Batch indices :param cont_covs: Continuous covariates :param cat_covs: Categorical covariates :param n_samples: Number of samples :returns: Dictionary containing latent variables and distributions .. py:method:: _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. :param qzm: Latent variable means :param qzv: Latent variable variances :param observed_lib_size: Observed library size :param n_samples: Number of samples :returns: Dictionary containing latent variables and distributions .. py:method:: 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. :param z: Latent space representation :type z: torch.Tensor :param library: Library size factors :type library: torch.Tensor :param batch_index: Batch indices for each cell :type batch_index: torch.Tensor :param cont_covs: Continuous covariates :type cont_covs: torch.Tensor, optional :param cat_covs: Categorical covariates :type cat_covs: torch.Tensor, optional :param size_factor: Size factors (if not using library) :type size_factor: torch.Tensor, optional :param y: Labels for each cell :type y: torch.Tensor, optional :param transform_batch: Batch to transform to (for batch correction) :type transform_batch: torch.Tensor, optional :returns: Dictionary with distribution objects for data, library size, and latent space :rtype: dict .. py:method:: 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 :param tensors: Original data tensors :param inference_outputs: Outputs from the inference process :param generative_outputs: Outputs from the generative process :param kl_weight: Weight coefficient for KL divergence term (used for KL annealing) :returns: Object containing total loss and individual loss components .. py:method:: 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 :math:`p(\hat{x} \mid x)`, where :math:`x` is the input data and :math:`\hat{x}` is the sampled data. We sample from this distribution by first sampling ``n_samples`` times from the posterior distribution :math:`q(z \mid x)` for a given observation, and then sampling from the likelihood :math:`p(\hat{x} \mid z)` for each of these. :param tensors: Dictionary of tensors passed into :meth:`~scvi.module.VAE.forward`. :param n_samples: Number of Monte Carlo samples to draw from the distribution for each observation. :param max_poisson_rate: The maximum value to which to clip the ``rate`` parameter of :class:`~scvi.distributions.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,)``. .. py:method:: 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. :param tensors: Dictionary of tensors passed into :meth:`~scvi.module.VAE.forward`. :param n_mc_samples: Number of Monte Carlo samples to use for the estimation of the marginal log-likelihood. :param return_mean: Whether to return the mean of marginal likelihoods over cells. :param n_mc_samples_per_pass: Number of Monte Carlo samples to use per pass. This is useful to avoid memory issues. .. py:method:: 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. :rtype: numpy.ndarray .. py:class:: 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: :py:obj:`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. :param n_input: Number of input genes :param n_batch: Number of batches :param n_labels: Number of labels :param n_hidden: Number of nodes per hidden layer (for encoder) :param n_latent: Dimensionality of the latent space :param n_layers_encoder: Number of hidden layers used for encoder NNs :param dropout_rate: Dropout rate for neural networks :param 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 :param log_variational: Log(data+1) prior to encoding for numerical stability. Not normalization. :param gene_likelihood: One of * ``'nb'`` - Negative binomial distribution * ``'zinb'`` - Zero-inflated negative binomial distribution * ``'poisson'`` - Poisson distribution :param use_batch_norm: Bool whether to use batch norm in decoder :param bias: Bool whether to have bias term in linear decoder :param latent_distribution: One of * ``'normal'`` - Isotropic normal * ``'ln'`` - Logistic normal with normal params N(0, 1) :param use_observed_lib_size: Use observed library size for RNA as scaling factor in mean of conditional distribution. :param \*\*kwargs: .. py:attribute:: use_batch_norm :value: True .. py:attribute:: z_encoder .. py:attribute:: l_encoder .. py:attribute:: decoder .. py:method:: 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. :rtype: numpy.ndarray