polish documentation

Author: KatjaDanielzik

DESCRIPTION

@@ -12,11 +12,11 @@ BugReports: https://github.com/KatjaDanielzik/BayesVolcano/issues
 Description: Bayesian models are used to estimate effect sizes (e.g., gene expression changes,
     protein abundance differences, drug response effects) while accounting for uncertainty, 
     small sample sizes, and complex experimental designs.
-    However, Bayesian outputs are often difficult to interpret at a glance.
-    One way to quickly identify important biological changes of frequentist analysis 
+    However, Bayesian posteriors of models with many parameters are often difficult to interpret at a glance.
+    One way to quickly identify important biological changes based on frequentist analysis 
     are volcano plots (using fold-changes and p-values).
-    Bayesian volcano plots bring together the uncertainty aware power of Bayesian 
-    models and the familiar visualization of volcano plots.
+    Bayesian volcano plots bring together the explicit treatment of uncertainty in 
+    Bayesian models and the familiar visualization of volcano plots.
 License: GPL (>= 3)
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)

R/plot_volcano.R

@@ -45,7 +45,7 @@ plot_volcano <- function(result,
                          label.parameter.threshold = NULL,
                          label.pi.threshold = NULL,
                          title = "Bayesian Volcano Plot",
-                         xlab = "parameter value"){
+                         xlab = "median parameter value"){
 
   # Input validation
   if (!is.list(result) || !("result" %in% names(result)) || !("meta" %in% names(result))) {
@@ -93,14 +93,14 @@ plot_volcano <- function(result,
 
   # create base plot ####
   ## get threshold
-  t <- result$meta$threshold
+  t <- result$meta$zero.effect
 
-  subtitle <- paste0("vertical black line: threshold for pi = ",t)
+  subtitle <- paste0("vertical black line: zero effect of parameter = ",t)
 
   p <- ggplot(df,(aes(x=parameter.median,y=pi.value))) +
     geom_point()+
     theme_bw()+
-    # mark user set threshold
+    # mark user set zero.effect
     geom_vline(aes(xintercept=t))+
     xlab(xlab)+
     ylab("pi")+

R/prepare_volcano_df.R

@@ -12,13 +12,13 @@
 #'     \item \code{label}: the biological label (e.g., `cell.line`, `time.point`)
 #'     \item Optional: other columns (e.g., `group`, `condition`) for future coloring
 #'   }
-#' @param threshold For which threshold to calculate pi. Default is 0.   
+#' @param zero.effect Central parameter value corresponding to no effect (default t=0).
 #' @param CrI.low lower bound of credible interval
 #' @param CrI.high upper bound of credible interval
 #'
 #' @details
 #' Only returns pi-values and summaries for parameters that are in posterior and
-#' annotation_df. 
+#' annotation_df. For formula see README or Vignette
 #' 
 #'
 #' @return A list with:
@@ -37,7 +37,7 @@
 #' \itemize{
 #'   \item \code{CrI.low}: lower CrI boundary set by user
 #'   \item \code{CrI.high}: upper CrI boundary set by user
-#'   \item \code{threshold}: threshold for pi set by user
+#'   \item \code{zero.effect}: zero.effect for pi set by user
 #'   }
 #'}
 #'
@@ -77,16 +77,16 @@
 prepare_volcano_df <- function(
     posterior,
     annotation_df,
-    threshold = 0,
+    zero.effect = 0,
     CrI.low = 0.025,
     CrI.high = 0.975
 ) {
   # Input validation
   if (!is.data.frame(posterior)) {
     stop("Argument 'posterior' must be a data frame.")
   }
-  if(!is.numeric(threshold)){
-    stop("threshold has to be numeric")
+  if(!is.numeric(zero.effect)){
+    stop("zero.effect has to be numeric")
   }
   if (any(!is.numeric(c(CrI.low, CrI.high)))) {
     stop("CrI.low and CrI.high must be numeric.")
@@ -117,7 +117,8 @@ prepare_volcano_df <- function(
     values <- posterior[[param]]
 
     # Compute stats
-    pi_value <- .pi_value(values,threshold)
+    pi_value <- .pi_value(value = values,
+                          zero.effect = zero.effect)
     median_val <- median(values)
     crI_low <- stats::quantile(values, probs = CrI.low, na.rm = TRUE)
     crI_high <- stats::quantile(values, probs = CrI.high, na.rm = TRUE)
@@ -147,5 +148,5 @@ prepare_volcano_df <- function(
 
   return(list(result=result,meta=list(CrI.low=as.numeric(CrI.low),
                                       CrI.high=as.numeric(CrI.high),
-                                      threshold=as.numeric(threshold))))
+                                      zero.effect=as.numeric(zero.effect))))
 }

R/utils.R

@@ -3,12 +3,12 @@
 #' Calculates pi-value as integral under
 #'
 #' @param value numerical vector of posterior draws
-#' @param threshold numerical value indicating for which treshhold to calculate pi
+#' @param zero.effect numerical value indicating for which treshhold to calculate pi
 #'
 #' @returns pi-value
 #' @keywords internal
-.pi_value <- function(value, threshold) {
+.pi_value <- function(value, zero.effect) {
   l <- length(value)
-  pi <- 2*max(sum(value<=threshold)/l, sum(value>=threshold)/l)-1
+  pi <- 2*max(sum(value<=zero.effect)/l, sum(value>=zero.effect)/l)-1
   return(pi)
 }

README.md

@@ -16,23 +16,33 @@ to interpret at a glance.
 One way to quickly identify important biological changes based on frequentist analysis 
 are volcano plots (using fold-changes and p-values).
 
-Bayesian volcano plots bring together the uncertainty aware power of Bayesian 
-models and the familiar visualization of volcano plots by:
+Bayesian volcano plots bring together the explicit treatment of uncertainty in
+Bayesian models and the familiar visualization of volcano plots by:
+
+   1) Calculation and using ![equation](https://latex.codecogs.com/svg.image?%5Cpi)-values
+      on the y-axis as a summary of posterior parameter values lying beyond a threshold.
+      With *i* being one entity that was modeled, *param* the estimated parameter and *t*
+      the central parameter value corresponding to no effect (default t=0).
+      
+      ![equation](https://latex.codecogs.com/svg.image?%5Cpi_%7Bi%7D=2*max%5Cleft(%5Cint_%7Bparam_%7Bi%7D=-%5Cinfty%7D%5E%7Bt%7Dp(param_%7Bi%7D)%5C,dparam_%7Bi%7D,%5Cint_%7Bparam_%7Bi%7D=t%7D%5E%7B%5Cinfty%7Dp(param_%7Bi%7D)%5C,dparam_%7Bi%7D%5Cright)-1)
+
+
+   2) Preserving the familiar, intuitive volcano structure.
+
+      The figure below shows the distribution of the posterior samples on the right
+      and their translation into a Bayesian volcano plot on the righth.
+
+      ![](man/figures/README-explain_volcano.png)
+
 
-   1) Showing posterior medians on the x-axis.
-   2) Calculation and using ![equation](https://latex.codecogs.com/svg.image?%5Cpi)-values on the y-axis as a summary 
-      of posterior parameter values lying beyond a threshold.
-      With *i* being one entity that was modeled and *param* the estimated parameter
-![equation](https://latex.codecogs.com/svg.image?%5Cpi_%7Bi%7D=2*max%5Cleft(%5Cint_%7Bparam_%7Bi%7D=-%5Cinfty%7D%5E%7B0%7Dp(param_%7Bi%7D)%5C,d%20param_%7Bi%7D,%5Cint_%7Bparam_%7Bi%7D=0%7D%5E%7B%5Cinfty%7Dp(param_%7Bi%7D)%5C,d%20param_%7Bi%7D%5Cright)-1%20)
 
    3) Optional displaying credible intervals (CrIs) to visualize uncertainty.
-   4) Preserving the familiar, intuitive volcano structure.
 
-We are not the first to think about the concept of Bayesian volcano plots [Sousa et al. 2020](https://doi.org/10.1016/j.aca.2019.11.006) introduced them as a single
-use case (their b-values correspond to our pi-values)
-but to our knowledge we are the first to provide an R-package
+We are not the first to think about the concept of Bayesian volcano plots: [Sousa et al. 2020](https://doi.org/10.1016/j.aca.2019.11.006) introduced them as a single
+use case (pi-value= 1 - b-value) but to our knowledge we are the first to provide an R-package
 for easy calculation of pi-values and visualization. 
 
+
 ## Installation
 
 You can install the development version of BayesVolcano from [GitHub](https://github.com/) with:
@@ -62,9 +72,10 @@ result <- prepare_volcano_df(
    annotation_df = annotation_df
  )
 plot_volcano(result,
-             color="group",
-             label="label",
-             label.pi.threshold = 0.9,
+             CrI = FALSE, # optional display of credible intervals
+             color="group", # optional color coding
+             label="label", # optional text labels
+             label.pi.threshold = 0.9, # optional thresholds for labels
              label.parameter.threshold = 0.5)
 ```