Merge pull request #4 from federicomarini/revision_2

Revision 2

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: ideal
 Type: Package
 Title: Interactive Differential Expression AnaLysis
-Version: 1.13.1
-Date: 2020-05-26
+Version: 1.13.2
+Date: 2020-09-28
 Authors@R: c(person("Federico", "Marini", role = c("aut", "cre"), 
     email ="[email protected]", 
     comment = c(ORCID = '0000-0003-3252-7758')))
@@ -63,5 +63,5 @@ BugReports: https://github.com/federicomarini/ideal/issues
 biocViews: ImmunoOncology, GeneExpression, DifferentialExpression, RNASeq, Sequencing,
     Visualization, QualityControl, GUI, GeneSetEnrichment, ReportWriting
 VignetteBuilder: knitr
-RoxygenNote: 7.1.0
+RoxygenNote: 7.1.1
 Encoding: UTF-8

NEWS.md

@@ -3,6 +3,9 @@
 ## Other notes
 
 * Replaced dependency from `d3heatmap` with the functionality of `heatmaply`
+* Additional notifications are returned when closing the app while saving the state to the R environment - both in the console as a `message`, and in the UI via `showNotification`
+* The vignette and the tour contain a section about the format required to run `ideal` correctly
+* The vignette also indicates some exemplary steps after exporting the values to the R environment, showcasing how to perform additional functional enrichment analyses e.g. via `fgsea` or `gprofiler2`
 
 # ideal 1.12.0
 

R/ideal.R

@@ -4299,6 +4299,13 @@ ideal<- function(dds_obj = NULL,
           # better practice rather than assigning to global env - notify users of this
           assign(paste0("ideal_inputs_", tstamp),cur_inputs, envir = ideal_env)
           assign(paste0("ideal_values_", tstamp),cur_values, envir = ideal_env)
+          showNotification(
+            paste0("ideal closed, state successfully saved to the R environment. ",
+                   "You can access these values by searching the `ideal_env` object."),
+            type = "message")
+          message("ideal closed, state successfully saved to the R environment.")
+          message("     You can access these values by searching the `ideal_env` object.")
+
           stopApp("ideal closed, state successfully saved to global R environment.")
 
           # assign(paste0("ideal_inputs_",
@@ -4322,6 +4329,7 @@ ideal<- function(dds_obj = NULL,
         # values[names(LiveInputs)] <- LiveInputs
         r_data <- reactiveValuesToList(values)
         save(LiveInputs, r_data , file = filename)
+        message("list of inputs and reactive values correctly saved as binary data")
       })
     }
 

inst/extdata/intro_datasetup.txt

@@ -1,6 +1,7 @@
 element;intro
 #Welcome;Welcome to the tour for the Data Setup tab!
 #upload_count_matrix;Here you can upload your count matrix. Please read in the collapsible help about the formats that are accepted, or click on the question mark icon on the right to trigger a modal popup.
+#help_format;You can click on this round button to trigger the opening of a modal dialog window, which contains information (in the form of text and screenshots) on the formats that are expected/required to work with ideal
 #box_ddsobj;Up here you have three Info Boxes. The first is a summary for your DESeqDataSet object you will create soon...
 #box_annobj;... the second will contain the overview on the annotation object you can provide or compute...
 #box_resobj;... and the third is about the DESeqResults object you will compute in the following tabs. They turn from red to green as you have populated the underlying objects.

vignettes/ideal-usersguide.Rmd

@@ -128,6 +128,15 @@ Different modalities are supported to launch the application:
   The design formula can be constructed interactively at runtime
 - `ideal()`, where the count matrix and experimental design can simply be uploaded at runtime, where all the derived objects can be extracted and computed live. 
   These files have to be formatted as tabular text files, and a function in the package tries to guess the separator, based on heuristics of occurrencies per line of commonly used characters
