mutation.rem: Estimation of the random-effect model for clonality based on...
In Clonality: Clonality testing

Description Usage Arguments Details Value Author(s) References Examples

The model estimates the proportion of clonal cases in a population, and the distribution of the clonality signal.

1	mutation.rem(mutmat, proba=FALSE, print.proba=FALSE, xigrid = seq(0.0005, 0.9995, by=0.001), init.para = c(0,1,0.5), conv.crit = 1e-5, niter=300 )

`mutmat`	Matrix containing the data, with all mutations in rows and the tumor pairs in columns. The data are coded as 0=mutation not observed, 1=shared mutation (observed in both tumors), 2=private mutation (observed in one tumor only). The first column contains the probabilities of occurence for each mutation.
`proba`	Indicates whether to compute the individual probabilities of clonality for each pair. The default is FALSE.
`print.proba`	Indicates whether the individual probabilities of clonality should be printed in the output. The default is FALSE.
`xigrid`	Grid of the values of xi used to compute the integration; it corresponds to the domain of definition of xi. The default is seq(0.0005, 0.9995, by=0.001).
`init.para`	Initial values of the parameters for the optimization. The order of the parameters is c(mu, sigma, pi), where mu and sigma are the mean and variance of the lognormal distribution of the random-effect xi, and pi is the proportion of clonal cases. The default is c(0,1,0.5).
`conv.crit`	Criteria used to defined convergence (on all three parameters). The default is 1e-5.
`niter`	Maximum number of iterations used for the EM algorithm. The default is 300.

The function estimates a random effects model in which the random effect (the clonality signal, denoted xi_i for the ith case) reflects the somatic similarity of the tumors on a scale from 0 to 1, where 0 represents independence and higher values represent clonal tumors that are increasingly similar. The proportion of cases that are clonal is represented by the parameter pi. Thus the likelihood is a compound of (1-pi) cases that have a clonality signal of exactly 0, and pi cases that have a clonality signal drawn from a lognormal random effects distribution with mean mu and variance sigma^2. The program estimates the parameters using an EM algorithm to maximize the likelihood. The output provides parameter estimates (mu, sigma, pi). The example dataset presented contains data from a study in which each patient has both a pre-malignant lobular carcinoma in situ (LCIS) and an invasive breast cancer, and we wish to estimate the proportion of these cases for which the LCIS was a direct precursor to the invasive cancer.

`mu`	Estimated mean of the random-effect distribution.
`sigma`	Estimated standard-deviation of the random-effect distribution.
`pi`	Estimated proportion of clonal pairs in the population.
`likmat`	Grid of likelihood values for each tumor pair (rows) and each value of xi (columns) needed for the function clonal.proba that computes the individual probabilities of clonality.
`likelihood`	Value of the maximized likelihood.
`convergence`	Convergence status, 0=no convergence, 1=convergence reached.
`n.iter`	Number of iterations used.
`pr.clonal`	Individual probabilities of clonality.

Audrey Mauguen mauguena@mskcc.org and Venkatraman E. Seshan.

Mauguen A, Seshan VE, Ostrovnaya I, Begg CB. Estimating the Probability of Clonal Relatedness of Pairs of Tumors in Cancer Patients. Biometrics 2018;74(1):321-330.

#___ Analysis of LCIS data
data(lcis)
 mut.matrix<-create.mutation.matrix(lcis ,rem=TRUE)
freq<-get.mutation.frequencies(rownames(mut.matrix),"BRCA") 


#__ Parameters estimation
mod <- mutation.rem(cbind(freq, mut.matrix))
mod

#__ Probability of being clonal
mod <- mutation.rem(cbind(freq, mut.matrix), proba=TRUE)
mod