Model evaluation

get_latent_representation(m::scVAE, countmatrix::Matrix; 
    cellindices=nothing, give_mean::Bool=true
)

Computes the latent representation of an scVAE model on input count data by applying the scVAE encoder.

Returns the mean (default) or a sample of the latent representation (can be controlled by give_mean keyword argument).

Arguments:

• m::scVAE: scVAE model from which the encoder is applied to get the latent representation
• countmatrix::Matrix: matrix of counts (e.g., countmatrix field of an AnnData object), which is to be embedded with the scVAE model encoder. Is assumed to be in a (cell x gene) format.

Keyword arguments:

• cellindices=nothing: optional; indices of cells (=rows) on which to subset the countmatrix before embedding it
• give_mean::Bool=true: optional; if true, returns the mean of the latent representation, else returns a sample.

register_latent_representation!(adata::AnnData, m::scVAE)

Calculates the latent representation obtained from encoding the countmatrix of the AnnData object with a trained scVAE model by applying the function get_latent_representation(m, adata.X). Stored the latent representation in the scVI_latent field of the input AnnData object.

Returns the modified AnnData object.

get_loadings(dec::scLinearDecoder)

Extracts the loadings of a scLinearDecoder, specifically corresponding to the weight matrix of the linear scLinearDecoder.factor_regressor layer. If batch normalisation is applied, the weight matrix is re-scaled according to the accumulated statistics in the batch norm layer (for details, see ?Flux.BatchNorm).

Returns the matrix of loadings.

register_umap_on_latent!(adata::AnnData, m::scVAE)

Calculates a UMAP (Uniform Manifold Projection and Embedding, McInnes et al. 2018) embedding of the latent representation obtained from encoding the countmatrix of the AnnData object with a trained scVAE model. If a latent representation is already stored in adata.scVI_latent, this is used for calculating the UMAP, if not, a latent representation is calculated and registered by calling register_latent_representation!(adata, m).

The UMAP is calculated using the Julia package UMAP.jl with default parameters. It is then stored in the scVI_latent_umap field of the input AnnData object.

Returns the modified AnnData object.

function plot_umap_on_latent(
    m::scVAE, adata::AnnData; 
    save_plot::Bool=false, 
    seed::Int=987, 
    filename::String="UMAP_on_latent.pdf"
)

Plots a UMAP embedding of the latent representation obtained from encoding the countmatrix of the AnnData object with the scVAE model. If no UMAP representation is stored in adata.scVI_latent_umap, it is calculated and registered by calling register_umap_on_latent(adata, m).

By default, the cells are color-coded according to the celltypes field of the AnnData object.

For plotting, the VegaLite.jl package is used.

Arguments:

• m::scVAE: trained scVAE model to use for embedding the data with the model encoder
• adata:AnnData: data to embed with the model; adata.X is encoded with m

Keyword arguments:

• save_plot::Bool=true: whether or not to save the plot
• filename::String="UMAP_on_latent.pdf: filename under which to save the plot. Has no effect if save_plot==false.
• seed::Int=987: which random seed to use for calculating UMAP (to ensure reproducibility)

plot_pca_on_latent(
    m::scVAE, adata::AnnData; 
    save_plot::Bool=false, 
    filename::String="PCA_on_latent.pdf"
)

Plots a PCA embedding of the latent representation obtained from encoding the countmatrix of the AnnData object with the scVAE model. If no latent representation is stored in adata.scVI_latent, it is calculated and registered by calling register_latent_representation(adata, m).

PCA is calculated using the singular value decomposition implementation in LinearAlgebra.jl, see ?LinearAlgebra.svd. For details on the PCA implementation, see the source code in the prcomps function in src/Evaluate.jl.

By default, the cells are color-coded according to the celltypes field of the AnnData object.

For plotting, the VegaLite.jl package is used.

Arguments:

• m::scVAE: trained scVAE model to use for embedding the data with the model encoder
• adata:AnnData: data to embed with the model; adata.X is encoded with m

Keyword arguments:

• save_plot::Bool=true: whether or not to save the plot
• filename::String="UMAP_on_latent.pdf: filename under which to save the plot. Has no effect if save_plot==false.

function plot_latent_representation(
    m::scVAE, adata::AnnData; 
    save_plot::Bool=false, 
    seed::Int=987, 
    filename::String="UMAP_on_latent.pdf"
)

Plots the latent representation obtained from encoding the countmatrix of the AnnData object with the scVAE model. If the dimension of the latent space according to m.n_latent is > 2, it calculates a UMAP embedding first. In this case, if no UMAP representation is stored in adata.scVI_latent_umap, it is calculated and registered by calling register_umap_on_latent(adata, m).

By default, the cells are color-coded according to the celltypes column in adata.obs, if present.

For plotting, the VegaLite.jl package is used.

Arguments:

• m::scVAE: trained scVAE model to use for embedding the data with the model encoder
• adata:AnnData: data to embed with the model; adata.X is encoded with m

Keyword arguments:

• save_plot::Bool=true: whether or not to save the plot
• filename::String="UMAP_on_latent.pdf: filename under which to save the plot. Has no effect if save_plot==false.
• seed::Int=987: which random seed to use for calculating UMAP (to ensure reproducibility)

sample_from_prior(m::scVAE, adata::AnnData, n_samples::Int; sample_library_size::Bool=false)

Samples from the prior N(0,1) distribution of the latent representation of a trained scVAE model. Calculates the library size based on the countmatrix of the input AnnData object and either samples from it or uses the mean. Subsequently draws n_samples from the generative distribution defined by the decoder based on the samples from the prior and the library size.

Returns the samples from the model.

Arguments:

• m::scVAE: trained scVAE model from which to sample
• adata::AnnData: AnnData object based on which to calculate the library size
• n_samples::Int: number of samples to draw

Keyword arguments:

• sample_library_size::Bool=false: whether or not to sample from the library size. If false, the mean of the observed library size is used.

sample_from_posterior(m::scVAE, adata::AnnData)

Samples from the posterior distribution of the latent representation of a trained scVAE model. Calculates the latent posterior mean and variance and the library size based on the countmatrix of the input AnnData object and samples from the posterior. Subsequently samples from the generative distribution defined by the decoder based on the samples of the latent representation and the library size.

Returns the samples from the model.

Arguments:

• m::scVAE: trained scVAE model from which to sample
• adata::AnnData: AnnData object based on which to calculate the latent posterior