scvi.model.base.DifferentialComputation#

class scvi.model.base.DifferentialComputation(model_fn, representation_fn, adata_manager)[source]#

Unified class for differential computation.

This class takes a function from a model like SCVI or TOTALVI and takes outputs from this function with respect to the adata input and computed Bayes factors as described in [Lopez et al., 2018], [Xu et al., 2021], or [Boyeau et al., 2019].

Parameters:
model_fn Callable

Callable in model API to get values from.

representation_fn Callable

Callable providing latent representations, e.g., get_latent_representation(), for scVI.

adata_manager AnnDataManager

AnnDataManager created by setup_anndata().

Methods table#

filter_outlier_cells(selection)

Filters out cells that are outliers in the representation space.

get_bayes_factors(idx1, idx2[, mode, ...])

A unified method for differential expression inference.

process_selection(selection)

If selection is a mask, convert it to indices.

scale_sampler(selection[, ...])

Samples the posterior scale using the variational posterior distribution.

Methods#

DifferentialComputation.filter_outlier_cells(selection)[source]#

Filters out cells that are outliers in the representation space.

DifferentialComputation.get_bayes_factors(idx1, idx2, mode='change', batchid1=None, batchid2=None, use_observed_batches=False, n_samples_overall=5000, use_permutation=False, m_permutation=10000, change_fn=None, m1_domain_fn=None, delta=0.5, pseudocounts=None, threshold_counts=0.01, test_mode='three', cred_interval_lvls=None)[source]#

A unified method for differential expression inference.

Two modes coexist:

\[M_1: h_1 > h_2 ~\text{and}~ M_2: h_1 \leq h_2.\]

DE can then be based on the study of the Bayes factors

\[\log p(M_1 | x_1, x_2) / p(M_2 | x_1, x_2).\]
  • The 'change' mode (described in [Boyeau et al., 2019]).

    This mode consists of estimating an effect size random variable (e.g., log fold-change) and performing Bayesian hypothesis testing on this variable. The change_fn function computes the effect size variable \(r\) based on two inputs corresponding to the posterior quantities (e.g., normalized expression) in both populations.

Hypotheses:

\[M_1: r \in R_1 ~\text{(effect size r in the region inducing differential expression)}\]
\[M_2: r \notin R_1 ~\text{(no differential expression)}\]

To characterize the region \(R_1\), which induces DE, the user has two choices.

  1. A common case is when the region \([-\delta, \delta]\) does not induce differential expression. If the user specifies a threshold delta, we suppose that \(R_1 = \mathbb{R} \setminus [-\delta, \delta]\)

  2. Specify a specific indicator function:

\[f: \mathbb{R} \mapsto \{0, 1\} ~\text{s.t.}~ r \in R_1 ~\text{iff.}~ f(r) = 1.\]

Decision-making can then be based on the estimates of

\[p(M_1 \mid x_1, x_2).\]

Both modes require sampling the posterior distributions. For that purpose, we sample the posterior in the following way:

  1. The posterior is sampled n_samples_overall times for each subpopulation.

  2. For computational efficiency (posterior sampling is quite expensive), instead of comparing the obtained samples element-wise, we can permute posterior samples. Remember that computing the Bayes Factor requires sampling \(q(z_A \mid x_A)\) and \(q(z_B \mid x_B)\).

Currently, the code covers several batch handling configurations:

  1. If use_observed_batches=True, then batches are considered as observations and cells’ normalized means are conditioned on real batch observations.

  2. If case (cell group 1) and control (cell group 2) are conditioned on the same batch ids. This requires set(batchid1) == set(batchid2) or batchid1 == batchid2 === None.

  3. If case and control are conditioned on different batch ids that do not intersect, i.e., set(batchid1) != set(batchid2) and len(set(batchid1).intersection(set(batchid2))) == 0.

This function does not cover other cases yet and will warn users in such cases.

Parameters:
mode Literal['vanilla', 'change'] (default: 'change')

one of [“vanilla”, “change”]

idx1 list[bool] | ndarray

bool array masking subpopulation cells 1. Should be True where cell is from associated population

idx2 list[bool] | ndarray

bool array masking subpopulation cells 2. Should be True where cell is from associated population

batchid1 Sequence[int | float | str] | None (default: None)

List of batch ids for which you want to perform DE Analysis for subpopulation 1. By default, all ids are taken into account

batchid2 Sequence[int | float | str] | None (default: None)

List of batch ids for which you want to perform DE Analysis for subpopulation 2. By default, all ids are taken into account

use_observed_batches bool | None (default: False)

Whether posterior values are conditioned on observed batches

n_samples_overall int (default: 5000)

Number of overall posterior samples

use_permutation bool (default: False)

Activates step 2 described above. Simply formulated, pairs obtained from posterior sampling will be randomly permuted so that the number of pairs used to compute Bayes Factors becomes m_permutation.

m_permutation int (default: 10000)

Number of times we will “mix” posterior samples in step 2. Only makes sense when use_permutation=True

change_fn str | Callable | None (default: None)

function computing effect size based on both posterior values

m1_domain_fn Callable | None (default: None)

custom indicator function of effect size regions inducing differential expression

delta float | None (default: 0.5)

specific case of region inducing differential expression. In this case, we suppose that \(R \setminus [-\delta, \delta]\) does not induce a differential expression (LFC case). If the provided value is None, then a proper threshold is determined from the distribution of LFCs across genes.

pseudocounts float | None (default: None)

pseudocount offset used for the mode change. When None, observations from non-expressed genes are used to estimate its value.

threshold_counts float (default: 0.01)

mean expression threshold in a group to consider a gene as non-expressed

test_mode Literal['two', 'three'] (default: 'three')

consider down- and up-regulated genes separately (three) or all genes together (two)

cred_interval_lvls list[float] | ndarray | None (default: None)

List of credible interval levels to compute for the posterior LFC distribution

Return type:

dict[str, ndarray]

Returns:

Differential expression properties

DifferentialComputation.process_selection(selection)[source]#

If selection is a mask, convert it to indices.

Return type:

ndarray

DifferentialComputation.scale_sampler(selection, n_samples_overall=5000, n_samples_per_cell=None, batchid=None, use_observed_batches=False, give_mean=False)[source]#

Samples the posterior scale using the variational posterior distribution.

Parameters:
selection list[bool] | ndarray

Mask or list of cell ids to select

n_samples_overall int | None (default: 5000)

Number of samples in total per batch (fill either n_samples_total or n_samples_per_cell)

n_samples_per_cell int | None (default: None)

Number of time we sample from each observation per batch (fill either n_samples_total or n_samples_per_cell)

batchid Sequence[int | float | str] | None (default: None)

Biological batch for which to sample from. Default (None) sample from all batches

use_observed_batches bool | None (default: False)

Whether normalized means are conditioned on observed batches or if observed batches are to be used

give_mean bool | None (default: False)

Return mean of values

Return type:

dict

Returns:

type Dictionary containing: scale Posterior aggregated scale samples of shape (n_samples, n_vars) where n_samples correspond to either: - n_bio_batches * n_cells * n_samples_per_cell or - n_samples_total batch associated batch ids