tensor {TCA}

Extracting hidden 3D signals from 2D input

Description

Estimates 3-dimensional signals (features by observations by sources) from input of mixtures (features by observations), under the assumption of the TCA model that each observation is a mixture of unique source-specific values (in each feature in the data). For example, in the context of tissue-level bulk DNA methylation data coming from a mixture of cell types (i.e. the input is methylation sites by individuals), tensor allows to estimate a tensor of cell-type-specific levels for each individual in each methylation site (i.e. a tensor of methylation sites by individuals by cell types).

Usage

tensor(
  X,
  tca.mdl,
  scale = FALSE,
  parallel = FALSE,
  num_cores = NULL,
  log_file = "TCA.log",
  debug = FALSE,
  verbose = TRUE
)

Arguments

X

An m by n matrix of measurements of m features for n observations. Each column in X is assumed to be a mixture of k sources. Note that X must include row names and column names and that NA values are currently not supported. X should not include features that are constant across all observations.

tca.mdl

The value returned by applying the function tca to X.

scale

A logical value indicating whether to divide the estimate of each entry in the tensor by its estimated standard deviation.

parallel

A logical value indicating whether to use parallel computing (possible when using a multi-core machine).

num_cores

A numeric value indicating the number of cores to use (activated only if parallel == TRUE). If num_cores == NULL then all available cores except for one will be used.

log_file

A path to an output log file. Note that if the file log_file already exists then logs will be appended to the end of the file. Set log_file to NULL to prevent output from being saved into a file; note that if verbose == FALSE then no output file will be generated regardless of the value of log_file.

debug

A logical value indicating whether to set the logger to a more detailed debug level; set debug to TRUE before reporting issues.

verbose

A logical value indicating whether to print logs.

Details

See tca for notations and details about the TCA model. Given estimates of the parameters of the model (given by tca), tensor uses the conditional distribution Z_{hj}^i|X_{ji}=x_{ji} for estimating the k source-specific levels of each observation i in each feature j.

Value

A list with the estimated source-specific values. The first element in the list is an m by n matrix (features by observations) corresponding to the estimated values coming from the first source, the second element in the list is another m by n matrix (features by observations) corresponding to the estimated values coming from the second source and so on.

References

Rahmani E, Schweiger R, Rhead B, Criswell LA, Barcellos LF, Eskin E, Rosset S, Sankararaman S, Halperin E. Cell-type-specific resolution epigenetics without the need for cell sorting or single-cell biology. Nature Communications 2019.

Examples

data <- test_data(50, 20, 3, 2, 2, 0.01)
tca.mdl <- tca(X = data$X, W = data$W, C1 = data$C1, C2 = data$C2)
Z_hat <- tensor(data$X, tca.mdl)