Quick Start Guide for shinyExprPortal
The deployment of a portal relies on two data files – an expression matrix and a table with observed measures (e.g. clinical measures) – and a configuration file that defines which modules should be displayed in the portal. In the simplest case, the data will have only one sample per subject – an interactive command-line wizard can guide you step-by-step through the creation of the configuration file. If your data contains more than one sample per subject, for example, for different time points, the best approach is to run a function that creates an empty configuration file with placeholders for the fields in the configuration file that must be completed. This configuration file can then be modified in an editor such as RStudio or any other text editor. If your data has multiple samples per subject, you should also check the Data Preparation Guide vignette, which describes the expected format for each data file.
Using the wizard
The use of the interactive wizard requires placing files in the correct folders before starting. The following steps guide you through this.
- Create a folder where the app will be located
To facilitate the organization and deployment of the portal, it is better to create a folder that contains only the files that are related to the project. If you use RStudio, you may prefer to create a project.
- Copy the expression matrix file to the project folder
The matrix can be a CSV, TSV (tab-separated columns) or .rds file
with a matrix object (not a data.frame). The
matrix should have HGNC or similar gene names in rows and sample
identifiers in columns.
If your matrix has the following format, you can move on to the next step:
| S1_01 | S1_02 | S2_01 | S2_02 | S3_01 | S3_02 | |
|---|---|---|---|---|---|---|
| ABC | -1.1826275 | -0.1427944 | 0.2837148 | -1.0846875 | 1.4662465 | 0.3333712 |
| BCD | 0.5009344 | -0.5631573 | -1.9891684 | -0.4535489 | -0.3725553 | -1.4633255 |
| CDE | -0.3673866 | -0.9002269 | 0.8540826 | -0.8459260 | 1.1986017 | -2.1271411 |
| DEF | 0.9106383 | 1.3183111 | 1.7120702 | -0.1965905 | -0.4897399 | -1.3004362 |
| EFG | -0.2517570 | 0.5663286 | 1.4755231 | -0.6066199 | 1.0842046 | 0.2629723 |
| FGH | 1.0313818 | 0.4600922 | 1.4563664 | 1.0294441 | 0.4000891 | -1.3620379 |
| GHI | -1.6147864 | -0.4840838 | 1.4685035 | -0.5380069 | -1.4276492 | -1.5367300 |
| HIJ | -0.4470996 | 0.7821662 | -2.7590426 | -0.1744132 | 1.5379258 | 0.6522824 |
| IJK | 0.1486526 | -1.0208573 | -0.2916623 | -0.0239926 | -0.0995437 | -0.8533035 |
| JKL | -0.4805347 | 0.2912907 | -2.1837019 | 0.7181387 | 0.5009550 | -0.0029226 |
- Copy a measures table file to the project folder
This table can be a CSV, TSV or .rds file with a
data.frame object. In this file, each row corresponds to a
different subject and the order must match the order of samples in the
expression matrix (if your data contains more than one sample per
subject, you should follow the Data Preparation
Guide and not follow these steps). The first column of this table
should be named and contain subject or sample identifiers.
If your measures table has the following format, you can move on to the next step:
| Sample_ID | Platelets_m01 | Platelets_m02 | Age | drugNaive |
|---|---|---|---|---|
| S1 | 180.3649 | 167.5632 | 81 | Yes |
| S2 | 239.6616 | 186.3996 | 86 | Yes |
| S3 | 185.6588 | 208.7710 | 49 | No |
- Optionally copy a metadata table file to the folder
This table should also be in any the formats above and should not have any sample or subject identifier columns. The columns of this table will be used to populate the interface with radio buttons to allow sample subset selection. It should also follow a one row per subject/sample format.
Finally,
- In R, load the package and run
create_config_wizard(getwd())
If you are not using an RStudio project, ensure that the folder with
the files is the current working directory. You can check the current
working directory with getwd() and use
setwd("path/to/folder") to modify it. You should then run
create_config_wizard(getwd()).
The wizard will inform you about what each step is doing and will
ask you questions about names of files and other details to create the
configuration file. It will also wait when you are required to do
additional actions such as creating folders and copying files. Depending
on your choices, at least two files will have been created when you
finish it: app.R and config.yaml.
- Open and execute the code of app.R to test the portal
Still using R (or RStudio) you can source the app.R file to run the code and open the portal on your browser. You can also copy the project folder to a Shiny server or use the rsconnect package to deploy it to shinyapps.io.
Creating a config template
If your data is more complex than the case outlined above, you can
run create_config_template(getwd()) to create a config.yaml
file that will contain placeholder names to be replaced. If you decide
to use this method, you will have to create a lookup table file, by
default named lookup_table.csv, which matches samples with
subjects in the measures table and looks like the following:
#> source sample_id subject_id group
#> 1 microarray sample_1 subject_1 control
#> 2 microarray sample_2 subject_2 treatment
#> 3 microarray sample_3 subject_3 treatmentAs you can see above, the lookup table also includes sample metadata information (group). Any metadata that you want to use to create subsets in the interface (e.g. to compute correlations only for a control group) should be included in this table and then defined in the configuration file under sample_categories, as following:
In the modules of the portal that allow the selection of subset of samples, the configuration above will appear as the following control:
Including new modules in the configuration
After the config.yaml file has been created, you can edit it to modify the setup of modules that have already been defined or include new ones. The modules available in the package vary between their requirements and aims: some of them are more exploratory and only require changes to the configuration file, while others were designed to help showcase and explore results of analysis. If you have computed sets of genes using a package such as WGCNA, you can create a table to load them into the geneModulesHeatmap module, for example. In the current version, the following modules are available:
shinyExprPortal::show_available_modules()
#> [1] "cohortOverview" "degModules" "degSummary"
#> [4] "degDetails" "corrModules" "singleGeneCorr"
#> [7] "singleMeasureCorr" "geneModulesHeatmap" "multiMeasureCorr"
#> [10] "compareTrajGroups" "geneProjectionOverlay"The modules are split in their requirements as follows:
No additional files needed
- Single gene/multiple measures correlations
- Single measure/all genes correlation
- Multi-measure/all genes correlation
- Expression/measures changes over time
Additional files needed
- Differential expression models summary page: table of models, DE packages outputs (e.g. limma, deseq2, edgeR)
- Differential expression models visualization: table of models, DE packages outputs (e.g. limma, deseq2, edgeR)
- Gene modules heatmap: data frame with gene lists (WGCNA, genes of interest, etc.)
- 2D gene projection (e.g. MDS, UMAP): data frame with 2D coordinates for all genes
Check the Full Configuration Guide for details about each module and how to set up the additional files required by each of them.
Deploying the portal remotely
You can deploy the app in your Posit/RStudio Connect server or in the public shinyapps.io website (note that you cannot password-protect the portal under the free plan). You can follow the guide to set up your account and install the required packages. The only other requirement is to change the app.R file by including the optional dependencies for each module (as listed in the configuration guide).
For example, the original app.R would look like this:
If you want to use the geneModulesHeatmap module, to visualize heatmaps of lists of genes, you must also have the RColorBrewer installed. To deploy it in shinyapps.io, you must then import it as in the example below:
```