@@ -35,6 +35,7 @@ export(plotGeneralGraphStats)

 export(plotPCA_all)

 export(plotTFEnrichment)

 export(plot_stats_connectionSummary)

+export(visualizeGRN)

 import(BiocFileCache)

 import(BiocManager)

 import(GenomicRanges)

@@ -2580,11 +2580,11 @@ addConnections_peak_gene <- function(GRN, overlapTypeGene = "TSS", corMethod = "

     # Finally, do the actual overlaps

-    overlapsAll = GenomicRanges::findOverlaps(query, subject, 

+    overlapsAll = suppressWarnings(GenomicRanges::findOverlaps(query, subject, 

                                               minoverlap = 1,

                                               type = "any",

                                               select = "all",

-                                              ignore.strand = TRUE)

+                                              ignore.strand = TRUE))

     query_row_ids  = S4Vectors::queryHits(overlapsAll)

@@ -4211,7 +4211,8 @@ getGRNConnections <- function(GRN, type = "all.filtered",  permuted = FALSE, inc

     "plot_communityStats"            = "GRN.community_stats",

     "plot_communityEnrichment"       = "GRN.community_enrichment",

     "plot_generalNetworkStats"       = "GRN.overall_stats",

-    "plot_TFEnrichment"              = "GRN.TF_enrichment"

+    "plot_TFEnrichment"              = "GRN.TF_enrichment",

+    "plot_network"                   = "GRN.network_visualisation"

   )

@@ -6,7 +6,7 @@

 #'

 #' @template GRN 

 #' @template outputFolder

-#' @param data Character. Either \code{"peaks"} or \code{"rna"} or \code{"all"}. Type of data to plot a PCA for. \code{"peaks"} corresponds to the the open chromatin data, while \code{"rna"} refers to the RNA-seq counts. If set to \code{"all"}, PCA will be done for both data modalities. In any case, PCA will be based on the original provided data before any additional normalization has been run (i.e., usually the raw data).

+#' @param data Character. Either \code{"peaks"} or \code{"rna"} or \code{"all"}. Default \code{c("rna", "peaks")}. Type of data to plot a PCA for. \code{"peaks"} corresponds to the the open chromatin data, while \code{"rna"} refers to the RNA-seq counts. If set to \code{"all"}, PCA will be done for both data modalities. In any case, PCA will be based on the original provided data before any additional normalization has been run (i.e., usually the raw data).

 #' @param topn Integer vector. Default \code{c(500,1000,5000)}. Number of top variable features to do PCA for. Can be a vector of different numbers (see default).

 #' @param type Character. One of or a combination of \code{"raw"}, \code{"normalized"}, \code{"all"}. Default \code{c("raw", "normalized")}. Should the PCA plots be done based on the raw or normalized data, respectively?

 #' @template forceRerun

@@ -525,6 +525,9 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

     if (!permutationCur %in% dataType2) {

       next

     }

+      

+    futile.logger::flog.info(paste0("\n Plotting for permutation ", permutationCur))

+      

     suffixFile = .getPermutationSuffixStr(permutationCur)

@@ -677,8 +680,15 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

   pageCounter = 1  

-  plots.l = list()

-  index = 1

+  if (!is.null(file)) {

+      .checkOutputFile(file)

+      grDevices::pdf(file, width = width, height = height)

+      futile.logger::flog.info(paste0("Plotting to file ", file))

+  } else {

+      futile.logger::flog.info(paste0("Plotting directly"))   

+  }

+  

+ 

   # Dont take all TF, some might be missing.

   connections_TF_peak = GRN@connections$TF_peaks[[as.character(perm)]]$connectionStats

@@ -692,10 +702,10 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

   pb <- progress::progress_bar$new(total = nTF)

-  levels_pos<-unique(as.character(cut(GRN@config$parameters$internal$stepsFDR, breaks = GRN@config$parameters$internal$stepsFDR, right = FALSE, include.lowest = TRUE )))

-  levels_neg<-unique(as.character(cut(GRN@config$parameters$internal$stepsFDR, breaks = rev(GRN@config$parameters$internal$stepsFDR), right = TRUE,  include.lowest = TRUE )))

+  steps = GRN@config$parameters$internal$stepsFDR

-

+  levels_pos<-unique(as.character(cut(steps, breaks = steps, right = FALSE, include.lowest = TRUE )))

+  levels_neg<-unique(as.character(cut(steps, breaks = rev(steps), right = TRUE, include.lowest = TRUE )))

   for (i in seq_len(nTF)) {

     pb$tick()

@@ -704,6 +714,7 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

     connections_TF_peakCur = dplyr::filter(connections_TF_peak, TF.name == TFCur)

     # Produce two FDR plots, coming from both directions

+    plotsCur.l = list()

     for (typeCur in c("pos","neg")) {

       if (typeCur == "pos") {

@@ -718,6 +729,8 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

         dplyr::mutate(TF_peak.r_bin = factor(TF_peak.r_bin, levels = levelsCur))  %>%

         reshape2::melt(id = c("TF_peak.r_bin", "TF_peak.connectionType", "n")) 

+      plotTitle = paste0(TFCur, ": Direction ", typeCur, ifelse(perm == 0, "", "(permuted)"))

+      

       if (!useGCCorrection) {

         g = suppressWarnings(connections_TF_peak.filt %>% 

@@ -725,7 +738,7 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

                                ggplot(aes(TF_peak.r_bin, value, color = .data$n, shape = variable)) +

                                geom_point(na.rm = TRUE) +

                                facet_wrap(~TF_peak.connectionType, ncol = 1) + 

-                               labs(x="Correlation bin", y="FDR TF-peak", title= paste0(TFCur, ": Direction ", typeCur)) +

+                               labs(x="Correlation bin", y="FDR TF-peak", title= plotTitle) +

                                theme_bw() +

                                theme(axis.text.x=element_text(angle=60, hjust=1, size= 8)) +

                                scale_x_discrete(drop=FALSE) + 

@@ -735,6 +748,8 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

                                                   values = c("TF_peak.fdr" = 1)) +

                                scale_color_viridis_c("No. of connections") 

         )

+        plotsCur.l[[typeCur]] = g

+        

         if (plotDetails) {

@@ -742,7 +757,7 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

             ggplot(aes(TF_peak.r_bin, log10(value+1), color = variable)) + 

             geom_point(size = 1) +

             facet_wrap(~TF_peak.connectionType, ncol = 1) + 

-            labs(x="Correlation bin", y="log10(Observed frequencies +1)", title= paste0(TFCur, ": Direction ", typeCur)) +

+            labs(x="Correlation bin", y="log10(Observed frequencies +1)", title= plotTitle) +

             theme_bw() +

             theme(axis.text.x=element_text(angle=60, hjust=1, size= 8)) +

             scale_x_discrete(drop=FALSE) + 

@@ -753,6 +768,8 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

                                labels = c("tpvalue" = "True positives\n(foreground, scaling ref.)\n", 

                                           "fpvalue" = "False positives\n(background, unscaled)\n", 

                                           "fpvalue_norm" = "False positives\n(background, scaled to ref.)"))

+          

+          plotsCur.l[[paste0(typeCur, "_details")]] = g

         }

@@ -764,7 +781,7 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

                                ggplot(aes(TF_peak.r_bin, value, color = .data$n, shape = variable, alpha = variable)) + 

                                geom_point(na.rm = TRUE) +

                                facet_wrap(~TF_peak.connectionType, ncol = 1) + 

-                               labs(x="Correlation bin", y="FDR TF-peak", title= paste0(TFCur, ": Direction ", typeCur)) +

+                               labs(x="Correlation bin", y="FDR TF-peak", title= plotTitle) +

                                theme_bw() +

                                theme(axis.text.x=element_text(angle=60, hjust=1, size= 8)) +

                                scale_x_discrete(drop=FALSE) + 

@@ -774,13 +791,15 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

                                                   values = c("TF_peak.fdr" = 3,"TF_peak.fdr_orig" = 1)) +

                                scale_color_viridis_c("No. of connections") + 

                                scale_alpha_discrete(range = c("TF_peak.fdr" = 0.5,"TF_peak.fdr_orig" = 1))  +

-                               guides(alpha = FALSE))

+                               guides(alpha = FALSE)

+        )

