R/step2_prepare.R

In ShixiangWang/absCopyNumber: Tumor Purity, Ploidy and Absolute Copy Number Estimation

#' Prepare parameters for absCopyNumber calling
#'
#' @description This is the second step for absCopyNumber pipeline, user provide
#' parameters for model construction.
#' @param absCopyNumber a \code{absCopyNumber} object generated by \code{abs_initialize} function.
#' @param alpha.min the minimum allowed
#' value for tumor purity. Default is 0.20. If you do have the pathologist
#' estimate, set it as the lower bound of the pathologist estimate is usually
#' preferred.
#' @param alpha.max the maximum allowed
#' value for tumor purity. Default is 1.0. If you do have the pathologist
#' estimate, set it as the upper bound of the pathologist estimate is usually
#' preferred.
#' @param tau.min the minimum allowed value for tumor ploidy, default is 0.5.
#' @param tau.max the maximum allowed value for tumor ploidy, default is 8.
#' @param copyratio.min the minimum value of copy number ratio to assign weight in model, default is 0.2.
#' @param copyratio.max the maximum value of copy number ratio to assign weight in model, default is 3.
#' @param qmax maximum allowed absolute copy number for any segments, default is 10.
#' @param lamda The relative weight of the
#' segment copy ratio data over the SNV data. Must be a value in (0.0,1.0]. Only used when SNV
#' file is provided. The default value is 0.5,
#' which give equal weights to copy-number-based ratio estimator and SNV-frequency-based estimator. If
#' \code{lamda} is 1, only use copy-number-based ratio model to minimized objective function.
#' @param method method for object function optimization, should be one of "Grid Search", "Bayesian Optimization".
#' @param min.sol.freq A solution
#' should appear at least this proportion to be kept. Singleton solutions are
#' usually not trustable. By default (min.sol.freq=0.05), the program will only
#' retain solutions that cover at least 5 percent of the search space.
#' @param snv.type one of "somatic", "germline", if no SNV data, just let is be "somatic"
#' @author Shixiang Wang <w_shixiang@163.com>
#' @return a \code{absCopyNumber} object with parameters for model construction.
#' @import data.table
#' @export
#' @examples
#' file_cn = system.file("extdata/example.cn.txt.gz", package = "absCopyNumber")
#' file_snv = system.file("extdata/example.snv.txt.gz", package = "absCopyNumber")
#'
#' \donttest{
#' res1 =  abs_initialize(seg = file_cn, snv = file_snv, verbose = T)
#' res1 =  abs_prepare(res1)
#' }
#'
#' @seealso \code{\link[absCopyNumber]{absCopyNumber}}, \code{\link[absCopyNumber]{abs_initialize}}, , \code{\link[absCopyNumber]{abs_calling}}
abs_prepare = function(absCopyNumber,
                       alpha.min = 0.2,
                       alpha.max = 1.0,
                       tau.min = 0.5,
                       tau.max = 8.0,
                       copyratio.min = 0.2,
                       copyratio.max = 3,
                       qmax = 10,
                       lamda = 0.5,
                       method = c("Grid Search", "Bayesian Optimization"),
                       min.sol.freq = 0.05,
                       snv.type = c("somatic", "germline")) {
    stopifnot(alpha.min>=0.1, alpha.max<=1, tau.min>=0.0, tau.max<=20, min.sol.freq>=0, min.sol.freq<=1,
                lamda>0, lamda<=1)

    if(!inherits(absCopyNumber, "absCopyNumber")) {
        stop("Wrong input object, please check!")
    }

    method = match.arg(method)
    snv.type = match.arg(snv.type)
    platform = absCopyNumber@params$platform

    params = list(
        platform = platform,
        alpha.min = alpha.min,
        alpha.max = alpha.max,
        tau.min = tau.min,
        tau.max = tau.max,
        copyratio.min = copyratio.min,
        copyratio.max = copyratio.max,
        qmax = qmax,
        lamda = lamda,
        method = method,
        min.sol.freq = min.sol.freq,
        snv.type = snv.type
    )

    absCopyNumber@params = params
    return(absCopyNumber)
}


#' subset a absCopyNumber object by samples
#'
#' @param object a \code{absCopyNumber} object
#' @param samples a character vector to specify samples.
#' @author Shixiang Wang <w_shixiang@163.com>
#' @return a \code{absCopyNumber} object
#' @export
abs_subset = function(object, samples = NULL){
    if(is.null(samples)) {
        message("no sample name provided, return original object")
        return(object)
    }else{
        sample_exist = unique(object@data$sample)
        if(!all(samples %in% sample_exist)) {
            stop("detect invalid sample names:\n  ", paste(samples[!samples %in% sample_exist], collapse = " "))
        }else{
            object@data = object@data[sample %in% samples]
            if(!identical(object@SNV, data.table::data.table())){
                object@SNV = object@SNV[sample %in% samples]
            }
        }
        return(object)
    }
}

# setMethod(f = "abs_subset", signature = "absCopyNumber", definition = function(object, samples = NULL){
#     if(is.null(samples)) {
#         message("no sample name provided, return original object")
#         return(object)
#     }else{
#         sample_exist = unique(object@data$sample)
#         if(!all(samples %in% sample_exist)) {
#             stop("detect invalid sample names:\n  ", paste(samples[!samples %in% sample_exist], collapse = " "))
#         }else{
#             object@data = object@data[sample %in% samples]
#             if(!identical(object@SNV, data.table::data.table())){
#                 object@SNV = object@SNV[sample %in% samples]
#             }
#         }
#         return(object)
#     }
# })