Advance doc (#328)

* fix typo * add Q raised by Anik, closes #324 * closes #321 * closes #319 - found and fixed additional broken links * enhanced doc - solves #320 * Apply suggestions from code review Co-authored-by: Paul Jonas Jost <[email protected]>
ICB-DCM · Aug 23, 2024 · 3f6005c · 3f6005c
1 parent c7e9b81
commit 3f6005c
Show file tree

Hide file tree

Showing 7 changed files with 38 additions and 28 deletions.
diff --git a/docs/faq.md b/docs/faq.md
@@ -27,10 +27,10 @@ nav_order: 7
 </style>
 
 <div class="faq">
-  <div class="question" onclick="toggleAnswer('q1')">1. What is ComicsART?</div>
+  <div class="question" onclick="toggleAnswer('q1')">1. What is cOmicsArt?</div>
   <div id="q1" class="answer">ComicsART is a tool designed to facilitate easy explorative and statistical analysis. It stands for customizable Omics Analysis and Reporting Tool. Its special focus is to guarantee reproducibility within the GUI providing you an autogenerated HTML report of which clicks have been done and to guarantee reprodubility without the GUI provding on click all code and data to fully reproduce in R what you have done within the GUI - allowing then for to enjoy the freedom and options programming gives you! </div>
 
-  <div class="question" onclick="toggleAnswer('q2')">2. How do I get started with ComicsART?</div>
+  <div class="question" onclick="toggleAnswer('q2')">2. How do I get started with cOmicsArt?</div>
   <div id="q2" class="answer">There are several ways- depending on what type of learner you are! You might want to first read our publication that includes the whole picture and our vision. If you want to experience the app without the own data you can use the test-dataset by simply selecting Testdata tab in the sidebar and then starting your journey. We have also screen recordings available on YouTube as well as this extensive documentation you already found! In case you are left with question feel free to mail us: [email protected].</div>
 
   <div class="question" onclick="toggleAnswer('q3')">3. My Data upload does not work - what do I do?</div>
@@ -41,11 +41,18 @@ Common issues are: Not exactly the same row or columnnames, missing values, wron
   </div>
 
 <div class="question" onclick="toggleAnswer('q4')">4. The app is running since ages and nothing happens</div>
-  <div id="q5" class="answer">
+  <div id="q4" class="answer">
   Is grey overlay visibile? If yes, tha app backend has crashed - this can have multiple reasons. It could be a disconnection between your browser and the server or the server itself is not running anymore. If you refresh the page you might be able to reconnect but potentially have to redo your work. We try to almost alsways give you the option to still recieve the HTML report so you know at least what has been done up to this point. If this happens often to you it might be a good idea to employ our DOCKER image or install the app locally on your machine. Instructions can be found in the 'Installation' tab in the sidebar.
   </div>
 </div>
 
+<div class="question" onclick="toggleAnswer('q5')">5. Where is the HTMl report?</div>
+  <div id="q5" class="answer">
+  The report is generated for your download upon clicking on the hyperlink 'Download Report (as html)' underneath the cOmicsArt - text at the top left. Upon clicking you will see a loading bar and the report will be finalized. To retrieve it you need to click on 'Download report' (it is also a hyperlink) - you should get prompted by your file-browser to save the file. If this does not happen please check your browser settings and allow pop-ups for this page.
+  </div>
+</div>
+
+
 <script>
 function toggleAnswer(id) {
   var answer = document.getElementById(id);

diff --git a/docs/interface-details/enrichment-analysis.md b/docs/interface-details/enrichment-analysis.md
@@ -71,7 +71,7 @@ The main panel displays the results of the enrichment analysis. Here are some ke
 
 - **Download Options**: The visualisation can be downloaded directly in common formats 
   (e.g., PNG, TIFF, PDF) or sent to the report. You can also download the underlying R 
-  code and data. For more information, check out [Interface Details](interface-details.md). The tables can be downloaded in common formats as well (.csv,
+  code and data. For more information, check out [Interface Details](../interface-details.md). The tables can be downloaded in common formats as well (.csv,
   .xlsx).
 
 ### Other Notes

diff --git a/docs/interface-details/heatmap.md b/docs/interface-details/heatmap.md
@@ -11,16 +11,22 @@ The Heatmap tab is divided into two main sections: the side panel and the main p
 
 ## Side Panel
 
-In the side panel, you have the following options:
+Within the side panel, you have multiple options, which depend on the selected option within
+'Select Entities to show'. Here are the general options:
 
 - **Use batch corrected data?**: Allows you to choose whether to use batch corrected data.
-  - Options: Yes, No
+  - Options: Yes, No. Note, this option only shows up at the top if you have done batch correction
+  within the [Pre-procesing tab](pre-processing.md) tab
 
 - **Select Entities to show**: Allows you to select which entities to show in the heatmap.
-  - Options: all, Select based on Annotation, Top K
+  - Options: all, Select based on Annotation, Top K. Below you can find further information. Note, that you will get a warning if you want to visualise more than 100 entries to prevent unintentional long loading times.
+
 
 ### Conditional Options for "Top K"
 
+Often, you don't want to visualize the entire set of entities you have but only the top entities, for example, the top 100 entities with the highest LogFoldChange
+Hence you need to specifcy the ordering critera and the 'k' (number of entities) you want to visualize. 
+
 - **Order based on**: Select the criterion for ordering the top entities.
   - Options: LogFoldChange, absolute LogFoldChange, LogFoldChange and Significant, absolute LogFoldChange and Significant
 
@@ -30,29 +36,27 @@ In the side panel, you have the following options:
 
 - **Choose treatment group of log2 FoldChange**: Select the treatment group for log2 fold change.
 
-- **adj. p-value threshold**: Set the adjusted p-value threshold.
+- **adj. p-value threshold**: Set the adjusted p-value threshold. Only entities with an adjusted p-value below this threshold will be considered. Hence, if your `k` is greater than the number of significant entities, you will get less than `k` entities.
 
 ### Conditional Options for "Select based on Annotation"
 
-- **Choose the variable to select the rows after**: Select the variable to use for row selection.
+- **Choose the variable to select the rows after**: Select the variable to use for row selection. Displayed here are all options (specifically column names) you provided within the row annotation.
 
-- **Which entities to use?**: Select the specific entities to include in the heatmap.
+- **Which entities to use?**: Select the specific entities to include in the heatmap. The default option is `all`. Note that you can choose multiple items.
 
 ### Action Button
 
 - **Get Heatmap**: Clicking this button will generate the heatmap in the main panel based on the selected parameters.
 
 ### Aesthetics Options
 
-- **Choose the variable to color the samples after**: Select the variable for coloring the samples.
-
-- **Choose the variable to color the rows after**: Select the variable for coloring the rows.
+- **Choose the variable to color the samples after**: Select the variable for coloring the samples. The coloring options are populated based on the sample annotation provided initially. Often, you want to examine whether the given sample labels coincide with the unsupervised clustering of the heatmap.
 
-- **Choose the label of rows**: Select the label for rows to be shown in the plot.
+- **Choose the variable to color the rows after**: Select the variable for coloring the rows. The coloring options are populated based on the row annotation provided initially. This can help identify patterns within the heatmap that are similar to the coloring of the samples.
 
 - **Row/Column Clustering?**: Enable or disable row/column clustering.
 
-- **row-wise scaling?**: Enable or disable row-wise scaling. Useful to see changes 
+- **row-wise scaling?**: Enable or disable row-wise scaling - note that this is z-scaling. Useful to see changes 
   within one row more clearly.
 
 ## Main Panel
@@ -61,19 +65,20 @@ The main panel displays the heatmap and additional options. Here are some key po
 
 - **Heatmap Plot**: Displays the generated heatmap.
 
+- **Choose the label of rows**: Select the label for rows to be shown in the plot.
+
 - **Threshold upon which explicit labels are shown**: Set the threshold for showing 
   explicit row labels. If more than the specified number of rows are shown, the labels 
   will be hidden.
 
-- **Save genes shown in Heatmap as list**: Save the list of genes displayed in the 
-  heatmap for further usage in the [Enrichment Analysis](enrichment-analysis.md).
+- **Save genes shown in Heatmap for OA with Enrichment Analysis tab**: Sends the list of genes displayed in the 
+  heatmap for further usage in the [Enrichment Analysis](enrichment-analysis.md). Hence, if one wants to send a specific set to the over-represententation analysis (OA) tab, this is the way to go.
 
-- **Download Options**: The visualization can be downloaded directly in common formats (e.g., PNG, TIFF, PDF) or sent to the report. You can also download the underlying R code and data. For more information, check out [Interface Details](interface-details.md).
+- **Download Options**: The visualization can be downloaded directly in common formats (e.g., PNG, TIFF, PDF) or sent to the report. You can also download the underlying R code and data. For more information, check out [Interface Details](../interface-details.md).
 
 - **Notes**: Add personal notes regarding the heatmap.
 
 ### Other Notes
 
 - **Question Marks**: The displayed question marks provide quick and immediate help. However, since you are reading this documentation, you found the extensive version. Hope it helped!
-
 - **Interpretation**: The heatmap can provide insights into the relationships between different entities based on the selected annotations and clustering options. Adjusting the selection and aesthetic parameters can help in identifying the most relevant patterns.
diff --git a/docs/interface-details/pca.md b/docs/interface-details/pca.md
@@ -41,7 +41,7 @@ The main panel displays the PCA results. Here are some key points:
 
 - **Information Display**: At the top of the main panel, some information is displayed regarding the computation of the PCA.
 
-- **Download Options**: The visualization can be downloaded directly in common formats (e.g., PNG, TIFF, PDF) or sent to the report. You can also download the underlying R code and data. For more information, check out [Interface Details](interface-details.md).
+- **Download Options**: The visualization can be downloaded directly in common formats (e.g., PNG, TIFF, PDF) or sent to the report. You can also download the underlying R code and data. For more information, check out [Interface Details](../interface-details.md).
 
 ### Other Notes
 

diff --git a/docs/interface-details/sample-correlation.md b/docs/interface-details/sample-correlation.md
@@ -32,7 +32,7 @@ The main panel displays the correlation heatmap. Here are some key points:
 
 - **Information Display**: At the top of the main panel, some information is displayed regarding the computation of the correlation matrix.
 - **Heatmap Visualization**: The heatmap provides a visual representation of the sample correlation based on the selected method and coloring option.
-- **Download Options**: The visualization can be downloaded directly in common formats (e.g., PNG, TIFF, PDF) or sent to the report. You can also download the underlying R code and data. For more information, check out [Interface Details](interface-details.md).
+- **Download Options**: The visualization can be downloaded directly in common formats (e.g., PNG, TIFF, PDF) or sent to the report. You can also download the underlying R code and data. For more information, check out [Interface Details](../interface-details.md).
 - **Non-Interactive Plot**: Note that this plot is not interactive.
 
 ### Other Notes

diff --git a/docs/interface-details/significance-analysis.md b/docs/interface-details/significance-analysis.md
@@ -52,8 +52,7 @@ The main panel displays the results of the significance analysis. The main panel
     - **Intersections**: The dots and lines indicate which groups are part of each intersection.
   - **Download Options**: You can save the plots in different file formats such as 
     PNG, TIFF, and PDF. You also have the option to download the underlying R code 
-    and data. For more information, check out [Interface 
-      Details](interface-details.md).
+    and data. For more information, check out [Interface Details](../interface-details.md).
 - **Comparison tabs**: For each selected comparison, a separate tab is created in 
   which the results can be viewed. They consist of a Volcano plot and a table.
   - **Table**: A sortable table, displaying pvalue, padj, log2FoldChange, and other 
@@ -64,8 +63,7 @@ The main panel displays the results of the significance analysis. The main panel
     - **Uncorrected p-Values**: Shows the log fold change versus the uncorrected p-values.
     - Both plots simultaneously or separately can be downloaded directly in common 
       formats (e.g., PNG, TIFF, PDF) or sent to the report. You can also download 
-      the underlying R code and data. For more information, check out [Interface 
-      Details](interface-details.md).
+      the underlying R code and data. For more information, check out [Interface Details](../interface-details.md).
 
 ### Other Notes
 

diff --git a/docs/interface-details/single-gene-visualisations.md b/docs/interface-details/single-gene-visualisations.md
@@ -20,7 +20,7 @@ In the side panel, you have the following options:
 
 - **Select Annotation you want to select an entity from**: You can choose the annotation to select the entities from. The options are directly taken from the provided row annotation. Precisely it is the column names of the row annotation.
 
-- **Select the Gene from the list**: In the dropdown menu, you can choose from the unique items present in the chosen annotation category. Note that you can choose an annotation that is the same for multiple items. For example, you can choose `gene_type` (if present in your row annotation) and then `protein coding`. The displayed plot will show the sum of all protein coding genes for the respective sample, grouped by what is chosen below. You can check out [Showcase B](showcase-b.md) for an actual example. There is also a [screen recording](../screen_recording.md) covering some examples.
+- **Select the Gene from the list**: In the dropdown menu, you can choose from the unique items present in the chosen annotation category. Note that you can choose an annotation that is the same for multiple items. For example, you can choose `gene_type` (if present in your row annotation) and then `protein coding`. The displayed plot will show the sum of all protein coding genes for the respective sample, grouped by what is chosen below. You can check out [our showcases](../showcases.md) for actual examples. There is also a [screen recording](../screen_recording.md) covering some examples.
 
 - **Get Single Gene Visualisation**: Clicking this button will generate the visualisation in the main panel based on the selected options.
 
@@ -31,10 +31,10 @@ In the side panel, you have the following options:
 The main panel displays the single gene visualisations. Here are some key points:
 
 - **Visualisation**: The visualisation provides a boxplot or dot plot based on the number of samples per group and the selected options. Note that you only see boxplots if you have more than 3 samples per group. If there are fewer than 4 samples, only dots will be displayed.
-- **Select your desired comparisons**: Here you select which comparisons you want to test and display in the plot. Note that each test is taken as individual test, there is no multiple testing correction done ((Why it is important)[https://www.nature.com/articles/nbt1209-1135]) when choosing more than one test. For more advanced testing please go to the [Significance analysis tab](significance-analysis.md)
+- **Select your desired comparisons**: Here you select which comparisons you want to test and display in the plot. Note that each test is taken as an individual test, there is no multiple testing correction done \([Why it is important](https://www.nature.com/articles/nbt1209-1135)\) when choosing more than one test. For more advanced testing please go to the [Significance analysis tab](significance-analysis.md)
 
 
-- **Download Options**: The visualisation can be downloaded directly in common formats (e.g., PNG, TIFF, PDF) or sent to the report. You can also download the underlying R code and data. For more information, check out [Interface Details](interface-details.md).
+- **Download Options**: The visualisation can be downloaded directly in common formats (e.g., PNG, TIFF, PDF) or sent to the report. You can also download the underlying R code and data. For more information, check out [Interface Details](../interface-details.md).
 
 ### Other Notes