Quick Start Guide for shinyExprPortal

Deploying a portal using the package relies on two data files – an expression matrix and a table with observed measures (e.g. clinical measures) – and a configuration file that tells the package how to display the portal. For the simple case where each subject in the dataset only has one sample, there is a command-line wizard that will guide you step-by-step through the creation of the configuration file. Alternatively, there is a function that creates an empty configuration file with placeholders for the required properties, which can then be edited in any text editor. For more complex cases, such as multiple samples per subject, the Data Preparation Guide vignette describes how to prepare the data to use with the package.

Using the wizard

Before starting the wizard, ensure you do the following

  1. Create a folder where the app will be located

If using RStudio, create a new project to facilitate the rest of the setup.

  1. Place an expression matrix file in the project folder

With HGNC or similar gene names in rows and samples in columns. The file can be a .csv, .tsv/txt or .rds file. If using an .rds file, save it as a matrix object, not a data.frame.

Go to the next step if your expression matrix is structured in this way and you saved it in the project folder:

S1_01 S1_02 S2_01 S2_02 S3_01 S3_02
ABC -1.4127426 -0.3621493 0.2147088 -0.8174455 0.7024095 -0.6686752
BCD -1.0707987 0.1816074 -0.6670617 0.3973465 -0.5420608 1.5772780
CDE -1.1254756 0.8003482 -2.2905743 -0.2206138 -0.8058991 1.3681189
DEF 2.8476257 0.2010853 -0.3333579 -1.5883781 1.2044741 -0.5274128
EFG 1.0658611 0.8334225 0.7420654 -0.0083339 -0.1881590 1.3140758
FGH -0.5816411 -0.0055004 1.6779702 0.1731967 -0.2770538 -0.2182928
GHI -0.5111421 0.3021287 0.6301968 1.8334751 -0.5823513 0.3708706
HIJ 1.2977422 -1.1457535 -0.5422707 -2.4843264 1.3926210 -0.5818575
IJK 1.0270082 0.1455537 0.2319058 -1.1548395 -1.2458561 0.2780365
JKL -0.2147963 1.6957425 -0.9073559 0.2659457 2.2257624 1.1482463
  1. Place a measures table file in the project folder

With variables in columns and subjects in rows. The subjects must be in the same order as their samples in the expression matrix. Again most formats can be used, but if using a .rds file, the measures file must be saved as a data.frame.

Go to the next step if your measures table is structured in this way and you saved it in the project folder:

Sample_ID Platelets_m01 Platelets_m02 Age drugNaive
S1 166.0402 169.0903 84 Yes
S2 159.0836 187.3554 41 Yes
S3 219.9151 242.7457 75 No
  1. Optionally place a metadata table file in the folder

A table that contains sample information such as control group, age, etc. This will add radio buttons on the interface for selecting subsets based on these variables. It should also follow a one row per subject/sample format.

Finally,

  1. In R, load the package and run create_config_wizard()

If you are not using an RStudio project, ensure that the folder with the files is the current working directory (check with getwd()).

The wizard will inform you about each stage and ask questions to set up the configuration file. It will also wait when you are required to do additional actions such as creating folders and moving files. Depending on your choices, at least two files will have been created: app.R and config.yaml.

  1. Open and run the contents of app.R to test the portal

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

Alternatively, you can run create_config_template() to create a config.yaml file that will contain placeholders that you can edit. If you decide on 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 treatment

As 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:

sample_categories:
  - name: group
    label: Group
    values:
      - treatment
      - control

In the portal, this will appear as:

Adding modules

Once the config.yaml file is created, you can edit it to modify the setup of modules that are already defined or add new ones. The modules included in the package vary between their requirements and aims: some of them are more exploratory and only require setting them up in 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"

Below is a summary of which modules work with the basic data files and which ones require additional files:

No additional files needed

Additional files needed

Check the Full Configuration Guide for details about each module and how to set up the additional files required by each of them.

Deploying it remotely

You can deploy the app in your Posit/RStudio Connect server or, alternatively, in the public shinyapps.io website (note that the app will be public under the free plan). You can follow the guide to set up your account and install the required packages. The only other requirement to make it work is to modify the app.R file to include the optional dependencies for each module (as listed in the configuratoin guide).

For example, the original app.R would look like this:

library(shinyExprPortal)
run_app("config.yaml")

If you want to use the geneModulesHeatmap module, for visualizing heatmaps of lists of genes, you must also have the RColorBrewer installed. To deploy in shinyapps.io, you must then import it like in the example below:

library(shinExprPortal)
library(RColorBrewer)
run_app("config.yaml")

```