check website

NAMESPACE

@@ -3,6 +3,7 @@
 export(colocboost)
 export(colocboost_plot)
 export(get_cormat)
+export(get_cos)
 export(get_cos_summary)
 export(get_strong_colocalization)
 importFrom(grDevices,adjustcolor)

R/colocboost.R

@@ -95,10 +95,29 @@
 #' \item{cos_details}{A object with all information for colocalization results.}
 #' \item{data_info}{A object with detailed information from input data}
 #' \item{model_info}{A object with detailed information for colocboost model}
+#' 
+#' @examples
+#' # colocboost example
+#' set.seed(1)
+#' N = 1000
+#' P = 100
+#' # Generate X with LD structure
+#' sigma <- 0.9^abs(outer(1:P, 1:P, "-"))
+#' X <- MASS::mvrnorm(N, rep(0, P), sigma)
+#' colnames(X) <- paste0("SNP", 1:P)
+#' L = 3
+#' true_beta <- matrix(0, P, L)
+#' true_beta[5, 1] <- 0.5  # SNP5 affects trait 1
+#' true_beta[5, 2] <- 0.4  # SNP5 also affects trait 2 (colocalized)
+#' true_beta[10, 2] <- 0.3 # SNP10 only affects trait 2
+#' true_beta[20, 3] <- 0.6 # SNP20 only affects trait 3
+#' Y <- matrix(0, N, L)
+#' for (l in 1:L){  Y[, l] <- X %*% true_beta[, l] + rnorm(N, 0, 1) }
+#' res <- colocboost(X = X, Y = Y)
 #'
+#' @family colocboost
 #' @importFrom stats na.omit
 #' @export
