diff --git a/NEWS.md b/NEWS.md index 845e561e..4e602024 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,6 @@ # sigminer 2.3.1 +- Updated `sig_fit()` related documents for better usage (#454). - Added `cluster_col` to `show_group_enrichment()`. - Fixed the bug that error returned when `cluster_row = TRUE` & `return_list = TRUE` in function `show_group_enrichment()`. - Fixed the error in generating DBS and INDEL matrix when only one sample input (#453). diff --git a/R/sig_fit.R b/R/sig_fit.R index 736ca77a..90248835 100644 --- a/R/sig_fit.R +++ b/R/sig_fit.R @@ -49,6 +49,52 @@ #' Nature genetics 48.6 (2016): 600. #' @examples #' \donttest{ +#' +#' # For mutational signatures ---------------- +#' # SBS is used for illustration, similar +#' # operations can be applied to DBS, INDEL, CN, RS, etc. +#' +#' # Load simulated data +#' data("simulated_catalogs") +#' data = simulated_catalogs$set1 +#' data[1:5, 1:5] +#' +#' # Fitting with all COSMIC v2 reference signatures +#' sig_fit(data, sig_index = "ALL") +#' # Check ?sig_fit for sig_db options +#' # e.g., use the COSMIC SBS v3 +#' sig_fit(data, sig_index = "ALL", sig_db = "SBS") +#' +#' # Fitting with specified signatures +#' # opt 1. use selected reference signatures +#' sig_fit(data, sig_index = c(1, 5, 9, 2, 13), sig_db = "SBS") +#' # opt 2. use user specified signatures +#' ref = get_sig_db()$db +#' ref[1:5, 1:5] +#' ref = ref[, 1:10] +#' # The `sig` used here can be result object from `sig_extract` +#' # or any reference matrix with similar structure (96-motif) +#' v1 = sig_fit(data, sig = ref) +#' v1 +#' +#' # If possible, auto-reduce the reference signatures +#' # for better fitting data from a sample +#' v2 = sig_fit(data, sig = ref, auto_reduce = TRUE) +#' v2 +#' +#' all.equal(v1, v2) +#' +#' # Some samples reported signatures dropped +#' # but its original activity values are 0s, +#' # so the data remain same (0 -> 0) +#' all.equal(v1[, 2], v2[, 2]) +#' +#' # For COSMIC_10, 6.67638 -> 0 +#' v1[, 4]; v2[, 4] +#' all.equal(v1[, 4], v2[, 4]) +#' +#' # For general purpose ----------------------- +#' #' W <- matrix(c(1, 2, 3, 4, 5, 6), ncol = 2) #' colnames(W) <- c("sig1", "sig2") #' W <- apply(W, 2, function(x) x / sum(x)) diff --git a/R/sig_fit_bootstrap.R b/R/sig_fit_bootstrap.R index f6a5bef6..117f5cc7 100644 --- a/R/sig_fit_bootstrap.R +++ b/R/sig_fit_bootstrap.R @@ -22,6 +22,12 @@ #' @keywords bootstrap #' @seealso [report_bootstrap_p_value], [sig_fit], [sig_fit_bootstrap_batch] #' @examples +#' +#' # This function is designed for processing +#' # one sample, thus is not very useful in practice +#' # please check `sig_fit_bootstrap_batch` +#' +#' # For general purpose ------------------- #' W <- matrix(c(1, 2, 3, 4, 5, 6), ncol = 2) #' colnames(W) <- c("sig1", "sig2") #' W <- apply(W, 2, function(x) x / sum(x)) diff --git a/R/sig_fit_bootstrap_batch.R b/R/sig_fit_bootstrap_batch.R index fe28d1af..55c69d5b 100644 --- a/R/sig_fit_bootstrap_batch.R +++ b/R/sig_fit_bootstrap_batch.R @@ -23,6 +23,25 @@ #' @seealso [sig_fit], [sig_fit_bootstrap] #' #' @examples +#' # For mutational signatures ---------------- +#' # SBS is used for illustration, similar +#' # operations can be applied to DBS, INDEL, CN, RS, etc. +#' +#' # Load simulated data +#' data("simulated_catalogs") +#' data = simulated_catalogs$set1 +#' data[1:5, 1:5] +#' +#' # Fitting with COSMIC reference signatures +#' \donttest{ +#' # Generally set n = 100 +#' rv = sig_fit_bootstrap_batch(data, +#' sig_index = c(1, 5, 9, 2, 13), +#' sig_db = "SBS", n = 10) +#' rv +#' } +#' +#' # For general purpose -------------------- #' W <- matrix(c(1, 2, 3, 4, 5, 6), ncol = 2) #' colnames(W) <- c("sig1", "sig2") #' W <- apply(W, 2, function(x) x / sum(x)) diff --git a/man/scoring.Rd b/man/scoring.Rd index df3dc02d..04a0c623 100644 --- a/man/scoring.Rd +++ b/man/scoring.Rd @@ -4,7 +4,7 @@ \alias{scoring} \title{Score Copy Number Profile} \usage{ -scoring(object, TD_size_cutoff = c(1000, 100000, 2000000), TD_cn_cutoff = Inf) +scoring(object, TD_size_cutoff = c(1000, 1e+05, 2e+06), TD_cn_cutoff = Inf) } \arguments{ \item{object}{a object of \link{CopyNumber}.} diff --git a/man/sig_auto_extract.Rd b/man/sig_auto_extract.Rd index 5e2a88e1..27b4097f 100644 --- a/man/sig_auto_extract.Rd +++ b/man/sig_auto_extract.Rd @@ -13,8 +13,8 @@ sig_auto_extract( ref_sigs = NULL, K0 = 25, nrun = 10, - niter = 200000, - tol = 0.0000001, + niter = 2e+05, + tol = 1e-07, cores = 1, optimize = FALSE, skip = FALSE, diff --git a/man/sig_fit.Rd b/man/sig_fit.Rd index 7a572453..df7c407a 100644 --- a/man/sig_fit.Rd +++ b/man/sig_fit.Rd @@ -113,6 +113,52 @@ feature CN is used. } \examples{ \donttest{ + +# For mutational signatures ---------------- +# SBS is used for illustration, similar +# operations can be applied to DBS, INDEL, CN, RS, etc. + +# Load simulated data +data("simulated_catalogs") +data = simulated_catalogs$set1 +data[1:5, 1:5] + +# Fitting with all COSMIC v2 reference signatures +sig_fit(data, sig_index = "ALL") +# Check ?sig_fit for sig_db options +# e.g., use the COSMIC SBS v3 +sig_fit(data, sig_index = "ALL", sig_db = "SBS") + +# Fitting with specified signatures +# opt 1. use selected reference signatures +sig_fit(data, sig_index = c(1, 5, 9, 2, 13), sig_db = "SBS") +# opt 2. use user specified signatures +ref = get_sig_db()$db +ref[1:5, 1:5] +ref = ref[, 1:10] +# The `sig` used here can be result object from `sig_extract` +# or any reference matrix with similar structure (96-motif) +v1 = sig_fit(data, sig = ref) +v1 + +# If possible, auto-reduce the reference signatures +# for better fitting data from a sample +v2 = sig_fit(data, sig = ref, auto_reduce = TRUE) +v2 + +all.equal(v1, v2) + +# Some samples reported signatures dropped +# but its original activity values are 0s, +# so the data remain same (0 -> 0) +all.equal(v1[, 2], v2[, 2]) + +# For COSMIC_10, 6.67638 -> 0 +v1[, 4]; v2[, 4] +all.equal(v1[, 4], v2[, 4]) + +# For general purpose ----------------------- + W <- matrix(c(1, 2, 3, 4, 5, 6), ncol = 2) colnames(W) <- c("sig1", "sig2") W <- apply(W, 2, function(x) x / sum(x)) diff --git a/man/sig_fit_bootstrap.Rd b/man/sig_fit_bootstrap.Rd index 38e4df49..390ca31a 100644 --- a/man/sig_fit_bootstrap.Rd +++ b/man/sig_fit_bootstrap.Rd @@ -102,6 +102,12 @@ This can be used to obtain the confidence of signature exposures or search the suboptimal decomposition solution. } \examples{ + +# This function is designed for processing +# one sample, thus is not very useful in practice +# please check `sig_fit_bootstrap_batch` + +# For general purpose ------------------- W <- matrix(c(1, 2, 3, 4, 5, 6), ncol = 2) colnames(W) <- c("sig1", "sig2") W <- apply(W, 2, function(x) x / sum(x)) diff --git a/man/sig_fit_bootstrap_batch.Rd b/man/sig_fit_bootstrap_batch.Rd index 61c1fc7b..bf7f7905 100644 --- a/man/sig_fit_bootstrap_batch.Rd +++ b/man/sig_fit_bootstrap_batch.Rd @@ -52,6 +52,25 @@ a \code{list} of \code{data.table}. Read \link{sig_fit_bootstrap} for more option setting. } \examples{ +# For mutational signatures ---------------- +# SBS is used for illustration, similar +# operations can be applied to DBS, INDEL, CN, RS, etc. + +# Load simulated data +data("simulated_catalogs") +data = simulated_catalogs$set1 +data[1:5, 1:5] + +# Fitting with COSMIC reference signatures +\donttest{ +# Generally set n = 100 +rv = sig_fit_bootstrap_batch(data, + sig_index = c(1, 5, 9, 2, 13), + sig_db = "SBS", n = 10) +rv +} + +# For general purpose -------------------- W <- matrix(c(1, 2, 3, 4, 5, 6), ncol = 2) colnames(W) <- c("sig1", "sig2") W <- apply(W, 2, function(x) x / sum(x)) diff --git a/tests/testthat/test-roxytest-testexamples-sig_fit.R b/tests/testthat/test-roxytest-testexamples-sig_fit.R index 8995d488..047de2fa 100644 --- a/tests/testthat/test-roxytest-testexamples-sig_fit.R +++ b/tests/testthat/test-roxytest-testexamples-sig_fit.R @@ -2,9 +2,55 @@ # File R/sig_fit.R: @testexamples -test_that("Function sig_fit() @ L99", { +test_that("Function sig_fit() @ L145", { + + # For mutational signatures ---------------- + # SBS is used for illustration, similar + # operations can be applied to DBS, INDEL, CN, RS, etc. + + # Load simulated data + data("simulated_catalogs") + data = simulated_catalogs$set1 + data[1:5, 1:5] + + # Fitting with all COSMIC v2 reference signatures + sig_fit(data, sig_index = "ALL") + # Check ?sig_fit for sig_db options + # e.g., use the COSMIC SBS v3 + sig_fit(data, sig_index = "ALL", sig_db = "SBS") + + # Fitting with specified signatures + # opt 1. use selected reference signatures + sig_fit(data, sig_index = c(1, 5, 9, 2, 13), sig_db = "SBS") + # opt 2. use user specified signatures + ref = get_sig_db()$db + ref[1:5, 1:5] + ref = ref[, 1:10] + # The `sig` used here can be result object from `sig_extract` + # or any reference matrix with similar structure (96-motif) + v1 = sig_fit(data, sig = ref) + v1 + + # If possible, auto-reduce the reference signatures + # for better fitting data from a sample + v2 = sig_fit(data, sig = ref, auto_reduce = TRUE) + v2 + + all.equal(v1, v2) + + # Some samples reported signatures dropped + # but its original activity values are 0s, + # so the data remain same (0 -> 0) + all.equal(v1[, 2], v2[, 2]) + + # For COSMIC_10, 6.67638 -> 0 + v1[, 4]; v2[, 4] + all.equal(v1[, 4], v2[, 4]) + + # For general purpose ----------------------- + W <- matrix(c(1, 2, 3, 4, 5, 6), ncol = 2) colnames(W) <- c("sig1", "sig2") W <- apply(W, 2, function(x) x / sum(x)) diff --git a/tests/testthat/test-roxytest-testexamples-sig_fit_bootstrap.R b/tests/testthat/test-roxytest-testexamples-sig_fit_bootstrap.R index cbf85b10..593de427 100644 --- a/tests/testthat/test-roxytest-testexamples-sig_fit_bootstrap.R +++ b/tests/testthat/test-roxytest-testexamples-sig_fit_bootstrap.R @@ -2,8 +2,14 @@ # File R/sig_fit_bootstrap.R: @testexamples -test_that("Function sig_fit_bootstrap() @ L61", { +test_that("Function sig_fit_bootstrap() @ L67", { + + # This function is designed for processing + # one sample, thus is not very useful in practice + # please check `sig_fit_bootstrap_batch` + + # For general purpose ------------------- W <- matrix(c(1, 2, 3, 4, 5, 6), ncol = 2) colnames(W) <- c("sig1", "sig2") W <- apply(W, 2, function(x) x / sum(x)) diff --git a/tests/testthat/test-roxytest-testexamples-sig_fit_bootstrap_batch.R b/tests/testthat/test-roxytest-testexamples-sig_fit_bootstrap_batch.R index 2a68f953..10f6a085 100644 --- a/tests/testthat/test-roxytest-testexamples-sig_fit_bootstrap_batch.R +++ b/tests/testthat/test-roxytest-testexamples-sig_fit_bootstrap_batch.R @@ -2,8 +2,27 @@ # File R/sig_fit_bootstrap_batch.R: @testexamples -test_that("Function sig_fit_bootstrap_batch() @ L44", { +test_that("Function sig_fit_bootstrap_batch() @ L63", { + # For mutational signatures ---------------- + # SBS is used for illustration, similar + # operations can be applied to DBS, INDEL, CN, RS, etc. + + # Load simulated data + data("simulated_catalogs") + data = simulated_catalogs$set1 + data[1:5, 1:5] + + # Fitting with COSMIC reference signatures + + # Generally set n = 100 + rv = sig_fit_bootstrap_batch(data, + sig_index = c(1, 5, 9, 2, 13), + sig_db = "SBS", n = 10) + rv + + + # For general purpose -------------------- W <- matrix(c(1, 2, 3, 4, 5, 6), ncol = 2) colnames(W) <- c("sig1", "sig2") W <- apply(W, 2, function(x) x / sum(x))