Doc interface details (#239)

* update interface_details landing page * sample correlation docs done * PCA doc * expandend framework to include screen recording * single gene doc * add comicAnimals * add installation form git, docker is missing
ICB-DCM · Jul 4, 2024 · 8578657 · 8578657
1 parent 38adb59
commit 8578657
Show file tree

Hide file tree

Showing 39 changed files with 353 additions and 127 deletions.
diff --git a/docs/_site/assets/css/just-the-docs-dark.css b/docs/_site/assets/css/just-the-docs-dark.css
@@ -435,7 +435,7 @@ blockquote { margin: 10px 0; margin-block-start: 0; margin-inline-start: 0; padd
 @media (min-width: 31.25rem) { .site-title { font-size: 1.5rem !important; line-height: 1.25; } }
 @media (min-width: 50rem) { .site-title { padding-top: 0.5rem; padding-bottom: 0.5rem; } }
 
-.site-logo { width: 100%; height: 100%; background-image: url("/assets/images/Logo_cOmicsArt.svg"); background-repeat: no-repeat; background-position: left center; background-size: contain; }
+.site-logo { width: 100%; height: 100%; background-image: url("/OmicShiny/assets/images/Logo_cOmicsArt.svg"); background-repeat: no-repeat; background-position: left center; background-size: contain; }
 
 .site-button { display: flex; height: 100%; padding: 1rem; align-items: center; }
 

diff --git a/docs/_site/assets/css/just-the-docs-default.css b/docs/_site/assets/css/just-the-docs-default.css
@@ -307,7 +307,7 @@ blockquote { margin: 10px 0; margin-block-start: 0; margin-inline-start: 0; padd
 @media (min-width: 31.25rem) { .site-title { font-size: 1.5rem !important; line-height: 1.25; } }
 @media (min-width: 50rem) { .site-title { padding-top: 0.5rem; padding-bottom: 0.5rem; } }
 
-.site-logo { width: 100%; height: 100%; background-image: url("/assets/images/Logo_cOmicsArt.svg"); background-repeat: no-repeat; background-position: left center; background-size: contain; }
+.site-logo { width: 100%; height: 100%; background-image: url("/OmicShiny/assets/images/Logo_cOmicsArt.svg"); background-repeat: no-repeat; background-position: left center; background-size: contain; }
 
 .site-button { display: flex; height: 100%; padding: 1rem; align-items: center; }
 

diff --git a/docs/_site/assets/css/just-the-docs-light.css b/docs/_site/assets/css/just-the-docs-light.css
@@ -307,7 +307,7 @@ blockquote { margin: 10px 0; margin-block-start: 0; margin-inline-start: 0; padd
 @media (min-width: 31.25rem) { .site-title { font-size: 1.5rem !important; line-height: 1.25; } }
 @media (min-width: 50rem) { .site-title { padding-top: 0.5rem; padding-bottom: 0.5rem; } }
 
-.site-logo { width: 100%; height: 100%; background-image: url("/assets/images/Logo_cOmicsArt.svg"); background-repeat: no-repeat; background-position: left center; background-size: contain; }
+.site-logo { width: 100%; height: 100%; background-image: url("/OmicShiny/assets/images/Logo_cOmicsArt.svg"); background-repeat: no-repeat; background-position: left center; background-size: contain; }
 
 .site-button { display: flex; height: 100%; padding: 1rem; align-items: center; }
 

diff --git a/docs/_site/assets/images/cOmicsCat.png b/docs/_site/assets/images/cOmicsCat.png
diff --git a/docs/_site/assets/js/just-the-docs.js b/docs/_site/assets/js/just-the-docs.js
@@ -77,7 +77,7 @@ function disableHeadStyleSheets() {
 
 function initSearch() {
   var request = new XMLHttpRequest();
-  request.open('GET', '/assets/js/search-data.json', true);
+  request.open('GET', '/OmicShiny/assets/js/search-data.json', true);
 
   request.onload = function(){
     if (request.status >= 200 && request.status < 400) {
@@ -456,7 +456,7 @@ jtd.getTheme = function() {
 
 jtd.setTheme = function(theme) {
   var cssFile = document.querySelector('[rel="stylesheet"]');
-  cssFile.setAttribute('href', '/assets/css/just-the-docs-' + theme + '.css');
+  cssFile.setAttribute('href', '/OmicShiny/assets/css/just-the-docs-' + theme + '.css');
 }
 
 // Note: pathname can have a trailing slash on a local jekyll server

diff --git a/docs/_site/assets/js/search-data.json b/docs/_site/assets/js/search-data.json
diff --git a/docs/_site/code-and-data.html b/docs/_site/code-and-data.html
diff --git a/docs/_site/code-and-data/data.html b/docs/_site/code-and-data/data.html
diff --git a/docs/_site/code-and-data/examples.html b/docs/_site/code-and-data/examples.html
diff --git a/docs/_site/code-and-data/r-code.html b/docs/_site/code-and-data/r-code.html
diff --git a/docs/_site/faq.html b/docs/_site/faq.html
diff --git a/docs/_site/index.html b/docs/_site/index.html
diff --git a/docs/_site/installation.html b/docs/_site/installation.html
diff --git a/docs/_site/interface-details.html b/docs/_site/interface-details.html
diff --git a/docs/_site/interface-details/enrichment-analysis.html b/docs/_site/interface-details/enrichment-analysis.html
diff --git a/docs/_site/interface-details/heatmap.html b/docs/_site/interface-details/heatmap.html
diff --git a/docs/_site/interface-details/pca.html b/docs/_site/interface-details/pca.html
diff --git a/docs/_site/interface-details/pre-processing.html b/docs/_site/interface-details/pre-processing.html
diff --git a/docs/_site/interface-details/required-data-input.html b/docs/_site/interface-details/required-data-input.html
diff --git a/docs/_site/interface-details/sample-correlation.html b/docs/_site/interface-details/sample-correlation.html
diff --git a/docs/_site/interface-details/selection.html b/docs/_site/interface-details/selection.html
diff --git a/docs/_site/interface-details/significance-analysis.html b/docs/_site/interface-details/significance-analysis.html
diff --git a/docs/_site/interface-details/single-gene-visualisations.html b/docs/_site/interface-details/single-gene-visualisations.html
diff --git a/docs/_site/showcases.html b/docs/_site/showcases.html
diff --git a/docs/_site/showcases/showcase-a.html b/docs/_site/showcases/showcase-a.html
diff --git a/docs/_site/showcases/showcase-b.html b/docs/_site/showcases/showcase-b.html
diff --git a/docs/_site/welcome.html b/docs/_site/welcome.html
diff --git a/docs/assets/images/cOmicsOctopus.png b/docs/assets/images/cOmicsOctopus.png
diff --git a/docs/assets/images/cOmicsRabbit.png b/docs/assets/images/cOmicsRabbit.png
diff --git a/docs/assets/images/cOmicsTurtle.png b/docs/assets/images/cOmicsTurtle.png
diff --git a/docs/faq.md b/docs/faq.md
@@ -1,7 +1,7 @@
 ---
 title: "FAQ"
 layout: default
-nav_order: 6
+nav_order: 7
 ---
 
 # Frequently Asked Questions (FAQ)

diff --git a/docs/index.md b/docs/index.md
@@ -7,10 +7,8 @@ nav_exclude: true
 # Welcome to   <span style="color:#EC0014"> c</span><span style="color:#FD8D33">O</span><span style="color:#3897F1">m</span><span style="color:#FFD335">i</span><span style="color:#A208BA">c</span><span style="color:#EF0089">s</span><span style="color:#EC0014">A</span><span style="color:#FD8D33">r</span><span style="color:#3897F1">t</span> Documentation 🎨
 
 
-![Example Image](/OmicShiny/assets/images/cOmicsCat.png)
-![Example Image](./OmicShiny/assets/images/cOmicsCat.png)
-
-
+![A comic about a cat finding cOmicsART](/OmicShiny/assets/images/cOmicsCat.png)
+*Image generated using DALL-E by OpenAI. Adjusted by Lea Seep*
 
 If you are looking for the web app, please visit: 🌐 [cOmicsART Web App](https://shiny.iaas.uni-bonn.de/OmicShiny/)
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -2,23 +2,117 @@
 layout: default
 title: "Local Installation"
 nav_order: 5
+editor_options: 
+  markdown: 
+    wrap: 72
 ---
+
 # Introduction
-Why do you want to install cOmicsART locally? If you just want to use it make sure to checkout the website: [cOmicsART](https://comicsart.org/). For this there is no installation effort required.
-If you know you are right here, let's get started.
+
+![A comic about a cat finding
+cOmicsART](/OmicShiny/assets/images/cOmicsTurtle.png) *Image generated
+using DALL-E by OpenAI. Adjusted by Lea Seep*
+
+Why do you want to install cOmicsART locally? If you just want to use it
+make sure to checkout the website:
+[cOmicsART](https://shiny.iaas.uni-bonn.de/OmicShiny/). For this there
+is no installation effort required. If you know you are right here,
+let's get started.
+
+# Running a cOmicsART locally within RStudio
+
+# Installing and Running the Shiny App Locally
+
+This guide provides detailed instructions on how to install and run the
+Shiny app from the provided GitHub repository.
+
+## Prerequisites
+
+Ensure you have the following software installed on your system: -
+[Git](https://git-scm.com/) - [R](https://www.r-project.org/) -
+[RStudio](https://rstudio.com/products/rstudio/download/) -
+[renv](https://rstudio.github.io/renv/articles/renv.html) package in R
+
+## Steps to Install and Run the Shiny App
+
+### 1. Clone the GitHub Repository
+
+Open a terminal or command prompt and use the following command to clone
+the repository:
+
+``` bash
+git clone https://github.com/leaseep/OmicShiny.git
+```
+
+### 2. Navigate to the Project Directory
+
+Change the directory to the cloned repository:
+
+``` bash
+cd OmicShiny
+```
+
+## 3. Restore the R Environment
+
+The project uses renv to manage dependencies. Restore the required R
+packages using the renv.lock file. Open R or RStudio. Ensure the package
+`renv` is installed in your R environment.Test with
+
+``` r
+library(renv)
+```
+
+If you get an error, install it using the following command:
+
+``` r
+install.packages("renv")
+```
+
+Then set the working directory to the root directory to install the
+environment from the lock file:
+
+``` r
+renv::restore(lockfile="renv.lock")
+```
+
+This will install all the necessary packages as specified in the
+renv.lock file. **Note:** This takes quite some time as there are a lot of packages to retrieve. 
+Some of those need specific system dependencies. 
+
+## 4. Start the Shiny App
+
+From the R console, start the Shiny app using the following command.
+Note that you will need to be in the `program` directory.
+
+``` r
+shiny::runApp('shinyApp',port=3939)
+```
+
+After starting the Shiny app, you will see an IP address printed in the
+R console:
+
+``` r
+Listening on http://127.0.0.1:3939
+```
+
+Open your web browser and go to the provided IP address to access the
+Shiny app.
 
 # Running a cOmicsART Using Docker
 
-This guide will help you use the provided Docker image to start your Shiny app.
+This guide will help you use the provided Docker image to start your
+Shiny app.
 
 ## Prerequisites
 
-1. **Install Docker**: Ensure Docker is installed on your system. You can download and install Docker from [Docker's official website](https://www.docker.com/get-started).
+1.  **Install Docker**: Ensure Docker is installed on your system. You
+    can download and install Docker from [Docker's official
+    website](https://www.docker.com/get-started).
 
 ## Steps to Run the ShinyApp
 
 .....
 
 # Local deploy the App from github
 
-....
+....
diff --git a/docs/interface-details.md b/docs/interface-details.md
@@ -6,6 +6,8 @@ nav_order: 2
 ---
 
 # Interface Details
+![A comic about a cat finding cOmicsART](/OmicShiny/assets/images/cOmicsOctopus.png)
+*Image generated using DALL-E by OpenAI. Adjusted by Lea Seep*
 
 If you need tab-specific information, navigate to the respective documentation using the left sidebar.
 
@@ -15,41 +17,41 @@ If you need tab-specific information, navigate to the respective documentation u
 
 The cOmicsART user interface evolves gradually to guide users through the necessary steps:
 
-- **Data Input Tab**: The initial tab where users upload their data. A successful data upload is necessary before accessing the next tab.
-- **Pre-Processing Tab**: This tab becomes accessible after a successful data upload. It offers multiple options to prepare the data for analysis, including diagnostic plots to check for normal distribution.
-- **Analysis Tabs**: Six analysis options are available, each in its own tab. These tabs provide interactive result visualizations and various analytical functions.
+- 📥 **Data Input Tab**: The initial tab where users upload their data. A successful data upload is necessary before accessing the next tab.
+- ⚙️ **Pre-Processing Tab**: This tab becomes accessible after a successful data upload. It offers multiple options to prepare the data for analysis, including diagnostic plots to check for normal distribution.
+- 📈 **Analysis Tabs**: Six analysis options are available, each in its own tab. These tabs provide interactive result visualizations and various analytical functions.
 
 To get more information on the tabs, navigate to the respective documentation using the left sidebar.
 
-
 ### Navigation Principles
 
-- **Button Clicks**: Used to evoke actions.
-- **Loading Bars**: Display waiting times during processing.
-- **Question Marks**: Provide quick help and guide to respective detailed documentation found on this very site
-- **Dropdown Menus**: Offer options for selection. Sometime multiple items can be selected. If clicking on a selected item it is removed from the selection
-- **Checkboxes**: If a checkbox is clicked, the respective feature is activated. If clicked again, the feature is deactivated.
-- **Sliding Bars**: Used to adjust numeric parameters or ranges. The range of the sliding bar is displayed above the bar. Simply slide the bar to the desired value.
-- **Text Fields**: Used to enter text. Within cOmicsART these fields are mostly used to hold your Notes, which are saved in the HTML report at approporiate position. You can use [markdown syntax](https://www.markdownguide.org/cheat-sheet/) here.
-
+- 🖱️ **Button Clicks**: Used to evoke actions.
+- ⏳ **Loading Bars**: Display waiting times during processing.
+- ❓ **Question Marks**: Provide quick help and guide to respective detailed documentation found on this very site.
+- 🔽 **Dropdown Menus**: Offer options for selection. Sometimes multiple items can be selected. If clicking on a selected item it is removed from the selection.
+- ☑️ **Checkboxes**: If a checkbox is clicked, the respective feature is activated. If clicked again, the feature is deactivated.
+- 📏 **Sliding Bars**: Used to adjust numeric parameters or ranges. The range of the sliding bar is displayed above the bar. Simply slide the bar to the desired value.
+- 📝 **Text Fields**: Used to enter text. Within cOmicsART these fields are mostly used to hold your Notes, which are saved in the HTML report at the appropriate position. You can use [markdown syntax](https://www.markdownguide.org/cheat-sheet/) here.
 
 ### Features Across Tabs
+
 <div style="overflow: hidden;">
-    <div style="float: left; width: 70%;">
+  <div style="float: left; width: 70%;">
     <ol>
-        <li> <strong>Side Panel Structure:</strong> Each tab, except the input tab, has a side panel divided by a horizontal line:
-            <ul>
-                <li><strong>Upper Section:</strong> Contains options affecting the analysis, requiring recomputation when changed. The analysis is triggered by a "Do/Get analysis" button above the division line.</li>
-                <li><strong>Lower Section:</strong> Displays secondary parameters with changes reflecting immediately in the results (automatic update).</li>
-            </ul>
-        </li>
-        <li><strong>Download Options:</strong> Users can download autogenerated, HTML reports as well as visualizations and results in common formats (e.g., PNG, XLSX). There are respective buttons.
-        </li>
+      <li><strong>Side Panel Structure:</strong> Each tab, except the input tab, has a side panel divided by a horizontal line:
+        <ul>
+          <li><strong>Upper Section:</strong> Contains options affecting the analysis, requiring recomputation when changed. The analysis is triggered by a "Do/Get analysis" button above the division line.</li>
+          <li><strong>Lower Section:</strong> Displays secondary parameters with changes reflecting immediately in the results (automatic update).</li>
+        </ul>
+      </li>
+      <li><strong>Main Panel Structure:</strong> Each main panel contains the visualization of the analysis results. Some panels are further subdivided to show multiple results, for example, the Significance Analysis tab.</li>
+      <li><strong>Picture Download Options:</strong> Users can download visualizations and results in common formats (e.g., PNG, TIFF, PDF). There are respective buttons to select the file format. Upon 'Save plot' the file is downloaded to the local machine.</li>
+      <li><strong>Sending Visualizations to Report:</strong> Upon button click on 'Send only to report' the current shown visualization and associated parameters are saved to the Report. Hence, you can play around with parameters and can save the one of interest to you without cluttering the report with all tried options.</li>
+      <li><strong>Get Underlying R Code and Data:</strong> Upon button click, the R script and respective data to generate shown plot will be presented for download. The script includes the Data selection, pre-processing as well as the respective analysis. For more details make sure to check out [Code and Data](code-and-data.md).</li>
+      <li><strong>Notes:</strong> At the bottom of each tab you can find the Notes field - here you can enter text which will be saved within the report. You can use [markdown syntax](https://www.markdownguide.org/cheat-sheet/) here.</li>
     </ol>
-    </div>
-<div style="float: right; width: 30%;">
-        <img src="{{ site.baseurl }}/assets/images/desing_principleSidePanel.png" alt="The design of the sidepanel" style="width: 100%;">
+  </div>
+  <div style="float: right; width: 30%;">
+    <img src="{{ site.baseurl }}/assets/images/design_principleSidePanel.png" alt="The design of the side panel" style="width: 100%;">
+  </div>
 </div>
-
-
-
diff --git a/docs/interface-details/pca.md b/docs/interface-details/pca.md
@@ -1,12 +1,50 @@
 ---
 title: "PCA"
 layout: default
-parent: Interface Details
+parent: "Interface Details"
 nav_order: 5
 ---
 
-# Principle Component Analysis (PCA)
+# PCA
 
-# PCA Background
+The PCA tab is divided into two main sections: the side panel and the main panel.
+
+## Side Panel
+
+In the side panel, you have the following options:
+
+- **Get PCA**: Clicking this button will generate the PCA plot in the main panel based on the selected annotation type and entities.
+
+- **Toggle "Select Data"**: You can toggle on and off "Select Data". This allows you to quickly select data and perform PCA on the determined subset.
+
+  - **Choose the annotation type to select on**: You can choose an annotation type for selection, such as `cell`. The options are populated based on the sample annotation provided initially. Precisely it is the column names of the sample annotation.
+
+  - **Choose the entities to use**: Select the entities to include in the PCA. The default option is `all`. You can select all present unique within the selected sample annotation category. Note that you can choose multiple items.
+
+- **Choose the variable to color the samples after**: Below the horizontal line, you can choose a variable to color the samples. These options come from the sample annotations provided initially.
+
+- **PC for x-Axis**: Select the principal component for the x-axis. Options include PC1, PC2, PC3, and PC4.
+
+- **PC for y-Axis**: Select the principal component for the y-axis. Options include PC1, PC2, PC3, and PC4.
+
+- **Plot Loadings on top**: You can choose to plot the loadings on top of the PCA plot (the top 5 are used). You can hover over them to identify the respective entities. For more help on how to interpret loadings within a PCA, check out [this resource on PCA loadings interpretation](https://towardsdatascience.com/what-are-pca-loadings-and-biplots-9a7897f2e559).
+
+## Main Panel
+
+The main panel displays the PCA results. Here are some key points:
+
+- **Tabs in the Main Panel**: The main panel has several tabs:
+  - **PCA_plot**: Displays the main PCA plot. The PCA plot is interactive. You can hover over the points to see additional information. The "Select the anno to be shown at tooltip" option allows you to customize the annotation shown in the tooltip. This is populated by the information provided within the sample annotation.
+  - **PCA_Loadings**: Shows the loadings plot. Here the highest loadings in absoulte terms are shown. With the displayed slide bars you can adjust the number of positive/negative loadings to be shown. The loadings are specific for each principal component. To change the principal component, you will need to change in the sidebar the PC for x-Axis. You can also adjust what is shown on the y-axis by selecting the wanted annotation usind the drop down menu. The availbale options are taken from the provided row/entite annotation. 
+  - **PCA_Loadings_matrix**: Provides a matrix of the loadings. The matrix is an extension of the Loadings plot. Here, you can select the number of Principle components to include. Additionally, you can select the minim value of loadings an entities as to have for at least one of the principle components. Note, the chosen defaults are often faulty and need to be adjusted if you get no meaningful result at first.
+  - **Scree_Plot**: Shows the scree plot. The plot is interactive. You can hover over the points to see the precise variance explained by each principal component.
+
+- **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).
+
+### 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!
+- **PCA Interpretation**: Observing the PCA plot can give insights into the relationships between different samples based on the selected annotation and the principal components chosen for the axes. For more information on PCA interpretation, check out [this video on PCA interpretation](https://www.youtube.com/watch?v=FgakZw6K1QQ).
 
-# Reactive options