-
 colocboost <- function(X = NULL, Y = NULL, # individual data
                        sumstat = NULL, LD = NULL, # summary statistics: either Z, bhat, sebhat, N, var_Y,
                        ###### - index dict for X match multiple Y / LD match multiple sumstat

R/colocboost_inference.R

@@ -34,8 +34,7 @@ colocboost_post_inference <- function() {
 #'
 #' @return A correlation matrix (LD matrix).
 #'
-#' @rdname colocboost_post_inference
-#' @keywords cb_post_inference
+#' @family colocboost_utilities
 #' @export
 get_cormat <- function(X, intercepte = FALSE) {
   X <- t(X)

R/colocboost_output.R

@@ -7,7 +7,7 @@
 #' @param cb_output Output object from `colocboost` analysis
 #' @param outcome_names Optional vector of names of outcomes, which has the same order as Y in the original analysis.
 #' @param interest_outcome Optional vector specifying a subset of outcomes from \code{outcome_names} to focus on. When provided, only colocalization events that include at least one of these outcomes will be returned.
-#' @param gene_name Optional character string. When provided, adds a column with this gene name to the output table for easier filtering in downstream analyses.
+#' @param region_name Optional character string. When provided, adds a column with this gene name to the output table for easier filtering in downstream analyses.
 #'
 #' @return A summary table for colocalization events with the following columns:
 #' \item{focal_outcome}{The focal outcome being analyzed if exists. Otherwise, it is \code{FALSE}.}
@@ -23,12 +23,12 @@
 #' \item{colocalized_variables}{List of colocalized variables}
 #' \item{colocalized_variables_vcp}{Variant colocalization probabilities for all colocalized variables}
 #'
-#' @keywords cb_get_functions
+#' @family colocboost_inference
 #' @export
 get_cos_summary <- function(cb_output,
                             outcome_names = NULL,
                             interest_outcome = NULL,
-                            gene_name = NULL) {
+                            region_name = NULL) {
   if (!inherits(cb_output, "colocboost")) {
     stop("Input must from colocboost output!")
   }
@@ -65,8 +65,8 @@ get_cos_summary <- function(cb_output,
     summary_table[, 10] <- unlist(sapply(coloc_sets, function(tmp) paste0(tmp, collapse = "; ")))
     summary_table[, 11] <- unlist(sapply(cb_output$cos_details$cos$cos_variables, function(tmp) paste0(tmp, collapse = "; ")))
     summary_table[, 12] <- unlist(sapply(coloc_sets, function(tmp) paste0(vcp[tmp], collapse = "; ")))
-    if (!is.null(gene_name)) {
-      summary_table$gene_name <- gene_name
+    if (!is.null(region_name)) {
+      summary_table$region_name <- region_name
     }
     # - if focal colocalization
     focal_outcome_idx <- which(cb_output$data_info$outcome_info$is_focal)
@@ -128,7 +128,7 @@ get_cos_summary <- function(cb_output,
 #' \item{data_info}{A object with detailed information from input data}
 #' \item{model_info}{A object with detailed information for colocboost model}
 #'
-#' @keywords cb_get_functions
+#' @family colocboost_inference
 #' @export
 get_strong_colocalization <- function(cb_output,
                                       cos_npc_cutoff = 0.5,
@@ -359,22 +359,22 @@ get_strong_colocalization <- function(cb_output,
 #'
 #' @param cb_output Output object from `colocboost` analysis
 #' @param outcome_names Optional vector of names of outcomes, which has the same order as Y in the original analysis.
-#' @param gene_name Optional character string. When provided, adds a column with this gene name to the output table for easier filtering in downstream analyses.
+#' @param region_name Optional character string. When provided, adds a column with this gene name to the output table for easier filtering in downstream analyses.
 #'
 #' @return A summary table for fine-mapped events with the following columns:
 #' \item{outcomes}{Outcomes analyzed }
 #' \item{ucos_id}{Unique identifier for fine-mapped confidence sets }
 #' \item{purity}{Minimum absolute correlation of variables with in fine-mapped confidence sets }
-#' \item{top_variable}{The variable with highest posterior inclusion probability (PIP) }
-#' \item{top_variable_pip}{Posterior inclusion probability (PIP) for the top variable}
+#' \item{top_variable}{The variable with highest variant-level probability of association (VPA) }
+#' \item{top_variable_vpa}{Variant-level probability of association (VPA) for the top variable}
 #' \item{n_variables}{Number of variables in colocalization confidence set (CoS)}
 #' \item{ucos_index}{Indices of fine-mapped variables}
 #' \item{ucos_variables}{List of fine-mapped variables}
-#' \item{ucos_variables_pip}{Posterior inclusion probability (PIP) for all fine-mapped variables}
+#' \item{ucos_variables_vpa}{Variant-level probability of association (VPA) for all fine-mapped variables}
 #'
-#' @keywords cb_get_functions
+#' @family colocboost_inference
 #' @noRd
-get_ucos_summary <- function(cb_output, outcome_names = NULL, gene_name = NULL) {
+get_ucos_summary <- function(cb_output, outcome_names = NULL, region_name = NULL) {
   if (!inherits(cb_output, "colocboost")) {
     stop("Input must from colocboost object!")
   }
@@ -385,26 +385,26 @@ get_ucos_summary <- function(cb_output, outcome_names = NULL, gene_name = NULL)
     if (!is.null(outcome_names)) {
       cs_outcome <- outcome_names
     }
-    pip <- as.numeric(cb_output$pip)
+    vpa <- as.numeric(cb_output$vpa)
 
     summary_table <- matrix(NA, nrow = length(specific_cs$ucos$ucos_index), ncol = 9)
     colnames(summary_table) <- c(
       "outcomes", "ucos_id", "purity",
-      "top_variable", "top_variable_pip", "n_variables", "ucos_index",
-      "ucos_variables", "ucos_variables_pip"
+      "top_variable", "top_variable_vpa", "n_variables", "ucos_index",
+      "ucos_variables", "ucos_variables_vpa"
     )
     summary_table <- as.data.frame(summary_table)
     summary_table[, 1] <- cs_outcome[unlist(specific_cs$ucos_outcomes$outcome_index)]
     summary_table[, 2] <- names(specific_cs$ucos$ucos_index)
     summary_table[, 3] <- as.numeric(diag(as.matrix(specific_cs$ucos_purity$min_abs_cor)))
     summary_table[, 4] <- unlist(sapply(specific_cs$ucos$ucos_variables, function(tmp) tmp[1]))
-    summary_table[, 5] <- sapply(specific_cs$ucos$ucos_index, function(tmp) max(pip[tmp]))
+    summary_table[, 5] <- sapply(specific_cs$ucos$ucos_index, function(tmp) max(vpa[tmp]))
     summary_table[, 6] <- as.numeric(sapply(specific_cs$ucos$ucos_index, length))
     summary_table[, 7] <- unlist(sapply(specific_cs$ucos$ucos_index, function(tmp) paste0(tmp, collapse = "; ")))
     summary_table[, 8] <- unlist(sapply(specific_cs$ucos$ucos_variables, function(tmp) paste0(tmp, collapse = "; ")))
-    summary_table[, 9] <- unlist(sapply(specific_cs$ucos$ucos_index, function(tmp) paste0(pip[tmp], collapse = "; ")))
-    if (!is.null(gene_name)) {
-      summary_table$gene_name <- gene_name
+    summary_table[, 9] <- unlist(sapply(specific_cs$ucos$ucos_index, function(tmp) paste0(vpa[tmp], collapse = "; ")))
+    if (!is.null(region_name)) {
+      summary_table$region_name <- region_name
     }
   } else {
     summary_table <- NULL
@@ -413,9 +413,17 @@ get_ucos_summary <- function(cb_output, outcome_names = NULL, gene_name = NULL)
 }
 
 #' Extract CoS simply change the coverage without checking purity
-#' @keywords cb_get_functions
-#' @noRd
-get_cos_different_coverage <- function(cb_output, coverage = 0.95) {
+#' 
+#' @description `get_cos` get the colocalization confidence sets (CoS) with different coverage.
+#' 
+#' @param cb_output Output object from `colocboost` analysis
+#' @param coverage A number between 0 and 1 specifying the \dQuote{coverage} of the estimated colocalization confidence sets (CoS) (default is 0.95).
+#' 
+#' @return A list of indices of variables in each CoS.
+#' 
+#' @family colocboost_utilities
+#' @export
+get_cos <- function(cb_output, coverage = 0.95) {
   cos_vcp <- cb_output$cos_details$cos_vcp
   cos_diff_coverage <- lapply(cos_vcp, function(w) {
     unlist(get_in_cos(w, coverage = coverage))

R/colocboost_plot.R

@@ -6,7 +6,7 @@
 #'
 #' @param cb_output Output object from `colocboost` analysis
 #' @param y Specifies the y-axis values, default is "log10p" for -log10 transformed marginal association p-values.
-#' @param pos Optional plotting range of x-axis to zoom in to a specific region.
+#' @param grange Optional plotting range of x-axis to zoom in to a specific region.
 #' @param plot_focal_only Logical, if TRUE only plots colocalization with focal outcome, default is FALSE.
 #' @param plot_cos_idx Optional indices of CoS to plot
 #' @param outcome_idx Optional indices of outcomes to include in the plot. \code{outcome_idx=NULL} to plot only the outcomes having colocalization.
@@ -17,7 +17,7 @@
 #' @param outcome_names Optional vector of outcomes names for the subtitle of each figure. \code{outcome_names=NULL} for the outcome name shown in \code{data_info}.
 #' @param plot_cols Number of columns in the plot grid, default is 2. If you have many colocalization. please consider increasing this.
 #' @param variant_coord Logical, if TRUE uses variant coordinates on x-axis, default is FALSE. This is required the variable names including position information.
-#' @param show_hits Logical, if TRUE shows top variables for each CoS, default is FALSE
+#' @param show_top_variables Logical, if TRUE shows top variables for each CoS, default is FALSE
 #' @param show_cos_to_uncoloc Logical, if TRUE shows colocalization to uncolocalized outcomes to diagnose, default is FALSE
 #' @param show_cos_to_uncoloc_idx Optional indices for showing CoS to all uncolocalized outcomes
 #' @param show_cos_to_uncoloc_outcome Optional outcomes for showing CoS to uncolocalized outcomes
@@ -37,11 +37,11 @@
 #' @importFrom utils head tail
 #' @importFrom graphics abline axis legend mtext par points text
 #' @importFrom grDevices adjustcolor
-#'
-#' @keywords cb_plot
+#' 
+#' @family colocboost_plot
 #' @export
 colocboost_plot <- function(cb_output, y = "log10p",
-                            pos = NULL,
+                            grange = NULL,
                             plot_focal_only = FALSE,
                             plot_cos_idx = NULL,
                             outcome_idx = NULL,
@@ -52,7 +52,7 @@ colocboost_plot <- function(cb_output, y = "log10p",
                             outcome_names = NULL,
                             plot_cols = 2,
                             variant_coord = FALSE,
-                            show_hits = FALSE,
+                            show_top_variables = FALSE,
                             show_cos_to_uncoloc = FALSE,
                             show_cos_to_uncoloc_idx = NULL,
                             show_cos_to_uncoloc_outcome = NULL,
@@ -91,20 +91,20 @@ colocboost_plot <- function(cb_output, y = "log10p",
   )
 
   colocboost_plot_basic <- function(cb_plot_input, cb_plot_init,
-                                    outcome_idx = NULL, pos = NULL,
+                                    outcome_idx = NULL, grange = NULL,
                                     plot_cols = 2,
                                     add_vertical = FALSE, add_vertical_idx = NULL,
-                                    show_hits = TRUE,
+                                    show_top_variables = TRUE,
                                     ...) {
     args <- list(...)
     args <- c(args, cb_plot_init[c("xlab", "ylab")])
     args$col <- cb_plot_init$bg
-    if (is.null(pos)) {
+    if (is.null(grange)) {
       args$x <- cb_plot_init$x
       y <- cb_plot_init$y
     } else {
-      args$x <- cb_plot_init$x[pos]
-      y <- lapply(cb_plot_init$y, function(yy) yy[pos])
+      args$x <- cb_plot_init$x[grange]
+      y <- lapply(cb_plot_init$y, function(yy) yy[grange])
     }
     args$pch <- cb_plot_init$pch
     args$cex.axis <- cb_plot_init$axis_size
@@ -199,7 +199,7 @@ colocboost_plot <- function(cb_output, y = "log10p",
           x0 <- intersect(args$x, cs)
           y1 <- args$y[match(x0, args$x)]
           points(x0, y1, pch = 21, bg = legend_text$col[i.cs], col = NA, cex = 2.5, lwd = 2.5)
-          if (show_hits) {
+          if (show_top_variables) {
             # add the hits points with "red"
             cs_hits <- as.numeric(cb_plot_input$cos_hits[[i.cs]])
             x_hits <- intersect(args$x, cs_hits)
@@ -250,10 +250,10 @@ colocboost_plot <- function(cb_output, y = "log10p",
   }
 
   colocboost_plot_basic(cb_plot_input, cb_plot_init,
-    pos = pos,
+    grange = grange,
     outcome_idx = outcome_idx, plot_cols = plot_cols,
     add_vertical = add_vertical, add_vertical_idx = add_vertical_idx,
-    show_hits = show_hits,
+    show_top_variables = show_top_variables,
     ...
   )
 }
@@ -378,7 +378,8 @@ get_input_plot <- function(cb_output, plot_cos_idx = NULL,
     "coef" = coef,
     "cos" = coloc_cos,
     "cos_hits" = coloc_hits,
-    "coloc_index" = coloc_index
+    "coloc_index" = coloc_index,
+    "select_cos" = select_cs
   )
 
   # check if plot cos to uncolocalized outcome
@@ -493,7 +494,7 @@ plot_initial <- function(cb_plot_input, y = "log10p",
 
     # cos_color <- c("#1F70A9", "#33A02C", "#CAB2D6", "#EA7827")
   }
-  args$col <- cos_color
+  args$col <- cos_color[cb_plot_input$select_cos]
 
   # - set data and x-lab and y-lab
   if (y == "log10p") {

R/data.R

@@ -10,6 +10,7 @@
 #'   \item{TrueCausalVariants}{List of causal variants}
 #' }
 #' @source See Cao et. al. 2025 for details. TO-DO-LIST
+#' @family colocboost_data
 "Ind_5traits"
 
 #' Summary level data for 5 traits
@@ -23,6 +24,7 @@
 #'   \item{TrueCausalVariants}{List of causal variants}
 #' }
 #' @source See Cao et. al. 2025 for details. TO-DO-LIST
+#' @family colocboost_data
 "Sumstat_5traits"
 
 
@@ -38,6 +40,7 @@
 #'   \item{TrueCausalVariants}{List of causal variants}
 #' }
 #' @source See Cao et. al. 2025 for details. TO-DO-LIST
+#' @family colocboost_data
 "Heterogeneous_Effect"
 
 
@@ -53,6 +56,7 @@
 #'   \item{TrueCausalVariants}{List of causal variants}
 #' }
 #' @source See Cao et. al. 2025 for details. TO-DO-LIST
+#' @family colocboost_data
 "Weaker_GWAS_Effect"
 
 
@@ -68,4 +72,5 @@
 #'   \item{TrueCausalVariants}{List of causal variants}
 #' }
 #' @source See Cao et. al. 2025 for details. TO-DO-LIST
+#' @family colocboost_data
 "Non_Causal_Strongest_Marginal"

_pkgdown.yml

@@ -2,3 +2,29 @@ url: https://statfungen.github.io/colocboost
 
 template:
   bootstrap: 5
+
+reference:
+  - title: "Example Data"
+    desc: "Example datasets for demonstration and testing"
+    contents:
+    - has_concept("colocboost_data")
+
+  - title: "ColocBoost Main Function"
+    desc: "Core functions for colocalization analysis"
+    contents:
+    - has_concept("colocboost")
+
+  - title: "Post Inference"
+    desc: "Functions for post-analysis inference of ColocBoost results"
+    contents:
+    - has_concept("colocboost_inference")
+
+  - title: "Visualization"
+    desc: "Functions for visualizing ColocBoost results"
+    contents:
+    - has_concept("colocboost_plot")
+
+  - title: "Utilities"
+    desc: "Helper functions and utilities"
+    contents:
+    - has_concept("colocboost_utilities")