ggpubrViolin.R

# Adding roxygen comments
#' A function for generating an interactive violin plot, and an ! interactive annotated gg violin plot
#'
#' This function generate a customisable annotated violin plot in png from a dataframe with an outcome variable with 2 levels
#' @param data dataframe with features as coluns, observations as rows. All features must continuous variables. A column denoting the case control must be present
#' @param group The column name from the column holding the case control status information
#' @param feature The column name from the feature of interest for comparison between groups
#' @param ctrl_id The value that denotes the controls in the "group" column (eg. "0", "Control"). Must be provided in double quotes
#' @param case_id The value that denotes the cases in the "group" column (eg. "1", "Case"). Must be provided in double quotes
#' @param SAVEDIR absolut path to output directory
#' @param FILENAME plot filename 
#' @param png_plot_width
#' @param png_plot_height
#' @param png_plot_res
#' @param transparency transparency (alpha) used for color, fill
#' @param ylab_custom
#' @param ggtitle_custom
#' @param ggsubtitle_custom
#' @param ggcaption_custom_color
#' @param ggtitle_custom_color
#' @param ggsubtitle_custom_color
#' @param ggcaption_custom_color
#' @keywords Violin plot
#' @export
#' @examples 
#' drawViolin(data = iris[1:100,] ,group = "Species", feature = "Sepal.Length", ctrl_id = "setosa", case_id = "versicolor")

library(ggpubr)
library(ggplot2)

drawViolin  <- function(    data                    = data      ,
                            group                   = group     ,
                            feature                 = feature   ,
                            ctrl_id                 = ctrl_id   ,
                            case_id                 = case_id   ,
                            ctrl_label              = "control" ,
                            case_label              = "case"    ,
                            ctrl_color              = '#3C91E6' ,
                            case_color              = '#f46036' ,
                            transparency            =  0.4      ,
                            ggsubtitle_custom_color = '#A9BACA' ,
                            ggtitle_custom_color    = '#4A637B' ,
                            ggcaption_custom_color  = '#A9BACA' ,
                            ggcaption_custom        =  ""       ,
                            png_plot_width          =  800      ,
                            png_plot_height         =  600      ,
                            png_plot_res            =  300      ,
                            dataset_id              = ''
                            ){ 


                    ggtitle_custom          =  paste0("Abundance of ", feature, " by ", group)
                    ggsubtitle_custom       =  paste0("Quantile values indicated" )
                    # Accesing column from name as string with double-square brackets
                    data[[group]] <- as.character(data[[group]])
                    data[[group]][data[[group]]==ctrl_id] <- ctrl_label
                    data[[group]][data[[group]]==case_id] <- case_label

                    # TODO: add control of labels, alphabetic order of control case user specified labels
                    # Now it's flaky, the correct color alloc works because we know apriori that case < control
                    data[[group]] <- factor(data[[group]], levels = c(ctrl_label, case_label))
                    data <- data[order(data[[group]], decreasing = FALSE),]

                    # LAYERING STARTS:

                    # // layer 1: a ggpubr::ggviolin
                    # ggopubr uses aes_string() this is why we can use this
                    p <- ggpubr::ggviolin(
                        data, 
                        x = group,
                        y = feature, 
                        add =  "median", 
                        color =  group, 
                        fill  =  group, 
                        alpha = transparency,
                        palette = c(ctrl_color, case_color)) +

                        # // layer 2: geom points 
                        geom_jitter(aes_string(color = group),
                                    position=position_jitter(width = 0.1)) +

                        # // layer 3: geom points, triangles to denote quantiles
                        stat_summary(fun.y=quantile, 
                        geom="point", 
                        size=3, 
                        shape = 17, 
                        alpha = 1,
                        color = "#4A637B",
                        fill  = "#4A637B" ) +

                        # // layer 4: geom text, text to denote quantiles values
                        stat_summary(aes(label=round(..y..,2)), 
                        fun.y=quantile, 
                        geom="text", 
                        color =  "#4A637B",
                        size=3,
                        vjust = 0,
                        hjust = -1) +
                        
                        # // layer :  theme()
                        theme_grey() +

                        # // layer 6:  Setting annotation for title, subtitle, caption
                        labs(title     = ggtitle_custom,
                            subtitle   = ggsubtitle_custom,
                            caption    = ggcaption_custom)   +
                        
                        #// layer 7: Controlling font face, font colour and font size of labs. Also centering with hjust 
                        theme(
                            plot.title    = element_text(color = ggtitle_custom_color   , size = 14, face = "bold" , hjust = 0.5),
                            plot.subtitle = element_text(color = ggsubtitle_custom_color, size = 9                , hjust = 1),
                            plot.caption  = element_text(color = ggsubtitle_custom_color, size = 7, face = "italic"))


                    FILENAME = paste0(feature, "_", dataset_id, "_violin")

                    # Save plotly object as .html file
                    htmlwidgets::saveWidget(ggplotly(p), file = paste0(FILENAME, ".html"))


                    # Save ggplot object as .png file
                    png(filename = paste0(FILENAME,  ".png"),
                        width    = png_plot_width, 
                        height   = png_plot_height)
                    plot(p)
                    dev.off()        

                    # For rendering plots in rmarkdown
                    print(p)                    
                    # END OF FUNCTION

                    }