+        plotsCur.l[[typeCur]] = g

         if (plotDetails) {

           g2 = ggplot(connections_TF_peak.filt %>% dplyr::filter(grepl("value", variable)), aes(TF_peak.r_bin, log10(value+1), color = variable)) + 

             geom_point(size = 1) +

             facet_wrap(~TF_peak.connectionType, ncol = 1) + 

-            labs(x="Correlation bin", y="log10(Observed frequencies +1)", title= paste0(TFCur, ": Direction ", typeCur)) +

+            labs(x="Correlation bin", y="log10(Observed frequencies +1)", title= plotTitle) +

             theme_bw() +

             theme(axis.text.x=element_text(angle=60, hjust=1, size= 8)) +

             scale_x_discrete(drop=FALSE) + 

@@ -794,41 +813,36 @@ plotDiagnosticPlots_TFPeaks <- function(GRN,

                                           "fpvalue_norm_orig" = "False positives without GC\n(background, scaled to ref.)\n",

                                           "fpvalue" = "False positives with GC\n(background, unscaled)\n", 

                                           "fpvalue_norm" = "False positives with GC\n(background, scaled to ref.)"))

+          

+          plotsCur.l[[paste0(typeCur, "_details")]] = g

         }

       }

-      # We now created either just one plot g or g + g2 for "one" direction

-      if (is.null(pages) | (!is.null(pages) && pageCounter %in% pages)) {

-          plots.l[[index]] = g

-          index = index + 1

-      }

-

-      

-      if (plotDetails) {

-          

-          if (is.null(pages) | (!is.null(pages) && pageCounter %in% pages)) {

-              plots.l[[index]] = g2

-              index = index + 1

-          }

-

-          # Only here we already have a new page, as we produced 2 plots in this iteration alone

-          pageCounter = pageCounter + 1 

-       }

-

-      

     } # end for both directions

-    if (!plotDetails) {

+    # Lets create the plots

+    if (is.null(pages) | (!is.null(pages) && pageCounter %in% pages)) {

+        plots_all = plotsCur.l$pos / plotsCur.l$neg

+        plot(plots_all)

+    }

+    pageCounter = pageCounter + 1 

+    

+    if (plotDetails) {

+        if (is.null(pages) | (!is.null(pages) && pageCounter %in% pages)) {

+            plots_all = plotsCur.l$pos_details / plotsCur.l$neg_details

+            plot(plots_all)

+        }

         pageCounter = pageCounter + 1 

     }

-

+    

+  

   } # end allTF

   .printWarningPageNumber(pages, pageCounter)

-  

-  .printMultipleGraphsPerPage(plots.l, nCol = 1, nRow = 2, pdfFile = file, height = height, width = width)

+ 

+  if (!is.null(file)) dev.off()

   .printExecutionTime(start)

 }

@@ -1712,7 +1726,7 @@ plot_stats_connectionSummary <- function(GRN, type = "heatmap",

                       column_names_gp = grid::gpar(fontsize = 10),

                       row_title = "TF-peak FDR",

                       cell_fun = function(j, i, x, y, width, height, fill) {

-                          grid::grid.text(sprintf("%.0f", plotData.l[[permIndex]][i, j]), x, y, gp = grid::gpar(fontsize = 30))

+                          grid::grid.text(sprintf("%.0f", plotData.l[[permIndex]][i, j]), x, y, gp = grid::gpar(fontsize = 20))

                       }

                   ) %>% plot()

