scvi.external.methylvi.BSSeqMixin

scvi.external.methylvi.BSSeqMixin#

class scvi.external.methylvi.BSSeqMixin[source]#

Bases: object

General purpose methods for BS-seq analysis.

Methods table#

differential_methylation([mdata, groupby, ...])

.

get_normalized_methylation([mdata, indices, ...])

Returns the normalized (decoded) methylation.

get_specific_normalized_methylation([mdata, ...])

Convenience function to obtain normalized methylation values for a single context.

Methods#

BSSeqMixin.differential_methylation(mdata=None, groupby=None, group1=None, group2=None, idx1=None, idx2=None, mode='vanilla', delta=0.05, batch_size=None, all_stats=True, batch_correction=False, batchid1=None, batchid2=None, fdr_target=0.05, silent=False, two_sided=True, **kwargs)[source]#

.

A unified method for differential methylation analysis.

Implements “vanilla” DE [Lopez et al., 2018]. and “change” mode DE [Boyeau et al., 2019].

Parameters:

  • mdata (MuData | None (default: None)) – MuData object with equivalent structure to initial MuData. If None, defaults to the MuData object used to initialize the model.

  • groupby (str | None (default: None)) – The key of the observations grouping to consider.

  • group1 (Iterable[str] | None (default: None)) – Subset of groups, e.g. [‘g1’, ‘g2’, ‘g3’], to which comparison shall be restricted, or all groups in groupby (default).

  • group2 (str | None (default: None)) – If None, compare each group in group1 to the union of the rest of the groups in groupby. If a group identifier, compare with respect to this group.

  • idx1 (Sequence[int] | Sequence[bool] | str | None (default: None)) – idx1 and idx2 can be used as an alternative to the AnnData keys. Custom identifier for group1 that can be of three sorts: (1) a boolean mask, (2) indices, or (3) a string. If it is a string, then it will query indices that verifies conditions on adata.obs, as described in pandas.DataFrame.query() If idx1 is not None, this option overrides group1 and group2.

  • idx2 (Sequence[int] | Sequence[bool] | str | None (default: None)) – Custom identifier for group2 that has the same properties as idx1. By default, includes all cells not specified in idx1.

  • mode (Literal['vanilla', 'change'] (default: 'vanilla')) – Method for differential expression. See user guide for full explanation.

  • delta (float (default: 0.05)) – specific case of region inducing differential expression. In this case, we suppose that \(R \setminus [-\delta, \delta]\) does not induce differential expression (change model default case).

  • batch_size (int | None (default: None)) – Minibatch size for data loading into model. Defaults to scvi.settings.batch_size.

  • all_stats (bool (default: True)) – Concatenate count statistics (e.g., mean expression group 1) to DE results.

  • batch_correction (bool (default: False)) – Whether to correct for batch effects in DE inference.

  • batchid1 (Iterable[str] | None (default: None)) – Subset of categories from batch_key registered in setup_anndata, e.g. [‘batch1’, ‘batch2’, ‘batch3’], for group1. Only used if batch_correction is True, and by default all categories are used.

  • batchid2 (Iterable[str] | None (default: None)) – Same as batchid1 for group2. batchid2 must either have null intersection with batchid1, or be exactly equal to batchid1. When the two sets are exactly equal, cells are compared by decoding on the same batch. When sets have null intersection, cells from group1 and group2 are decoded on each group in group1 and group2, respectively.

  • fdr_target (float (default: 0.05)) – Tag features as DE based on posterior expected false discovery rate.

  • silent (bool (default: False)) – If True, disables the progress bar. Default: False.

  • two_sided (bool (default: True)) – Whether to perform a two-sided test, or a one-sided test.

  • **kwargs – Keyword args for scvi.model.base.DifferentialComputation.get_bayes_factors()

Return type:

dict[str, DataFrame] | DataFrame

Returns:

Differential methylation DataFrame with the following columns:

proba_de

the probability of the region being differentially methylated

is_de_fdr

whether the region passes a multiple hypothesis correction procedure with the target_fdr threshold

bayes_factor

Bayes Factor indicating the level of significance of the analysis

effect_size

the effect size, computed as (accessibility in population 2) - (accessibility in population 1)

emp_effect

the empirical effect, based on observed detection rates instead of the estimated accessibility scores from the methylVI model

scale1

the estimated methylation level in population 1

scale2

the estimated methylation level in population 2

emp_mean1

the empirical (observed) methylation level in population 1

emp_mean2

the empirical (observed) methylation level in population 2