+
+You can obtain more information on the formats that are expected and required to work with `r Biocpkg("ideal")` by pressing the small round button in Step 1 of the Data Setup panel - these are common to the formats used by `r Biocpkg("pcaExplorer")`.
+For the sake of completeness, you can see an overview reported in the image below.
+
+```{r, out.width="100%", echo=FALSE}
+knitr::include_graphics(system.file("www", "help_dataformats.png", package = "pcaExplorer"))
+```
+
+The value to specify for the experimental design is best selected live in Step 2 of the Data Setup panel (see more in Section \@ref(datasetup)) - or if passing directly the `dds` object in the call to `ideal`, is already contained in the `dds` itself. 
 
 ## Accessing the public instance of `r Biocpkg("ideal")` 
 
@@ -210,7 +219,7 @@ For the main analysis, the available panels are described in the following subse
 The landing page for the app is also where you might likely be reading this text (otherwise in the package vignette).
 
 
-## Data Setup
+## Data Setup {#datasetup}
 
 The Data Setup panel is where you can upload or inspect the required inputs for running the app.
 This builds on the primary idea used by `r Biocpkg("pcaExplorer")` and extends it with the following aspects:
@@ -653,6 +662,77 @@ While running the app, the user can
 
 This functionality to retrieve and share the output is provided by action buttons that are placed close to each element of interest. 
 
+## Expanding the analysis after `ideal`
+
+After exporting the objects to the R environment, via the button "Exit ideal and save", it is possible to continue the analyses e.g. using alternative methods for functional enrichment analysis, with Functional Class Scoring methods (such as GSEA, as implemented in `r Biocpkg("fgsea")`), or additional methods for Overrepresentation Analysis (e.g. `r CRANpkg("gprofiler2")`).  
+In the example below, we show an example of the code required to perform `fgsea` on the set of objects exported from `ideal()`.
+
+```{r fgsea, eval=FALSE}
+library("fgsea")
+# selecting the result object from the exported environment
+exported_res <- ideal_env$ideal_values_20200926_135052$res_obj
+summary(exported_res)
+
+# for processing of intermediate steps
+library("dplyr")
+library("tibble")
+
+# extracting the rankes for pre-ranked gsea
+de_ranks <- exported_res %>%
+  as.data.frame() %>% 
+  dplyr::arrange(padj) %>% 
+  dplyr::select(symbol, stat) %>% 
+  deframe()
+head(de_ranks, 20)
+
+# loading the signatures from the gmt file - to be downloaded locally
+pathways_gmtfile <- gmtPathways("path_to/msigdb_v7.0_GMTs/h.all.v6.2.symbols.gmt")
+
+# running fgsea
+fgsea_result <- fgsea(pathways = pathways_gmtfile, 
+                      stats = de_ranks, 
+                      nperm = 100000)
+fgsea_result <- fgsea_result %>% 
+  arrange(desc(NES))
+
+# displaying the results
+DT::datatable(fgsea_result)
+```
+
+The following chunk shows an example of how to perform the functional enrichment analysis with `g:Profiler`'s tool `g:GOST`, using the interface in `r CRANpkg("gprofiler2")`
+
+```{r gprofiler2, eval=FALSE}
+library("gprofiler2")
+
+# selecting the result object from the exported environment
+exported_res <- ideal_env$ideal_values_20200926_135052$res_obj
+summary(exported_res)
+
+# extracting the DE genes vector
+degenes <- deseqresult2DEgenes(exported_res, FDR = 0.01)$symbol
+
+# running the test
+gost_res <- gost(
+  query = degenes[1:1000], 
+  organism = "hsapiens", 
+  ordered_query = FALSE, 
+  multi_query = FALSE, 
+  significant = FALSE, 
+  exclude_iea = TRUE, 
+  measure_underrepresentation = FALSE, 
+  evcodes = TRUE, 
+  user_threshold = 0.05, 
+  correction_method = "g_SCS", 
+  domain_scope = "annotated", 
+  numeric_ns = "", 
+  sources = "GO:BP", 
+  as_short_link = FALSE)
+
+# displaying the results
+DT::datatable(gost_res$result)
+```
+
+
 # Enhancing `ideal`
 
 The `annotation_obj` is a quick helper to make your data and results easier to read. For creating it, you can exploit the corresponding `org.XX.eg.db` packages, available in Bioconductor.