clonealign.Rd
clonealign
assigns single cells (measured with RNA-seq) to their clones of origin, where
the clones have been inferred from ultra-shallow scDNA-seq and collated into copy number profiles.
clonealign(gene_expression_data, copy_number_data, max_iter = 100, rel_tol = 1e-06, gene_filter_threshold = 0, learning_rate = 0.1, x = NULL, fix_alpha = FALSE, fix_s = NULL, dtype = "float64", saturate = TRUE, saturation_threshold = 6, K = NULL, B = 20, verbose = TRUE)
gene_expression_data | A matrix of gene counts or a
|
---|---|
copy_number_data | A matrix or data frame of copy number calls for each clone.
See |
max_iter | Maximum number of Variational Bayes iterations to perform |
rel_tol | Relative tolerance (change in ELBO per iteration in percent) below which the inference is considered converged |
gene_filter_threshold | Genes with total counts below or equal to this threshold will be filtered out (removes genes with no counts by default) |
learning_rate | The learning rate to be passed to the Adam optimizer |
x | An optional vector of covariates, e.g. corresponding to batch or patient. Can be a vector of a single covariate or a sample by covariate matrix. Note this should not contain an intercept. |
fix_alpha | Should the underlying priors for clone frequencies be fixed? Default TRUE (values are inferred from the data) |
fix_s | Should the size factors be fixed? If |
dtype | The dtype for tensorflow useage, either "float32" or "float64" |
saturate | Should the CNV-expression relationship saturate above copy number = |
saturation_threshold | If |
K | The dimensionality of the expression latent space. If left |
B | Number of basis functions for spline fitting |
verbose | Should warnings and EM convergence information be printed? Default TRUE |
An object of class clonealign_fit
. The maximum likelihood estimates of the
clone assignment paramters are in the clone
slot. Maximum likelihood estimates of
all model parameters are in the ml_params
slot.
Input format
gene_expression_data
must either be a SingleCellExperiment
or SummarizedExperiment
with a counts
assay
representing raw gene expression counts, or a cell by gene matrix of raw counts.
copy_number_data
must either be a matrix
, data.frame
or DataFrame
with a
row for each gene in gene_expression_data
and a column for each of the clones.
If colnames(copy_number_data)
is not NULL
then these names will be used for each of
the clones in the final output.
Recommended parameter settings
As with any probabilistic model there are many parameters to set. Through comprehensive simulations regarding the robustness of the model to mis-specification (ie what's the minimum proportion of genes for which the CNV-expression relationship can be true and our inferences still valid) we have come up with the following guidelines for parameter settings, reflected in the default values:
Number of ADAM iterations - if set to 1 we essentially perform gradient descent on the marginal log-likelihood which empircally appears to have the best performance
Dispersions should be clone-specific with weak shrinkage (sigma
= 1 appears best)
The generating probabilities should be fixed to be a priori equal (this corresponds to setting alpha = TRUE
)
The cell size factors are best fixed in advanced by multiplying the total counts of whatever genes are passed to clonealign by the edgeR (TMM) normalization factors
Controlling Variational inference
Inference is performed using reparametrization-gradient variational inference. Convergence is monitored via changes
to the evidence lower bound (ELBO) - this is controlled using the
rel_tol
parameter. When the difference between the new and old ELBOs normalized
by the absolute value of the old falls below rel_tol
, the algorithm is considered converged.
The maximum number of iterations to acheive this is set using the max_iter
parameter.
In each step, maximization is performed using Adam, with learning rate given by learning_rate
.
library(SingleCellExperiment) data(example_sce) copy_number_data <- rowData(example_sce)[,c("A", "B", "C")] cal <- clonealign(example_sce, copy_number_data)#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>#>print(cal)#> A clonealign_fit for 200 cells, 100 genes, and 3 clones #> To access clone assignments, call x$clone #> To access ML parameter estimates, call x$ml_paramsclones <- cal$clone