BSSeqMixin.get_normalized_methylation(mdata=None, indices=None, region_list=None, n_samples=1, n_samples_overall=None, batch_size=None, return_mean=True, return_numpy=None, context=None, **importance_weighting_kwargs)[source]#

Returns the normalized (decoded) methylation.

This is denoted as \(\mu_n\) in the methylVI paper.

Parameters:

  • mdata (MuData | None (default: None)) – MuData object with equivalent structure to initial Mudata. If None, defaults to the MuData object used to initialize the model.

  • indices (Sequence[int] | None (default: None)) – Indices of cells in mdata to use. If None, all cells are used.

  • region_list (Sequence[str] | None (default: None)) – Return frequencies of expression for a subset of regions. This can save memory when working with large datasets and few regions are of interest.

  • n_samples (int (default: 1)) – Number of posterior samples to use for estimation.

  • n_samples_overall (int (default: None)) – Number of posterior samples to use for estimation. Overrides n_samples.

  • batch_size (int | None (default: None)) – Minibatch size for data loading into model. Defaults to scvi.settings.batch_size.

  • return_mean (bool (default: True)) – Whether to return the mean of the samples.

  • return_numpy (bool | None (default: None)) – Return a ndarray instead of a DataFrame. DataFrame includes region names as columns. If either n_samples=1 or return_mean=True, defaults to False. Otherwise, it defaults to True.

  • context (str | None (default: None)) – If not None, returns normalized methylation levels for the specified methylation context. Otherwise, a dictionary with contexts as keys and normalized methylation levels as values is returned.

Return type:

ndarray | DataFrame | dict[str, ndarray | DataFrame]

Returns:

If n_samples is provided and return_mean is False, this method returns a 3d tensor of shape (n_samples, n_cells, n_regions). If n_samples is provided and return_mean is True, it returns a 2d tensor of shape (n_cells, n_regions). In this case, return type is DataFrame unless return_numpy is True. Otherwise, the method expects n_samples_overall to be provided and returns a 2d tensor of shape (n_samples_overall, n_regions).

If model was set up using a MuData object, a dictionary is returned with keys corresponding to individual methylation contexts with values determined as described above.

BSSeqMixin.get_specific_normalized_methylation(mdata=None, context=None, indices=None, transform_batch=None, region_list=None, n_samples=1, n_samples_overall=None, weights=None, batch_size=None, return_mean=True, return_numpy=None, **importance_weighting_kwargs)[source]#

Convenience function to obtain normalized methylation values for a single context.

Parameters:

  • mdata (MuData | None (default: None)) – MuData object with equivalent structure to initial MuData. If None, defaults to the MuData object used to initialize the model.

  • context (str (default: None)) – Methylation context for which to obtain normalized methylation levels.

  • indices (Sequence[int] | None (default: None)) – Indices of cells in mdata to use. If None, all cells are used.

  • transform_batch (Sequence[int | float | str] | None (default: None)) –

    Batch to condition on. If transform_batch is:

    • None, then real observed batch is used.

    • int, then batch transform_batch is used.

  • region_list (Sequence[str] | None (default: None)) – Return frequencies of expression for a subset of regions. This can save memory when working with large datasets and few regions are of interest.

  • n_samples (int (default: 1)) – Number of posterior samples to use for estimation.

  • n_samples_overall (int (default: None)) – Number of posterior samples to use for estimation. Overrides n_samples.

  • weights (Literal['uniform', 'importance'] | None (default: None)) – Weights to use for sampling. If None, defaults to “uniform”.

  • batch_size (int | None (default: None)) – Minibatch size for data loading into model. Defaults to scvi.settings.batch_size.

  • return_mean (bool (default: True)) – Whether to return the mean of the samples.

  • return_numpy (bool | None (default: None)) – Return a ndarray instead of a DataFrame. DataFrame includes region names as columns. If either n_samples=1 or return_mean=True, defaults to False. Otherwise, it defaults to True.

  • importance_weighting_kwargs – Keyword arguments passed into get_importance_weights().

Return type:

ndarray | DataFrame | dict[str, ndarray | DataFrame]

Returns:

If n_samples is provided and return_mean is False, this method returns a 3d tensor of shape (n_samples, n_cells, n_regions). If n_samples is provided and return_mean is True, it returns a 2d tensor of shape (n_cells, n_regions). In this case, return type is DataFrame unless return_numpy is True. Otherwise, the method expects n_samples_overall to be provided and returns a 2d tensor of shape (n_samples_overall, n_regions).