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.

  1. 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.

  1. 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.2011222 0.9136894 -0.3771393 0.7387623 0.5217865 0.5904075
BCD -0.2205230 0.2976324 -0.9090196 -0.7862833 -0.0703161 -0.0516805
CDE 0.9735785 1.2653886 -2.2692117 -0.2301233 0.3848107 0.5959624
DEF 1.1019936 -1.1031321 -0.0604219 0.1064487 0.3945320 -1.8486222
EFG 0.2741162 0.9132152 -1.5075864 -0.5112066 1.0834514 0.7842275
FGH 0.1277794 0.0928274 -0.2175801 0.6320683 -0.5760626 1.1190752
GHI -0.4785599 0.5029591 -1.3061171 -0.8710328 -0.2850174 -0.6456930
HIJ 0.3569087 -1.1996977 0.0423683 0.8497457 1.4721118 -0.6987773
IJK -0.3941647 1.9319724 -1.5152615 -0.3962332 -1.0091076 -1.2697819
JKL 0.5115816 0.7440640 -0.8089925 -0.4323540 -1.0463775 0.0090409
  1. 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 158.3633 211.1130 33 Yes
S2 248.6659 247.3781 44 Yes
S3 194.0834 170.4174 67 No
  1. 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,

  1. 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.

  1. 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 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 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

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

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

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:

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

```