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:
| ABC |
-0.7873999 |
0.3693501 |
-0.9366675 |
-0.3980517 |
0.3333291 |
-0.3694558 |
| BCD |
1.0997768 |
-0.1648199 |
0.7082051 |
-0.3894525 |
0.0281972 |
2.0574353 |
| CDE |
0.5879843 |
-1.8662817 |
1.5513961 |
-0.6072130 |
0.8533593 |
-0.4592378 |
| DEF |
-0.5337763 |
1.0292288 |
0.8642458 |
-0.7754012 |
0.7428988 |
-0.1797915 |
| EFG |
0.7101083 |
-1.6135976 |
0.1272717 |
-0.3694080 |
-1.4212034 |
0.8324556 |
| FGH |
1.1778824 |
-0.3106655 |
-2.5793397 |
-0.4823849 |
1.5400358 |
0.3969654 |
| GHI |
-0.8351968 |
-0.1536048 |
0.0985296 |
-0.2731899 |
-1.1924649 |
0.4178848 |
| HIJ |
0.4196595 |
0.3856262 |
-0.5990961 |
-1.2415837 |
1.1604674 |
0.0649809 |
| IJK |
0.5342609 |
-0.0442844 |
-1.0079831 |
-0.4534013 |
-1.0377030 |
-0.0542675 |
| JKL |
-1.4365367 |
-0.1781264 |
1.5396741 |
0.5172409 |
1.3363132 |
1.1525874 |
- 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:
| S1 |
239.2055 |
215.5097 |
62 |
Yes |
| S2 |
210.1010 |
188.4852 |
79 |
Yes |
| S3 |
192.7516 |
216.9618 |
57 |
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()
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.
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() 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
- 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:
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")
```