Modules
The final part of the configuration file is the definition of the
modules that should be included in the portal. These should be specified
in the order that they should appear on the portal menu. The function
show_available_modules() can be used to check which modules
are currently supported after the package is loaded; this guide is also
up to date and can also be used as reference. The following modules and
grouped modules are currently supported (grouped modules are
pseudo-modules that appear in sub-menus on the portal):
The package contains suggested dependencies when they are only needed by specific modules. This guide lists all these additional dependencies for each module. The other way to discover an additional dependency is to set up the configuration file and try to run the portal. If a package is missing, the portal will not run and you will be notified about which package dependency is missing.
Many modules also have optional settings, often for customization.
Optional settings supported by all modules
title
A custom name for the module can be defined for every module.
description A description paragraph can be defined to instruct visitors on usage of a module or to provide additional information, such as descriptions of the data being visualized or links to external references.
Example:
Modules:
cohortOverview
Required packages: {r2d3}
This module displays a grid of small line plots for each subject in the measures file. The line plots show each subjects’ trajectory for various measures over time and viewers can select the line color from a set of variables defined in the configuration file.
Minimum configuration
cohortOverview:
profile_variables:
Platelets:
values: [Platelets_m01, Platelets_m02]
colour_variables: [Age, Platelets_m01, Platelets_m02]Example: 
compareTrajGroups
Optional required packages:
[{RColorBrewer}](https://CRAN.R-project.org/package=RColorBrewer)
This module shows the combined expression and measure trajectory of
subjects over time. Viewers can select one gene and one measure that was
observed over time. The idea of the module is to split subjects in two
or more groups using a sidebyside_category from the lookup
table (e.g. two drug groups). Samples are initially filtered from a
visitor selection following subset_categories (e.g. if the
lookup table contains DrugGroup, Time and
Tissue, the only remaining valid category here is
Tissue, so visitors can select between different tissue
types). Samples are further selected based on the time variable defined
in the configuration file through trajectory_category,
which is also a column in the lookup table. The measures to be paired
with the samples are taken by combining compare_variables
with the time-values from trajectory_category. For example,
if Platelets is one of the variables listed as
compare_variables and the times are m01 and
m02, the trajectory will be constructed from the
observations of Platelets_m01 and
Platelets_m02 in the measures table. The expression of the
selected gene will also be taken using observations of samples at times
m01 and m2. In the interface, visitors can
change the measure used for the trajectory from the list of
compare_variables.
Minimum configuration
compareTrajGroups:
subset_categories:
- Tissue
sidebyside_category: DrugGroup
trajectory_category: Time
compare_variables:
- PlateletsExample: 
Optional settings
custom_traj_palette: the name of a RColorBrewer
palette or a list of valid colours (e.g. hex value) can be supplied
using this keyword. The colors will be used in order of appearance to
color the points for each value of trajectory_category.
advanced: the following advanced options can be defined, otherwise the defaults described earlier in this guide will be used:
- fit_method: if
TRUEorAllowHide, lets visitors choose a regression method from the available ones (linear,quadraticorcubic).AllowHideincludes a None option in the interface.
*Example of optional settings
degDetails
This module displays a volcano plot and a table with the results of
differential expression analysis exported by packages such as
limma, deseq2, and edgeR. It
requires a tabular file that organizes the results of differential
expressions and that should contain a high level category variable that
identifies different types of models and a File column with
the corresponding file names. The following is a valid minimal model
results table:
| Model | File |
|---|---|
| Linear | Model_1.txt |
| Nonlinear | Model_2.txt |
The following is an example of a more layered model setup, with two files per set of models (two files for Linear and two files for Nonlinear):
| Model | Time | Drug | File |
|---|---|---|---|
| Linear | m01 | d1 | Model_1.txt |
| Linear | m02 | d2 | Model_2.txt |
| Nonlinear | m01 | d1 | Model_3.txt |
| Nonlinear | m02 | d2 | Model_4.txt |
The configuration for this module requires a
category_variable to group the models and a
models file pointing to the table; this file can be a
tab-separated or comma-separated values file. Individual model results
should be placed inside a models subfolder.
Minimum configuration:
Example: 
Optional settings
link_to: name of another module to create a link to in the results table. In combination with the remaining variables in the model results table, it enables inspecting directly a gene with the matching subsets, for example, of time and tissue type. The module linked to should also support this functionality for this setting to work.degSummary
Required packages:
{knitr}, {kableExtra}
This module displays a summary table of all models included in the
models table (see previous module). It aggregates the number of
significant genes by p-value and adjusted p-values (with 0.05 threshold)
for each model. A partition_variable, matching a variable
in the models table (e.g. Drug) is used to partition the results
vertically. With two drugs d1 and d2, this means that the table will
contain 4 columns: number of significant d1 p-value genes, d1 adjusted
p-value genes, d2 p-value genes and d2 adjusted p-value genes.
Minimum configuration
geneModulesHeatmap
Required packages: {RColorBrewer}
This modules enables the visualization of a subset of genes, e.g. a co-expression module, cluster or signature, related to a downstream analysis method such as regulatory networks. It displays a heatmap with the expression of the genes from a viewer-selected module and scatterplots with the association between the module eigengene and measures defined in the configuration file. Gene modules must be specified in a table with a model/analysis category or source, valid sample categories associated with that module, module name and a list of associated genes is required. It is also possible to include annotations in the heatmap by defining a list of valid measures or categorical variables that the viewer can select. The following is an example of a valid modules table:
| Category | Time | Drug | ModuleName | targetGenes | rank |
|---|---|---|---|---|---|
| Linear | m01 | d1 | ABC (Activated) | PQR,QRS,RST | 1 |
| Linear | m01 | d1 | BCD (Inhibited) | QPP,PQQ,RST,TRR,WYX,WEX | 2 |
| Linear | m01 | d1 | CDE (Activated) | QQZ,ZZE,YYZ,YYE,PPA | 3 |
| Linear | m01 | d1 | DEF (Activated) | PP,APP,BBE | 4 |
| Linear | m02 | d1 | EFG (Activated) | HJK,JKL,MNJ | 1 |
| Linear | m02 | d1 | FGH (Activated) | MNO,NOP,PQR,QRS,RST,STU | 2 |
This module also support generic lists of genes that can be made
visible to any selection of subsets of samples. To define lists of genes
for this purpose, you can use * as a wildcard in a sample
category column. The following is an example of that in hypothetical
co-expression modules (e.g. outputs from WGCNA or CEMiTool), which
allows the viewer to explore the same modules for any subset of Time and
Drug.
| Category | Time | Drug | ModuleName | targetGenes | rank |
|---|---|---|---|---|---|
| Coexp | * | * | gray | PQR,QRS,RST | 1 |
| Coexp | * | * | red | QPP,PQQ,RST,TRR,WYX,WEX | 2 |
| Coexp | * | * | blue | QQZ,ZZE,YYZ,YYE,PPA | 3 |
| Coexp | * | * | orange | PP,APP,BBE | 4 |
| Coexp | * | * | green | HJK,JKL,MNJ | 1 |
| Coexp | * | * | black | MNO,NOP,PQR,QRS,RST,STU | 2 |
The configuration requires a modules_table that points
to the table file above, a category_variable that
identifies the table column with highest-level category of modules, a
modules_variable that identifies the table column with the
names of the modules and a genes_variable, which identifies
the table column that contains a list of gene symbols separated by
comma. In the interface, viewers will select a Category and subsets from
the remaining sample categories on the table (e.g. above, Time and Drug)
to see a list of modules associated with that category and sample
classes. An optional ordering column can be included in the table, and
set in the config file in rank_variable, to choose a custom
appearance order for each modules, as in the example above.
Minimum configuration
geneModulesHeatmap:
modules_table: modules.csv
category_variable: Category
modules_variable: ModuleName
genes_variable: targetGenesExample: 
Optional settings
subset_categories: list of categories to display as
filter. This option should be used if one or more sample categories from
the lookup table should not be used to subset samples, such as
pseudo-categories that partition subjects.
scatterplot_variables: a list of measures to correlate
with the module eigengene and display in scatterplots similar to those
in the single gene module. annotation_variables: a list
of measures can be supplied so that viewers can add annotations above
the heatmap. The variable names should match the measures table,
independent of their timepoint.
custom_annotation_colors: by default, the heatmap
package (the plotly-powered iheatmapr) will automatically assign colors
for the annotations. Alternatively, an RColorBrewer palette or a list of
colors (e.g. hex values) can be assigned to selected individual
variables (a variable with no custom palette will use a default
palette). For continuous variables, interpolation will be applied to a
list of colors.
annotation_range: for numeric variables that share a
theoretical range of values, but this range varies in observed data, it
is possible to define individual ranges so that the color scale is the
same across annotations. For each annotation variable, a minimum and
maximum value can be provided through a list. A common use case is for
disease activity variables with a maximum value that decreases over time
as patients improve.
custom_heatmap_palette: a custom RColorBrewer palette
can be provided to override the default RdBu palette used
in the heatmap.
Example of optional settings:
geneModulesHeatmap:
...
subset_categories:
- Cell_Type
scatterplot_variables:
- Platelets_m01
- Platelets_m02
annotation_variables:
- Age
- Platelets_m01
- Platelets_m02
- diseaseActivity_m01
- diseaseActivity_m02
custom_annotation_colors:
drugNaive:
Yes: yellow
No: green
Age: Reds
annotation_range:
diseaseActivity_m01: [0, 99]
diseaseActivity_m02: [0, 99]
custom_heatmap_palette: BrBGgeneProjectionOverlay
This module allow viewers to explore the variation of expression between pre-computed clusters of genes across subsets of subjects, following a pre-computed 2D projection of the genes from the whole dataset. This module was developed considering a 1:1 subject-to-sample scenario rather than multiple samples per subject. It display the 2D projection in two scatterplots: one scatteprlot shows the points colored by the group membership and the other shows the mean expression of the gene relative to the mean expression of all genes (i.e. a fold change). Sample categories can be used to define subsets of samples based on a characteristic of the subjects, such as a disease activity measure. The scatterplot will then show the expression in variation for that subset only. The coordinates file must contain gene symbols, two columns for position and a column for group. The first three must appear in that exact order, as the following:
| gene | x | y | group |
|---|---|---|---|
| EBSTE | 0.6300528 | -0.9797925 | 1 |
| KQKGP | -0.7802847 | 0.4296746 | 2 |
| KCTRB | 0.2727336 | 1.1359418 | 1 |
| BSUQS | 0.7320335 | 0.1305692 | 1 |
| FAVQE | -0.5509570 | 0.5461306 | 3 |
| EBSTE | -0.0735220 | -0.2765579 | 1 |
| KQKGP | 0.6999208 | -0.5223478 | 2 |
| KCTRB | 1.8967517 | -0.0581422 | 1 |
| BSUQS | -1.3357801 | 1.0836532 | 1 |
| FAVQE | -1.1710355 | 0.4838897 | 3 |
This table can be an .rds, .csv or .tsv file and must be defined in
the coordinates_file setting. The group column must be
indicated using the group_variable setting.
Minimum configuration
Example: 
Optional settings
The module also includes a heatmap to view the individual expression
of samples for the genes that belong to a selected group, and it can
display annotations based on the measures table. These should be defined
through annotation_variables, and, as with the previous
module, there is also the option of defining custom colors through
custom_annotation_colors and fix variable ranges through
annotation_range.
annotation_variables: a list of measures can be
supplied so that viewers can add annotations above the heatmap. The
variable names should fully match the measures table names, including
the time point suffix. custom_annotation_colors: by
default, the heatmap package (the plotly-powered iheatmapr) will
automatically assign colors to the annotation variables. Alternatively,
an RColorBrewer palette or a list of colors (e.g. hex values) can be
assigned to selected individual variables (a variable with no custom
palette will use a default palette). For continuous variables,
interpolation will be applied to a list of colors.
annotation_range: for numeric variables that share a
theoretical range of values but this range varies in observed data, it
is possible to define individual ranges so that the color scale is the
same across annotations. For each annotation variable, a minimum and
maximum value can be provided through a list. A common use case is for
disease activity variables with a maximum value that decreases over time
as patients improve, or blood samples.
Example of optional settings:
singleGeneCorr
This module allows viewers to compare the expression of a single gene
from a selected subset of samples with observed measures through
scatterplots. Groups of scatterplots are arranged in sub-tabs. Groups
are specified as a list through the tabs field. Each tab
contains a name to be displayed, a scale
setting, which can be either free (each scatterplot has its
own range in the horizontal axis) or fixed (all
scatterplots in a tab will have the same horizontal axis), and a list of
variables for each scatterplot. This module can be passed as a name to
link_to in other modules.
Minimum configuration
Example:
Optional settings
subset_categories: list of categories to display as filter. To be used if not every sample category in the lookup table should be used to create subsets of samples. For example, if a pseudo-category was created to split patients based on a clinical measure, you may not want to show that filter in every module in the app. color_variables: a list of variables, either numeric or discrete, can be supplied so that vi can assign a color to subjects. custom_point_colors: optionally, for the color variables, it is possible to supply custom colors as: valid Vega schemes, list of colors or named list of colors (see DrugNaive in the example below).
advanced: the following advanced options can be defined, otherwise the defaults described earlier in this guide will be used:
- correlation_method: if
TRUE, allows visitors to alternate between Pearson, Spearman and Kendall methods for computing correlation.
- expression_outliers: if
TRUE, allows visitors to exclude expression outliers from scatterplots, either through Tukey’s IQR range filtering, 5/95 percentiles or none.
- measures_outliers: if
TRUE, allows visitors to exclude measures outliers from scatterplots, either through Tukey’s IQR range filtering, 5/95 percentiles or none.
- fit_method: if
TRUEorAllowHide, allows visitors to choose a regression method from the available ones (linear,quadraticorcubic).AllowHideincludes a None option in the interface.
Example of optional settings:
singleMeasureCorr
This module allows viewers to explore a table with the correlation between one single measure and all genes from a subset of samples. The module can be set up with a list of measures from which viewers can select in the interface and the optional advanced settings for correlation method and outlier removal. As a default, the module can be defined simply as TRUE to include all numeric measures and no advanced settings:
Minimum configuration
A list of variables can be provided through
dropdown_variables:
Example: 
Optional settings
subset_categories: list of categories to display as
filter. To be used if not every sample category in the lookup table
should be use to create subsets of samples. For example, if a
pseudo-category was created to split patients based on a clinical
measure, you may not want to show that filter in every module in the
app.
link_to: name of another module to create a link to in
the results table. Every gene on the table will be a clickable link to
the module, with the subset matching the ones selected by the visitor.
The module linked to should also support this functionality for this
setting to work.
advanced: the following advanced options can be defined, otherwise the defaults described earlier in this guide will be used:
- correlation_method: if
TRUE, allows visitors to alternate between Pearson, Spearman and Kendall methods for computing correlation.
- expression_outliers: if
TRUE, allows visitors to exclude expression outliers from scatterplots, either through Tukey’s IQR range filtering, 5/95 percentiles or none.
- measures_outliers: if
TRUE, allows visitors to exclude measures outliers from scatterplots, either through Tukey’s IQR range filtering, 5/95 percentiles or none.
Example of optional settings:
multiMeasureCorr
This module allows visitors to view a heatmap and a table with the
most significantly correlated genes across a predefined set of measures.
The genes are taken from a subset selected by visitors, based on the
sample categories. This module requires the specification of
heatmap_variables, with multiple named lists of
variables.
Minimum configuration
Example:
Optional settings
subset_categories: list of categories to display as filter. To be used if not every sample category in the lookup table should be use to create subsets of samples. For example, if a pseudo-category was created to split patients based on a clinical measure, you may not want to show that filter in every module in the app.
custom_heatmap_scheme: a valid Vega schemes can be
provided to override the default redblue scheme.
link_to: name of another module to create a link to in the results table. Every gene on the table will be a clickable link to the module, with the subset matching the ones selected by the visitor. The module linked to should also support this functionality for this setting to work.
advanced: the following advanced options can be defined, otherwise the defaults described earlier in this guide will be used:
- correlation_method: if
TRUE, allows visitors to alternate between Pearson, Spearman and Kendall methods for computing correlation.
- expression_outliers: if
TRUE, allows visitors to exclude expression outliers from scatterplots, either through Tukey’s IQR range filtering, 5/95 percentiles or none.
- measures_outliers: if
TRUE, allows visitors to exclude measures outliers from scatterplots, either through Tukey’s IQR range filtering, 5/95 percentiles or none.
Example of optional settings: