Repository Mirror for your Cloud Server and Webhosting

Type:

Package

Title:

Subclone Multiplicity Allocation and Somatic Heterogeneity

Version:

1.0.0

Date:

2025-02-07

Description:

Cluster user-supplied somatic read counts with corresponding allele-specific copy number and tumor purity to infer feasible underlying intra-tumor heterogeneity in terms of number of subclones, multiplicity, and allocation (Little et al. (2019) <doi:10.1186/s13073-019-0643-9>).

License:

GPL (≥ 3)

Imports:

Rcpp, stats, smarter, reshape2, ggplot2

LinkingTo:

Rcpp, RcppArmadillo

Encoding:

UTF-8

LazyData:

true

Depends:

R (≥ 2.10)

RoxygenNote:

7.2.3

Suggests:

knitr, devtools

VignetteBuilder:

knitr

NeedsCompilation:

yes

Packaged:

2025-02-26 05:10:10 UTC; Admin

Author:

Paul Little [aut, cre]

Maintainer:

Paul Little <pllittle321@gmail.com>

Repository:

CRAN

Date/Publication:

2025-02-27 16:40:06 UTC

ITH_optim

Description

Performs EM algorithm for a given configuration matrix

Usage

ITH_optim(
  my_data,
  my_purity,
  init_eS,
  pi_eps0 = NULL,
  my_unc_q = NULL,
  max_iter = 4000,
  my_epsilon = 1e-06
)

Arguments

my_data

A R dataframe containing the following columns:

tAD: tumor alternate read counts
tRD: tumor reference read counts
CN_1: minor allele count
CN_2: major allele count, where CN_1 <= CN_2
tCN: CN_1 + CN_2

my_purity

A single numeric value of known/estimated purity

init_eS

A subclone configuration matrix pre-defined in R list eS

pi_eps0

A user-specified parameter denoting the proportion of loci not explained by the combinations of purity, copy number, multiplicity, and allocation. If NULL, it is initialized at 1e-3. If set to 0.0, the parameter is not estimated.

my_unc_q

An optimal initial vector for the unconstrained q vector, useful after running grid_ITH_optim. If this variable is NULL, then the subclone proportions, q, are randomly initialized. For instance, if my_unc_q = ( x1 , x2 ), then q = ( exp(x1) / (1 + exp(x1) + exp(x2)) , exp(x2) / (1 + exp(x1) + exp(x2)) , 1 / (1 + exp(x1) + exp(x2)).

max_iter

Positive integer, preferably 1000 or more, setting the maximum number of iterations

my_epsilon

Convergence criterion threshold for changes in the log likelihood, preferably 1e-6 or smaller

Value

If the EM algorithm converges, the output will be a list containing

iter: number of iterations
converge: convergence status
unc_q0: initial unconstrained subclone proportions parameter
unc_q: unconstrained estimate of q
q: estimated subclone proportions among cancer cells
CN_MA_pi: estimated mixture probabilities of multiplicities and allocations given copy number states
eta: estimated subclone proportion among tumor cells
purity: user-inputted tumor purity
entropy: estimated entropy
infer: A R dataframe containing inferred variant allocations (infer_A), multiplicities (infer_M), cellular prevalences (infer_CP).
ms: model size, number of parameters within parameter space
LL: The observed log likelihood evaluated at maximum likelihood estimates.
AIC = 2 * LL - 2 * ms: Negative AIC, used for model selection
BIC = 2 * LL - ms * log(LOCI): Negative BIC, used for model selection
LOCI: The number of inputted somatic variants.

A collection of pre-defined subclone configurations.

Description

A R list containing subclone configurations in matrix form for 1 to 5 subclones. For each matrix, each column corresponds to a subclone and each row corresponds to a variant's allocation across all subclones. For example, the first row of each matrix is a vector of 1's to represent clonal variants, variants present in all subclones.

Usage

eS

Format

An object of class list of length 5.

gen_ITH_RD

Description

Simulates observed alternate and reference read counts

Usage

gen_ITH_RD(DATA, RD)

Arguments

DATA

The output data.frame from gen_subj_truth

RD

A positive integer for the mean read depth generated from the negative binomial distribution

Value

A matrix of simulated alternate and reference read counts.

gen_subj_truth

Description

Simulates copy number states, multiplicities, allocations

Usage

gen_subj_truth(mat_eS, maxLOCI, nCN = NULL)

Arguments

mat_eS

A subclone configuration matrix pre-defined in R list eS

maxLOCI

A positive integer number of simulated somatic variant calls

nCN

A positive integer for the number of allelic copy number pairings to sample from. If NULL, it will be randomly sampled between 1 and 5.

Value

A list containing the following components:

subj_truth: dataframe of each variant's simulated minor (CN_1) and major (CN_2) copy number states, total copy number (tCN), subclone allocation (true_A), multiplicity (true_M), mutant allele frequency (true_MAF), and cellular prevalence (true_CP)
purity: tumor purity
eta: the product of tumor purity and subclone proportions
q: vector of subclone proportions

grid_ITH_optim

Description

This function performs a grid search over enumerated configurations within the pre-defined list eS

Usage

grid_ITH_optim(
  my_data,
  my_purity,
  list_eS,
  pi_eps0 = NULL,
  trials = 20,
  max_iter = 4000,
  my_epsilon = 1e-06
)

Arguments

my_data

A R dataframe containing the following columns:

tAD: tumor alternate read counts
tRD: tumor reference read counts
CN_1: minor allele count
CN_2: major allele count, where CN_1 <= CN_2
tCN: CN_1 + CN_2

my_purity

A single numeric value of known/estimated purity

list_eS

A nested list of subclone configuration matrices

pi_eps0

trials

Positive integer, number of random initializations of subclone proportions

max_iter

Positive integer, preferably 1000 or more, setting the maximum number of iterations

my_epsilon

Convergence criterion threshold for changes in the log likelihood, preferably 1e-6 or smaller

Value

A R list containing two objects. GRID is a dataframe where each row denotes a feasible subclone configuration with corresponding subclone proportion estimates q and somatic variant allocations alloc. INFER is a list where INFER[[i]] corresponds to the i-th row or model of GRID.

vis_GRID

Description

A simple visualization of SMASH's grid of solutions

Usage

vis_GRID(GRID)

Arguments

GRID

The GRID object output from grid_ITH_optim.

Value

A ggplot object for data visualization