Clomial.iterate {Clomial} | R Documentation

## Runs EM iterations until convergence of the Clomial model.

### Description

Given the data and the initial values for the model parameters, runs EM iterations until convergence of the Clomial model.

### Usage

    Clomial.iterate(Dt, Dc, Mu, P, maxIt=100, U = NULL, PTrue = NULL,
    llCutoff = 10^(-3), computePFunction = compute.P.reparam,
    doSilentOptim = TRUE, doTalk = TRUE, doLog = TRUE, debug = FALSE,
    noiseReductionRate = 0.01, fliProb=0.05,conservative=TRUE)

### Arguments

`maxIt` | The maximum number of EM iterations.
`Dt` | A matrix which contains the counts of the alternative allele where rows correspond to the genomic loci, and columns correspond to the samples.
`Dc` | A matrix which contains the counts of the total number of mapped reads where rows correspond to the genomic loci, and columns correspond to the samples.
`Mu` | The initial value for the Mu matrix which models the genotypes, where rows and columns correspond to genomic loci and clones, accordingly.
`P` | The initial matrix of clonal frequency where rows and columns correspond to clones and samples, accordingly.
`U` | The true value for `Mu`, used for debugging purposes only.
`PTrue` | The true value for `P`, used for debugging purposes only.
`llCutoff` | EM iterations stops if the relative improvement in the log-likelihood is not more than this threshold.
`computePFunction` | The function used for updating `P`. For advanced development use only.
`doSilentOptim` | If TRUE, the optimization massages will not be reported.
`doTalk` | If FALSE, the function will be run in silent mode.
`doLog` | Highly recommended to set to TRUE. Then, the computations will be done in log space to avoid numerical issues.
`debug` | If TRUE, the debug mode will be turned on.
`noiseReductionRate` | The noise will be reduce by this rate after each EM iteration.
`fliProb` | A "flipping probability" used for noise injection which can be disabled when `fliProb=0`. After the first EM iteration, each entry of the matrix `Mu` such as `m` may change to `1-m` with this probability. This probability decreases on subsequent iterations.
`conservative` | Boolean where TRUE means noise will be injected only if likelihood is improved after an EM iteration, otherwise the original Mu matrix will be used for the next iteration. For expert use only.

### Details

Injecting noise can be done by assigning a positive value to `fliProb`, and can be disabled by `fliProb=0`. Noise injection is recommended for training models with a high number of clones (>4).

### Value

A list will be made with the following entries:

`Qs` | The history of matrices containing the posterior `Q` values.
`Ps` | The history of `P` matrices.
`Mus` | The history of `Mu` matrices.
`Mu` | The value of `Mu` after convergence.
`P` | The value of `P` after convergence.
`llCutoff` | The threshold used to decide convergence.
`LRatio` | The final relative improvement in the log likelihood which lead to convergence.
`Likelihoods` | The history of log-likelihoods.
`fliProb` | The final value of `fliProb` used for noise injection.
`timeTaken` | An object of class “difftime” which reports the total computational time for EM iterations.
`endTaken` | An object of class “POSIXct” (see DateTimeClasses) which reports the time EM iterations finished.

### Author(s)

Habil Zare

### References

Inferring clonal composition from multiple sections of a breast cancer, Zare et al., Submitted.

### See Also

`Clomial`, `Clomial`, `breastCancer`

### Examples

    set.seed(1)
    ## Getting data:
    data(breastCancer)
    Dc <- breastCancer$Dc
    Dt <- breastCancer$Dt
    freq1 <- Dt/Dc
    N <- nrow(Dc)
    S <- ncol(Dc)
    Cnum <- 4 ## assumed number of clones.
    ## Random initialization:
    random1 <- runif(n=N*(Cnum-1),min=rowMins(freq1)*0.9,max=rowMaxs(freq1)*1.1)
    random1[random1>1] <- 1
    random1[random1<0] <- 0
    Mu <- matrix(random1,N,Cnum-1)
    Mu <- cbind( matrix(0,N,1), Mu )
    rownames(Mu) <- rownames(Dc)
    colnames(Mu) <- paste("C",1:Cnum,sep="")
    P <- matrix(runif(Cnum*S),Cnum,S)
    rownames(P) <- colnames(Mu)
    colnames(P) <- colnames(Dc)
    ## Normalizing P:
    for( t in 1:S ){
    	s <- sum(P[,t])
    	P[,t] <- P[,t]/s
    }##End for.

    ## Running EM:
    model1 <- Clomial.iterate(Dt=Dt, Dc=Dc, Mu=Mu, P=P)
    print("Genotypes:")
    round(model1$Mu)
    print("Clone frequencies:")
    model1$P

[Package Clomial version 1.20.0 Index]