@@ -3240,55 +3254,69 @@ plotTFEnrichment <- function(GRN, rankType = "degree", n = NULL, TF.names = NULL

 ############### GRN visualization ###############

-#' Visualize a filtered GRN (in development)

+#' Visualize a filtered GRN. 

 #'

 #' @template GRN 

 #' @template permuted

-#' @param file TODO

-#' @param title TODO

-#' @param maxRowsToPlot TODO

-#' @param useDefaultMetadata TODO

-#' @param vertice_color_TFs TODO

-#' @param vertice_color_peaks TODO

-#' @param vertice_color_genes TODO

+#' @template outputFolder

+#' @template basenameOutput

 #' @template plotAsPDF

 #' @template pdf_width

 #' @template pdf_height

+#' @param title NULL or Character. Default NULL. Title to be assigned to the plot.

+#' @param maxRowsToPlot Numeric. Default 500. Refers to the maximum number of connections to be plotted.

+#' @param graph Character. Default \code{TF-gene}. One of: \code{TF-gene}, \code{TF-peak-gene}. Whether to plot a graph with links from TFs to peaks to gene, or the graph with the inferred TF to gene connections.

+#' @param colorby Character. Default \code{type}. One of \code{type}, code \code{community}. Color the vertices by either type (TF/peak/gene) or community. See \code{\link{calculateCommunitiesStats}}

+#' @param layered Boolean. Default \code{FALSE}. Display the network in a layered format where each layer corresponds to a node type (TF/peak/gene).

+#' @param vertice_color_TFs Named list. Default \code{list(h = 10, c = 85, l = c(25, 95))}. The list must specify the color in hcl format (hue, chroma, luminence). See the \code{\link[colorspace]} package for more details and examples

+#' @param vertice_color_peaks Named list. Default \code{list(h = 135, c = 45, l = c(35, 95))}.

+#' @param vertice_color_genes Named list. Default \code{list(h = 260, c = 80, l = c(30, 90))}.

+#' @param vertexLabel_cex Numeric. Default \code{0.4}. Font size (multiplication factor, device-dependent)

+#' @param vertexLabel_dist Numeric. Default \code{0} vertex. Distance between the label and the vertex.

 #' @template forceRerun

-

-#' @return TODO

-# #' @export

-visualizeGRN <- function(GRN, file, title = NULL, maxRowsToPlot = 500, useDefaultMetadata = TRUE,

-                         graph = "TF-gene" , colorby = "type", layered = FALSE,

-                         vertice_color_TFs = NULL, vertice_color_peaks = NULL, vertice_color_genes = NULL,

-                         plotAsPDF = TRUE, pdf_width = 12, pdf_height = 12,

+#' @example 

+#' GRN = visualizeGRN(GRN, maxRowsToPlot = 700, graph = "TF-peak-gene", colorby = "type")

+#' @return the GRN object

+#' @export

+visualizeGRN <- function(GRN, outputFolder = NULL,  basenameOutput = NULL, plotAsPDF = TRUE, pdf_width = 12, pdf_height = 12,

+                         title = NULL, maxRowsToPlot = 500, graph = "TF-gene" , colorby = "type", layered = FALSE,

+                         vertice_color_TFs = list(h = 10, c = 85, l = c(25, 95)), vertice_color_peaks = list(h = 135, c = 45, l = c(35, 95)), vertice_color_genes = list(h = 260, c = 80, l = c(30, 90)),

+                         vertexLabel_cex = 0.4, vertexLabel_dist = 0,

+                         

                          forceRerun = FALSE

 ) {

+    

     start = Sys.time()

     GRN = .addFunctionLogToObject(GRN)

-    #checkmate::assertFlag(plotAsPDF)

+    checkmate::assertFlag(plotAsPDF)

+    checkmate::assertNumeric(pdf_width, lower = 5, upper = 99)

+    checkmate::assertNumeric(pdf_height, lower = 5, upper = 99)

     checkmate::assertNumeric(maxRowsToPlot)

-    checkmate::assertFlag(useDefaultMetadata)

     checkmate::assertSubset(graph, c("TF-gene", "TF-peak-gene"))

     checkmate::assertSubset(colorby, c("type", "community"))

     checkmate::assertFlag(layered)

-    checkmate::assertNumeric(pdf_width, lower = 5, upper = 99)

-    checkmate::assertNumeric(pdf_height, lower = 5, upper = 99)

-    

-    

-    futile.logger::flog.info(paste0("Plotting GRN network", dplyr::if_else(is.null(file), "", paste0(" to file ", file))))

-    

-    if (useDefaultMetadata) {

-        metadata_visualization.l = getBasic_metadata_visualization(GRN)

-        vertice_color_TFs   = list(metadata_visualization.l[["RNA_expression_TF"]],    "HOCOID",     "baseMean_log")

-        vertice_color_genes = list(metadata_visualization.l[["RNA_expression_genes"]], "ENSEMBL_ID", "baseMean_log")

-        vertice_color_peaks = list(metadata_visualization.l[["Peaks_accessibility"]],   "peakID",     "mean_log")

-    }

-    

-    

-    

+    checkmate::assertList(vertice_color_TFs)

+    checkmate::assertNames(names(vertice_color_TFs), must.include = c("h", "c", "l"), subset.of = c("h", "c", "l"))

+    checkmate::assertList(vertice_color_peaks)

+    checkmate::assertNames(names(vertice_color_peaks), must.include = c("h", "c", "l"), subset.of = c("h", "c", "l"))

+    checkmate::assertList(vertice_color_genes)

+    checkmate::assertNames(names(vertice_color_genes), must.include = c("h", "c", "l"), subset.of = c("h", "c", "l"))

+    checkmate::assertNumeric(vertexLabel_cex)

+    checkmate::assertNumeric(vertexLabel_dist)

+    checkmate::assertFlag(forceRerun)

+    

+    

+    outputFolder = .checkOutputFolder(GRN, outputFolder)

+    

+    # if (useDefaultMetadata) {

+    #   metadata_visualization.l = getBasic_metadata_visualization(GRN)

+    #   vertice_color_TFs   = list(metadata_visualization.l[["RNA_expression_TF"]],    "HOCOID",     "baseMean_log")

+    #   vertice_color_genes = list(metadata_visualization.l[["RNA_expression_genes"]], "ENSEMBL_ID", "baseMean_log")

+    #   vertice_color_peaks = list(metadata_visualization.l[["Peaks_accessibility"]],   "peakID",     "mean_log")

+    # }

+    # 

     #grn.merged = getGRNConnections(GRN, permuted = permuted, type = "all.filtered")

     # check that it's in sync with the @ graph

     if (graph == "TF-gene"){

@@ -3335,10 +3363,10 @@ visualizeGRN <- function(GRN, file, title = NULL, maxRowsToPlot = 500, useDefaul

     if (plotAsPDF) {

-        grDevices::pdf(file = file, width = pdf_width, height = pdf_height)

-        futile.logger::flog.info(paste0("Plotting to file ", file))

+        futile.logger::flog.info(paste0("Plotting GRN network to ", outputFolder, dplyr::if_else(is.null(basenameOutput), .getOutputFileName("plot_network"), basenameOutput),".pdf"))

+        grDevices::pdf(file = paste0(outputFolder,"/", ifelse(is.null(basenameOutput), .getOutputFileName("plot_network"), basenameOutput),".pdf"),width = pdf_width, height = pdf_height )

     } else {

-        futile.logger::flog.info(paste0("Plotting directly"))

+        futile.logger::flog.info(paste0("Plotting GRN network"))

     }

     if (nRows > maxRowsToPlot) { 

@@ -3347,7 +3375,7 @@ visualizeGRN <- function(GRN, file, title = NULL, maxRowsToPlot = 500, useDefaul

         message = paste0(title, "\n\nPlotting omitted.\n\nThe number of rows in the GRN (", nRows, ") exceeds the maximum of ", maxRowsToPlot, ".\nSee the maxRowsToPlot parameter to increase the limit")

         text(x = 0.5, y = 0.5, message, cex = 1.6, col = "red")

-        if (!is.null(file)) {

+        if (plotAsPDF) {

             grDevices::dev.off()

         }

@@ -3394,30 +3422,31 @@ visualizeGRN <- function(GRN, file, title = NULL, maxRowsToPlot = 500, useDefaul

         nBins_discard = 25

         nBins_real = nBins_orig - nBins_discard

-        if (!is.null(vertice_color_TFs)) {

-            color_gradient = rev(colorspace::sequential_hcl(nBins_orig, h = 10, c = 85, l = c(25, 95)))[(nBins_discard + 1):nBins_orig] # red

-            colors_categories.l[["TF"]]  = c(color_gradient[1], color_gradient[nBins_real]) 

-            colors_categories.l[["TF"]]  = color_gradient 

-            symbols_categories.l[["TF"]] = c(15,NA,15)

-        }

+        #if (!is.null(vertice_color_TFs)) {

+        color_gradient = rev(colorspace::sequential_hcl(nBins_orig, h = vertice_color_TFs[["h"]], c = vertice_color_TFs[["c"]], l = vertice_color_TFs[["l"]]))[(nBins_discard + 1):nBins_orig] # red

+        colors_categories.l[["TF"]]  = c(color_gradient[1], color_gradient[nBins_real]) 

+        colors_categories.l[["TF"]]  = color_gradient 

+        symbols_categories.l[["TF"]] = c(15,NA,15)

+        vertice_color_TFs   = append(list(metadata_visualization.l[["RNA_expression_TF"]],    "HOCOID",     "baseMean_log"), vertice_color_TFs)

+        #}

         if(graph == "TF-peak-gene"){

-            

-            if (!is.null(vertice_color_peaks)) {

-                color_gradient = rev(colorspace::sequential_hcl(nBins_orig, h = 135, c = 45, l = c(35, 95)))[(nBins_discard + 1):nBins_orig]  # green

-                colors_categories.l[["PEAK"]] = c(color_gradient[1], color_gradient[nBins_real])

-                colors_categories.l[["PEAK"]] = color_gradient

-                symbols_categories.l[["PEAK"]] = c(21,NA,21)

-            }

-            

+            #if (!is.null(vertice_color_peaks)) {

+            color_gradient = rev(colorspace::sequential_hcl(nBins_orig, h = vertice_color_peaks[["h"]], c = vertice_color_peaks[["c"]], l = vertice_color_peaks[["l"]]))[(nBins_discard + 1):nBins_orig]  # green

+            colors_categories.l[["PEAK"]] = c(color_gradient[1], color_gradient[nBins_real])

+            colors_categories.l[["PEAK"]] = color_gradient

+            symbols_categories.l[["PEAK"]] = c(21,NA,21)

+            vertice_color_peaks = append(list(metadata_visualization.l[["Peaks_accessibility"]],   "peakID",     "mean_log"), vertice_color_peaks)

+            # }

         }

-        if (!is.null(vertice_color_genes)) {

-            color_gradient = rev(colorspace::sequential_hcl(nBins_orig, h = 260, c = 80, l = c(30, 90)))[(nBins_discard + 1):nBins_orig] # blue

-            colors_categories.l[["GENE"]] = c(color_gradient[1], color_gradient[nBins_real]) 

-            colors_categories.l[["GENE"]] = color_gradient

-            symbols_categories.l[["GENE"]] = c(21,NA,21)

-        }

+        #if (!is.null(vertice_color_genes)) {

+        color_gradient = rev(colorspace::sequential_hcl(nBins_orig, h = vertice_color_genes[["h"]], c = vertice_color_genes[["c"]], l = vertice_color_genes[["l"]]))[(nBins_discard + 1):nBins_orig] # blue

+        colors_categories.l[["GENE"]] = c(color_gradient[1], color_gradient[nBins_real]) 

+        colors_categories.l[["GENE"]] = color_gradient

+        symbols_categories.l[["GENE"]] = c(21,NA,21)

+        vertice_color_genes = append(list(metadata_visualization.l[["RNA_expression_genes"]], "ENSEMBL_ID", "baseMean_log"), vertice_color_genes)

+        #}

         ## VERTICES ##

@@ -3637,9 +3666,9 @@ visualizeGRN <- function(GRN, file, title = NULL, maxRowsToPlot = 500, useDefaul

             ncommunities = length(unique(GRN@graph$TF_gene$clusterGraph$membership))

             if (ncommunities >=8){

-                community_colors = data.frame(community = names(sort(table(GRN@graph$TF_gene$clusterGraph$membership), decreasing = T)[1:ncommunities]),

+                community_colors = data.frame(community = names(sort(table(GRN@graph$TF_gene$clusterGraph$membership), decreasing = T)[1:nCommunitiesMax]),

                                               color = rainbow(7))

-                fillercolors = data.frame(community = 8:ncommunities, color = "847E89") # only color the x largest communities

+                fillercolors = data.frame(community = nCommunitiesMax:ncommunities, color = "847E89") # only color the x largest communities

                 community_colors = rbind(community_colors, fillercolors)

             }else{

@@ -3742,7 +3771,7 @@ visualizeGRN <- function(GRN, file, title = NULL, maxRowsToPlot = 500, useDefaul

         # Calling plot.new() might be necessary here

-        if(is.null(file)){

+        if(!plotAsPDF){

             plot.new()

         }

         par(mar=c(7,0,0,0) + 0.2)

@@ -3759,12 +3788,12 @@ visualizeGRN <- function(GRN, file, title = NULL, maxRowsToPlot = 500, useDefaul

             edge.width = igraph::E(net)$weight,

             vertex.label=igraph::V(net)$label,

             vertex.label.font=1, 

-            vertex.label.cex = 0.3, 

+            vertex.label.cex = vertexLabel_cex, 

             vertex.label.family="Helvetica", 

             vertex.label.color = "black",

             vertex.label.degree= -pi/2,

             vertex.label=igraph::V(net)$label,

-            vertex.label.dist= 0,

+            vertex.label.dist= vertexLabel_dist,

             vertex.shape = shape_vertex[igraph::V(net)$type],

             main = title

         )

@@ -3834,22 +3863,20 @@ visualizeGRN <- function(GRN, file, title = NULL, maxRowsToPlot = 500, useDefaul

     }

-    if (!is.null(file)) {

+    if (plotAsPDF) {

         grDevices::dev.off()

     }

     .printExecutionTime(start)

+    GRN

 }

-

-

-

 .verifyArgument_verticeType <- function(vertice_color_list) {

-  

-  checkmate::assertList(vertice_color_list, len = 3)

-  checkmate::assertDataFrame(vertice_color_list[[1]])

-  checkmate::assertSubset(c(vertice_color_list[[2]], vertice_color_list[[3]]), colnames(vertice_color_list[[1]]))

+    

+    checkmate::assertList(vertice_color_list, len = 6)

+    checkmate::assertDataFrame(vertice_color_list[[1]])

+    checkmate::assertSubset(c(vertice_color_list[[2]], vertice_color_list[[3]]), colnames(vertice_color_list[[1]]))

 }

@@ -8,7 +8,7 @@ plotDiagnosticPlots_peakGene(

   GRN,

   outputFolder = NULL,

   basenameOutput = NULL,

-  gene.types = list(c("all"), c("protein_coding"), c("protein_coding", "lincRNA")),

+  gene.types = list(c("protein_coding", "lincRNA")),

   useFiltered = FALSE,

   plotDetails = FALSE,

   plotPerTF = FALSE,

@@ -26,7 +26,7 @@ plotDiagnosticPlots_peakGene(

 \item{basenameOutput}{\code{NULL} or character. Default \code{NULL}. Basename of the output files that are produced. If set to \code{NULL}, a default basename is chosen. If a custom basename is specified, all output files will have the chosen basename as file prefix, be careful with not overwriting already existing files (if \code{forceRerun} is set to \code{TRUE})}

-\item{gene.types}{List of character vectors. Default list(c("all"), c("protein_coding"), c("protein_coding", "lincRNA")). Vectors of gene types to consider for the diagnostic plots. Multiple distinct combinations of gene types can be specified. For example, if set to \code{list(c("protein_coding", "lincRNA"), c("protein_coding"), c("all"))}, 3 distinct PDFs will be produced, one for each element of the list. The first file would only consider protein-coding and lincRNA genes, while the second plot only considers protein-coding ones. The special keyword "all" denotes all gene types found (usually, there are many gene types present, also more exotic and rare ones).}

+\item{gene.types}{List of character vectors. Default list(c("protein_coding", "lincRNA")). Vectors of gene types to consider for the diagnostic plots. Multiple distinct combinations of gene types can be specified. For example, if set to \code{list(c("protein_coding", "lincRNA"), c("protein_coding"), c("all"))}, 3 distinct PDFs will be produced, one for each element of the list. The first file would only consider protein-coding and lincRNA genes, while the second plot only considers protein-coding ones. The special keyword "all" denotes all gene types found (usually, there are many gene types present, also more exotic and rare ones).}

 \item{useFiltered}{Logical. TRUE or FALSE. Default FALSE. If set to \code{FALSE}, the diagnostic plots will be produced based on all peak-gene connections. This is the default and will usually be best to judge whether the background behaves as expected. If set to TRUE, the diagnostic plots will be produced based on the filtered set of connections. For this, the function \code{link{filterGRNAndConnectGenes}} must have been run before.}

@@ -25,7 +25,7 @@ plotPCA_all(

 \item{basenameOutput}{\code{NULL} or character. Default \code{NULL}. Basename of the output files that are produced. If set to \code{NULL}, a default basename is chosen. If a custom basename is specified, all output files will have the chosen basename as file prefix, be careful with not overwriting already existing files (if \code{forceRerun} is set to \code{TRUE})}

-\item{data}{Character. Either \code{"peaks"} or \code{"rna"} or \code{"all"}. Type of data to plot a PCA for. \code{"peaks"} corresponds to the the open chromatin data, while \code{"rna"} refers to the RNA-seq counts. If set to \code{"all"}, PCA will be done for both data modalities. In any case, PCA will be based on the original provided data before any additional normalization has been run (i.e., usually the raw data).}

+\item{data}{Character. Either \code{"peaks"} or \code{"rna"} or \code{"all"}. Default \code{c("rna", "peaks")}. Type of data to plot a PCA for. \code{"peaks"} corresponds to the the open chromatin data, while \code{"rna"} refers to the RNA-seq counts. If set to \code{"all"}, PCA will be done for both data modalities. In any case, PCA will be based on the original provided data before any additional normalization has been run (i.e., usually the raw data).}

 \item{topn}{Integer vector. Default \code{c(500,1000,5000)}. Number of top variable features to do PCA for. Can be a vector of different numbers (see default).}

@@ -2,56 +2,68 @@

 % Please edit documentation in R/plot.R

 \name{visualizeGRN}

 \alias{visualizeGRN}

-\title{Visualize a filtered GRN (in development)}

+\title{Visualize a filtered GRN.}

 \usage{

 visualizeGRN(

   GRN,

-  file,

+  outputFolder = NULL,

+  basenameOutput = NULL,

+  plotAsPDF = TRUE,

+  pdf_width = 12,

+  pdf_height = 12,

   title = NULL,

   maxRowsToPlot = 500,

-  useDefaultMetadata = TRUE,

   graph = "TF-gene",

   colorby = "type",

   layered = FALSE,

-  vertice_color_TFs = NULL,

-  vertice_color_peaks = NULL,

-  vertice_color_genes = NULL,

-  plotAsPDF = TRUE,

-  pdf_width = 12,

-  pdf_height = 12,

+  vertice_color_TFs = list(h = 10, c = 85, l = c(25, 95)),

+  vertice_color_peaks = list(h = 135, c = 45, l = c(35, 95)),

+  vertice_color_genes = list(h = 260, c = 80, l = c(30, 90)),

+  vertexLabel_cex = 0.4,

+  vertexLabel_dist = 0,

   forceRerun = FALSE

 )

 }

 \arguments{

 \item{GRN}{Object of class \code{\linkS4class{GRN}}}

-\item{file}{TODO}

+\item{outputFolder}{Character or \code{NULL}. Default \code{NULL}. If set to \code{NULL}, the default output folder as specified when initiating the object in \code{link{initializeGRN}} will be used. Otherwise, all output from this function will be put into the specified folder. We recommend specifying an absolute path.}

-\item{title}{TODO}

+\item{basenameOutput}{\code{NULL} or character. Default \code{NULL}. Basename of the output files that are produced. If set to \code{NULL}, a default basename is chosen. If a custom basename is specified, all output files will have the chosen basename as file prefix, be careful with not overwriting already existing files (if \code{forceRerun} is set to \code{TRUE})}

-\item{maxRowsToPlot}{TODO}

+\item{plotAsPDF}{\code{TRUE} or \code{FALSE}. Default \code{TRUE}.Should the plots be printed to a PDF file? If set to \code{TRUE}, a PDF file is generated, the name of which depends on the value of \code{basenameOutput}. If set to \code{FALSE}, all plots are printed to the currently active device. Note that most functions print more than one plot, which means you may only see the last plot depending on your active graphics device.}

-\item{useDefaultMetadata}{TODO}

+\item{pdf_width}{Number. Default 12. Width of the PDF, in cm.}

-\item{vertice_color_TFs}{TODO}

+\item{pdf_height}{Number. Default 12. Height of the PDF, in cm.}

-\item{vertice_color_peaks}{TODO}

+\item{title}{NULL or Character. Default NULL. Title to be assigned to the plot.}

-\item{vertice_color_genes}{TODO}

+\item{maxRowsToPlot}{Numeric. Default 500. Refers to the maximum number of connections to be plotted.}

-\item{plotAsPDF}{\code{TRUE} or \code{FALSE}. Default \code{TRUE}.Should the plots be printed to a PDF file? If set to \code{TRUE}, a PDF file is generated, the name of which depends on the value of \code{basenameOutput}. If set to \code{FALSE}, all plots are printed to the currently active device. Note that most functions print more than one plot, which means you may only see the last plot depending on your active graphics device.}

+\item{graph}{Character. Default \code{TF-gene}. One of: \code{TF-gene}, \code{TF-peak-gene}. Whether to plot a graph with links from TFs to peaks to gene, or the graph with the inferred TF to gene connections.}

-\item{pdf_width}{Number. Default 12. Width of the PDF, in cm.}

+\item{colorby}{Character. Default \code{type}. One of \code{type}, code \code{community}. Color the vertices by either type (TF/peak/gene) or community. See \code{\link{calculateCommunitiesStats}}}

-\item{pdf_height}{Number. Default 12. Height of the PDF, in cm.}

+\item{layered}{Boolean. Default \code{FALSE}. Display the network in a layered format where each layer corresponds to a node type (TF/peak/gene).}

+

+\item{vertice_color_TFs}{Named list. Default \code{list(h = 10, c = 85, l = c(25, 95))}. The list must specify the color in hcl format (hue, chroma, luminence). See the \code{\link[colorspace]} package for more details and examples}

+

+\item{vertice_color_peaks}{Named list. Default \code{list(h = 135, c = 45, l = c(35, 95))}.}

+

+\item{vertice_color_genes}{Named list. Default \code{list(h = 260, c = 80, l = c(30, 90))}.}

+

+\item{vertexLabel_cex}{Numeric. Default \code{0.4}. Font size (multiplication factor, device-dependent)}

+

+\item{vertexLabel_dist}{Numeric. Default \code{0} vertex. Distance between the label and the vertex.}

 \item{forceRerun}{\code{TRUE} or \code{FALSE}. Default \code{FALSE}. Force execution, even if the GRN object already contains the result. Overwrites the old results.}

 \item{permuted}{\code{TRUE} or \code{FALSE}. Default \code{FALSE}. Should the permuted data be taken (\code{TRUE}) or the non-permuted, original one (\code{FALSE})?}

 }

 \value{

-TODO

+the GRN object

 }

 \description{

-Visualize a filtered GRN (in development)

+Visualize a filtered GRN.

 }

@@ -4,7 +4,7 @@ author: "Christian Arnold, Judith Zaugg, Rim Moussa"

 date: "`r BiocStyle::doc_date()`"

 package: "`r BiocStyle::pkg_ver('GRaNIE')`"

 abstract: >

-  This workflow vignette shows how to use the `GRaNIE` package in a real-world example. For this purpose, you will use real data that is soon available in the `GRaNIEData` package for a more complex analysis to illustrate most of its features. Importantly, you will also learn in detail how to work with a `GRaNIE` object and what its main functions and properties are. The vignette will be continuously updated whenever new functionality becomes available or when we receive user feedback.

+  This workflow vignette shows how to use the `GRaNIE` package in a real-world example. For this purpose, you will use real data for a more complex analysis to illustrate most of its features. Importantly, you will also learn in detail how to work with a `GRaNIE` object and what its main functions and properties are. The vignette will be continuously updated whenever new functionality becomes available or when we receive user feedback.

 vignette: >

   %\VignetteIndexEntry{Workflow example}

   %\VignetteEngine{knitr::rmarkdown}

@@ -53,10 +53,25 @@ pre[class] {

 }

 ```

+# Example data

+

+The data is taken from [here](https://zenodo.org/record/1188300#.X370PXUzaSN) [1], has been processed to meet the requirements of the `GRaNIE` package and consists of the following files:

+

+* ATAC-seq peaks, raw counts (originally around 75,000, genome-wide, here filtered to around 60,500)

+* RNA-Seq data, raw counts (originally for around 35,000 genes, here filtered to around 19,000)

+* sample metadata with additional sample-specific information

+

+In general, the dataset is from human macrophages (both naive and IFNg primed) of healthy individuals and various stimulations / infections (naive vs primed and infected with SL1344 vs not), with 4 groups in total: control/infected(SL1344) and naive/primed(IFNg)

+

+

+Furthermore, the example dataset is accompanied by the following files:

+

+* genome-wide transcription factor binding site predictions for 75 selected TFs, along with a translation table to link TF names to their corresponding Ensembl IDs. For each TF, a gzipped BED file has been created with predicted TF binding sites. The files have been generated with `PWMScan` and the `HOCOMOCO` database, see [2] for details.

+

 # Example Workflow

 <a name="section1"></a>

-In the following example, you will use data from the `GRaNIEData` package (soon available) to construct a *eGRN* from ATAC-seq, RNA-seq data as well transcription factor data.

+In the following example, you will use the example data to construct a *eGRN* from ATAC-seq, RNA-seq data as well transcription factor data.

 ```{r <knitr, echo=FALSE, message=FALSE, results="hide", class.output="scroll-200"}

@@ -75,14 +90,13 @@ For reasons of brevity, we omit the output of this code chunk.

 ```{r loadLibaries2, echo=TRUE, message=FALSE, results="hide", warning=FALSE, class.output="scroll-200"}

 library(tidyverse)

-#library(GRaNIEData)

 library(GRaNIE)

 ```

 ## General notes

-Each of the `GRaNIE` functions we mention here in this Vignette comes with sensible default parameters that we found to work well for most of the datasets we tested it with so far.  However, **always check the validity and usefulness of the parameters before starting an analysis** to avoid unreasonable results.

+Each of the `GRaNIE` functions we mention here in this Vignette comes with sensible default parameters that we found to work well for most of the datasets we tested it with so far. For the purpose of this Vignette, however, and the resulting running times, we here try to provide a good compromise between biological necessity and computational efficiacy.  However, **always check the validity and usefulness of the parameters before starting an analysis** to avoid unreasonable results.

 ## Reading the data required for the `GRaNIE` package

@@ -101,8 +115,8 @@ So, let's import the enhancer and RNA-seq data as a data frame as well as some s

 ```{r importData, echo=TRUE, include=TRUE, class.output="scroll-200"}

 # We load the example data directly from the web:

-file_peaks = "https://www.embl.de/download/zaugg/GRaNIE/peaks.tsv.gz"

-file_RNA   = "https://www.embl.de/download/zaugg/GRaNIE/rna.tsv.gz"

+file_peaks = "https://www.embl.de/download/zaugg/GRaNIE/countsATAC.filtered.tsv.gz"

+file_RNA   = "https://www.embl.de/download/zaugg/GRaNIE/countsRNA.filtered.tsv.gz"

 file_sampleMetadata = "https://www.embl.de/download/zaugg/GRaNIE/sampleMetadata.tsv.gz"

 countsRNA.df      = read_tsv(file_RNA, col_types = cols())

@@ -119,7 +133,6 @@ sampleMetadata.df

 idColumn_peaks = "peakID"

 idColumn_RNA = "ENSEMBL"

-

 ```

 While we recommend raw counts for both enhancers and RNA-Seq as input and offer several normalization choices in the pipeline, it is also possible to provide pre-normalized data. Note that the normalization method may have a large influence on the resulting *eGRN* network, so make sure the choice of normalization is reasonable. For more details, see the next sections.

@@ -145,7 +158,7 @@ objectMetadata.l = list(name                = paste0("Macrophages_infected_prime

                         file_sampleMetadata = file_sampleMetadata,

                         genomeAssembly      = genomeAssembly)

-dir_output = "output"

+dir_output = "."

 GRN = initializeGRN(objectMetadata = objectMetadata.l,

                     outputFolder = dir_output,

@@ -190,34 +203,34 @@ Note that while this step is recommended to do, it is fully optional from a work

 ```{r runPCA, echo=TRUE, include=TRUE, eval = FALSE, class.output="scroll-200", collapse=FALSE, results="hold"}

-GRN = plotPCA_all(GRN, data = c("rna"), topn = 500, type = "raw", plotAsPDF = FALSE, pages = c(3,4), forceRerun = TRUE)

+GRN = plotPCA_all(GRN, data = c("rna"), topn = 500, type = "raw", plotAsPDF = FALSE, pages = c(2,3,14), forceRerun = TRUE)

 ```

-Depending on the parameters, multiple output plots may be produced, with up to two files for each of the specified `data` modalities (that is, RNA-Seq counts, as specified with `rna` here, as well as the peak counts, `peaks`, not done here for reasons of brevity). For each of them, PCA plots can be produced for both `raw` and `normalized` data (here: only `raw`). With `raw`, we here denote the original counts as given as input with the `addData()` function, irrespective of whether this was already pre-normalized or not. For more details, see the [Package Details Vignette](packageDetails.html). The `topn` argument specifies the number of top variable features to do PCA for - here 500.

+Depending on the parameters, multiple output files (and plots) may be produced, with up to two files for each of the specified `data` modalities (that is, RNA-Seq counts, as specified with `rna` here, as well as the peak counts, `peaks`, not done here for reasons of brevity). For each of them, PCA plots can be produced for both `raw` and `normalized` data (here: only `raw`). With `raw`, we here denote the original counts as given as input with the `addData()` function, irrespective of whether this was already pre-normalized or not. The `topn` argument specifies the number of top variable features to do PCA for - here 500.

-We do not show any of the PCA plots here for reasons of brevity, but make sure to examine these plots closely! For all details, which plota are produced and further comments on how to understand and interpret them, see the [Package Details Vignette](packageDetails.html).

+There are more plots that are generated, make sure to examine these plots closely! For all details, which plots are produced and further comments on how to understand and interpret them, see the [Package Website](https://grp-zaugg.embl-community.io/GRaNIE/).

 ## Add TFs and TFBS and overlap with peak

-Now it is time to add data for TFs and predicted TF binding sites (TFBS)! Our `GRaNIE` package requires pre-computed TFBS that need to be in a specific format (see the [Package Details Vignette](packageDetails.html) for details). In brief, a 6-column bed file must be present for each TF, with a specific file name that starts with the name of the TF, an arbitrary and optional suffix (here: "_TFBS") and a particular file ending (supported are `bed` or `bed.gz`; here, we specify the latter). All these files must be located in a particular folder that the `addTFBS()` functions then searches in order to identify those files that match the specified patterns. We provide example TFBS for the 3 genome assemblies we support, see the comment below and the [Package Details Vignette](packageDetails.html) for details. After setting this up, we are ready to overlap the TFBS and the peaks by calling the function `overlapPeaksAndTFBS()`.

+Now it is time to add data for TFs and predicted TF binding sites (TFBS)! Our `GRaNIE` package requires pre-computed TFBS that need to be in a specific format. In brief, a 6-column bed file must be present for each TF, with a specific file name that starts with the name of the TF, an arbitrary and optional suffix (here: `_TFBS`) and a particular file ending (supported are `bed` or `bed.gz`; here, we specify the latter). All these files must be located in a particular folder that the `addTFBS()` functions then searches in order to identify those files that match the specified patterns. We provide example TFBS for the 3 genome assemblies we support. After setting this up, we are ready to overlap the TFBS and the peaks by calling the function `overlapPeaksAndTFBS()`.

 For more parameter details, see the R help (`?addTFBS` and `?overlapPeaksAndTFBS`). 

 ```{r addTFBS, echo=TRUE, include=TRUE, eval = FALSE, class.output="scroll-200", results='hold'}

-folder_TFBS_first50 = "TFBS_selected"

+folder_TFBS_first50 = "https://www.embl.de/download/zaugg/GRaNIE/TFBS_selected.zip"

 # Download the zip of all TFBS files. Takes too long here, not executed therefore

-# filename <- "TFBS_selected.zip"

-# download.file("https://www.embl.de/download/zaugg/GRaNIE/TFBS_selected.zip", file.path(filename), quiet = FALSE)

-# unzip(file.path(filename), overwrite = TRUE, exdir = file.path("TFBS_selected"))

+# download.file(folder_TFBS_first50, file.path("TFBS_selected.zip"), quiet = FALSE)

+# unzip(file.path("TFBS_selected.zip"), overwrite = TRUE)

+# motifFolder = tools::file_path_as_absolute("TFBS_selected")

-GRN = addTFBS(GRN, motifFolder = folder_TFBS_first50, TFs = "all", filesTFBSPattern = "_TFBS", fileEnding = ".bed.gz", forceRerun = TRUE)

+GRN = addTFBS(GRN, motifFolder = motifFolder, TFs = "all", filesTFBSPattern = "_TFBS", fileEnding = ".bed.gz", forceRerun = TRUE)

 GRN = overlapPeaksAndTFBS(GRN, nCores = 1, forceRerun = TRUE)

 ```

-We see from the output (omitted here for brevity) that 75 TFs have been found in the specified input folder, and the number of TFBS that overlap our peaks for each of them. We now successfully added our TFs and TFBS to the `GRaNIE` object.

+We see from the output (omitted here for brevity) that 6 TFs have been found in the specified input folder, and the number of TFBS that overlap our peaks for each of them. We successfully added our TFs and TFBS to the `GRaNIE` object"

@@ -247,7 +260,7 @@ We can see from the output that no peaks have been filtered due to their size an

 ## Add TF-enhancer connections

-We now have all necessary data in the object to start constructing our network. As explained in the [Package Details Vignette](packageDetails.html), we currently support two types of links for our `GRaNIE` approach:

+We now have all necessary data in the object to start constructing our network. As explained elsewhere, we currently support two types of links for our `GRaNIE` approach:

 1. TF - enhancer

 2. enhancer - gene

@@ -260,7 +273,7 @@ In addition to creating TF-enhancer links based on TF expression, we can also co

 Lastly, we offer a so called GC-correction that uses a GC-matching background to compare it with the foreground instead of using the full background as comparison. We are still investigating the plausibility and effects of this and therefore mark this feature as experimental as of now.

-This function may run a while, and each time-consuming step has a built-in progress bar so the remaining time can be estimated. Note that the TF-enhancer links are constructed for both the original, non-permuted data (in the corresponding output plots that are produced, this is labeled as `original`) and permuted data (`permuted`). 

+Note that the TF-enhancer links are constructed for both the original, non-permuted data (in the corresponding output plots that are produced, this is labeled as `original`) and permuted data (`permuted`). 

 For more parameter options and parameter details, see the R help (`?addConnections_TF_peak`). 

 ```{r addTFPeakConnections, echo=TRUE, include=TRUE, eval = TRUE, class.output="scroll-200", results='hold'}

@@ -268,40 +281,41 @@ GRN = addConnections_TF_peak(GRN, plotDiagnosticPlots = FALSE,

                                      connectionTypes = c("expression"),

                                      corMethod = "pearson", forceRerun = TRUE)

 ```

-From the output, we see that a total of 65 TFs have RNA-seq data available and consequently will be included and correlated with the enhancer accessibility.

+From the output, we see that all of the 6 TFs also have RNA-seq data available and consequently will be included and correlated with the enhancer accessibility.

 ## Quality control 2: Diagnostic plots for TF-enhancer connections

-After adding the TF-enhancer links to our `GRaNIE` object, let's look at some diagnostic plots. Depending on the user parameters, the plots are either directly plotted to the currently active graphics device or to PDF files as specified in the object or via the function parameters. If plotted to a PDF, within the specified or default output folder (when initializing the `GRaNIE` object) should contain two new files that are named `TF_peak.fdrCurves_original.pdf` and `TF_peak.fdrCurves_permuted.pdf`, for example. For reasons of brevity and organization, we fully describe their interpretation and meaning in detail in the [Package Details Vignette](packageDetails.html#output_TF_peak) and not here, however.

+After adding the TF-enhancer links to our `GRaNIE` object, let's look at some diagnostic plots. Depending on the user parameters, the plots are either directly plotted to the currently active graphics device or to PDF files as specified in the object or via the function parameters. If plotted to a PDF, within the specified or default output folder (when initializing the `GRaNIE` object) should contain two new files that are named `TF_peak.fdrCurves_original.pdf` and `TF_peak.fdrCurves_permuted.pdf`, for example. 

+

+This function may run a while, and each time-consuming step has a built-in progress bar for the plot-related parts so the remaining time can be estimated. 

-In summary, TF-enhancer diagnostic plots are available for each TF, and each page summarizes the QC for each TF in two plots:  

+For reasons of brevity and organization, we fully describe their interpretation and meaning in detail elsewhere, however. In summary, TF-enhancer diagnostic plots are available for each TF, and each page summarizes the QC for each TF in two plots:  

 ```{r, echo=FALSE}

-GRN = plotDiagnosticPlots_TFPeaks(GRN, dataType = c("real", "permuted"), plotAsPDF = FALSE, pages = c(6))

+GRN = plotDiagnosticPlots_TFPeaks(GRN, dataType = c("real", "permuted"), plotAsPDF = FALSE, pages = 4)

 ```

-TODO: correct

-For this example, we can see a quite typical case: the TF-enhancer FDR for the various *ETV5.0.C* - enhancer pairs are above 0.2 for the wide majority correlation bins in both directions (that is, positive and negative), while a few bins towards more extreme correlation bins have a low FDR. The former indicate little statistical signal and confidence, while the latter are those connections we are looking for! Typically, however, only  few connections are in the more extreme bins, as indicated by the color. Here, correlation bin refers to the correlation of a particular *ETV5.0.C* - enhancer pair that has been discretized accordingly (i.e., a correlation of 0.07 would go into (0.05-0.10] correlation bin). Usually, depending on the mode of action of a TF, none or either one of the two directions may show a low FDR in particular areas of the plots, often close to more extreme correlation bins, but rarely both. For a better judgement and interpretation, we can also check how this looks like for permuted data:

+For this example, we can see a quite typical case: the TF-enhancer FDR for the various *EGR1.0.A* - enhancer pairs are above 0.2 for the wide majority correlation bins in both directions (that is, positive and negative), while a few bins towards more extreme correlation bins have a low FDR. The former indicate little statistical signal and confidence, while the latter are those connections we are looking for! Typically, however, only  few connections are in the more extreme bins, as indicated by the color. Here, correlation bin refers to the correlation of a particular *EGR1.0.A* - enhancer pair that has been discretized accordingly (i.e., a correlation of 0.07 would go into (0.05-0.10] correlation bin). Usually, depending on the mode of action of a TF, none or either one of the two directions may show a low FDR in particular areas of the plots, often close to more extreme correlation bins, but rarely both. For a better judgement and interpretation, we can also check how this looks like for permuted data:

 We see that for permuted data, there is much less significant bins, as expected.

-Here, in summary, a few positively correlated *ETV5.0.C* - enhancer pairs (with a correlation of at least 0.65 or so) are statistically significant and may be retained for the final *eGRN* network (if corresponding genes connecting to the respective enhancers are found).

+Here, in summary, a few positively correlated *EGR1.0.A* - enhancer pairs (with a correlation of above 0.5 or so) are statistically significant and may be retained for the final *eGRN* network (if corresponding genes connecting to the respective enhancers are found).

 ## Run the AR classification and QC (optional) {#output_AR}

 Transcription factors (TFs) regulate many cellular processes and can therefore serve as readouts of the signaling and regulatory state. Yet for many TFs, the mode of action—repressing or activating transcription of target genes—is unclear. In analogy to our *diffTF* approach that we recently published to calculate differential TF activity,the classification of TFs into putative transcriptional activators or repressors can also be done from within the `GRaNIE` framework in an identical fashion. This can be achieved with the function `AR_classification_wrapper()`.  

-**Note that this step is fully optional and can be skipped. The output of the function is not used for subsequent steps.**. To keep the memory footprint of the `GRaNIE` object low, we recommend to keep the function parameter default `deleteIntermediateData = TRUE`. Here, we specify to put all plots within `output/plots`. However, we do not actually run the code here.

+**Note that this step is fully optional and can be skipped. The output of the function is not used for subsequent steps.**. To keep the memory footprint of the `GRaNIE` object low, we recommend to keep the function parameter default `deleteIntermediateData = TRUE`. Here, we specify to put all plots within `output/plots`. However, for reasons of brevity, we do not actually run the code here.

 ```{r runARClassification, echo=TRUE, include=TRUE, eval = FALSE, class.output="scroll-200"}

 GRN = AR_classification_wrapper(GRN, significanceThreshold_Wilcoxon = 0.05,

                                 outputFolder = "output/plots", 

                                 plot_minNoTFBS_heatmap = 100, plotDiagnosticPlots = TRUE,

-                                deleteIntermediateData = TRUE, forceRerun = TRUE)

+                                forceRerun = TRUE)

 ```

 The classification runs for both real and permuted data, as before. The contents of these plots are identical to and uses in fact practically the same code as our `diffTF` software, and we therefore do not include them here. We refer to the following links for more details as well as the [Package Details Vignette](packageDetails.html#output_AR):

@@ -340,7 +354,7 @@ GRN = addConnections_peak_gene(GRN,

                                nCores = 1, plotDiagnosticPlots = FALSE, plotGeneTypes = list(c("all")), forceRerun = TRUE)

 ```

-We see from the output that almost 38,000 enhancer-gene links have been identified that match our parameters. From these 38,000, however, only around 16,351 actually had corresponding RNA-seq data available, while RNA-seq data was missing or has been filtered for the other. This is a rather typical case, as not all known and annotated genes are included in the RNA-seq data in the first place. Similar to before, the correlations have also been performed for the permuted data.

+We see from the output that almost 38,000 enhancer-gene links have been identified that match our parameters. However, only around 16,351 actually had corresponding RNA-seq data available, while RNA-seq data was missing or has been filtered for the other. This is a rather typical case, as not all known and annotated genes are included in the RNA-seq data in the first place. Similar to before, the correlations have also been performed for the permuted data.

 ## Quality control 3: Diagnostic plots for enhancer-gene connections

@@ -406,9 +420,15 @@ GRN_connections.all

 The table contains many columns, and the prefix of each column name indicates the part of the *eGRN* network that the column refers to (e.g., TFs, TF-enhancers, enhancers, enhancer-genes or genes, or TF-gene if the function `add_TF_gene_correlation()` has been run before). Data are stored in a format that minimizes the memory footprint (e.g., each character column is stored as a factor). This table can now be used for any downstream analysis, as it is just a normal data frame.

-## Visualize the filtered *eGRN* connections

+## Visualize the filtered *eGRN*

+

+The `GRaNIE` package also offers a function to visualize a filtered *eGRN* network! It is very easy to invoke, but provides many options to customize the output and the way the graph is drawn. We recommend to explore the options in the R help (`?getGRNConnections`).

+

+

+```{r visualizeGRN, echo=TRUE, include=TRUE, eval = TRUE, class.output="scroll-200"}

+GRN = visualizeGRN(GRN)

+```

-The `GRaNIE` package will soon also offer some rudimentary functions to visualize a filtered *eGRN* network. Stay tuned! Meanwhile, you can use the `igraph` package to construct a graph out of the filtered TF-enhancer-gene connection table (see above).

 ## Generate a connection summary for filtered connections

@@ -416,10 +436,10 @@ It is often useful to get a grasp of the general connectivity of a network and t

 ```{r connectionSummary, echo=TRUE, include=TRUE, eval = TRUE, class.output="scroll-200"}

 GRN = generateStatsSummary(GRN,

-                           TF_peak.fdr = c(0.01, 0.05, 0.1, 0.2), 

+                           TF_peak.fdr = c(0.05, 0.1, 0.2), 

                            TF_peak.connectionTypes = "all",

                            peak_gene.p_raw = NULL,

-                           peak_gene.fdr = c(0.01, 0.05, 0.1, 0.2),

+                           peak_gene.fdr = c(0.1, 0.2),

                            peak_gene.r_range = c(0,1),

                            allowMissingGenes = c(FALSE, TRUE),

                            allowMissingTFs = c(FALSE),