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

2. 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.2812006 | 0.0959465 | -0.1433469 | 0.6190067 | -1.5891782 | 0.4628595
BCD | 0.6825456 | 0.8063005 | -0.2100111 | 1.0613239 | 0.8104832 | -0.7839131
CDE | 0.9457214 | -1.0537737 | 0.4584748 | -0.9157724 | -1.3469275 | 0.7094322
DEF | -0.2658735 | 1.0678908 | 1.4588013 | 1.0377882 | 0.2932243 | 0.5205120
EFG | -0.6187387 | 2.0405124 | 0.4706340 | -1.9104065 | 0.9537008 | -0.8604187
FGH | 0.4830993 | -0.2596064 | 0.5381246 | 0.7235574 | -0.4357462 | 0.8665434
GHI | 0.6446006 | -0.7821890 | 0.5983716 | 0.0114790 | -0.8537087 | 0.4176822
HIJ | -0.5693693 | -0.8254058 | 2.0486070 | -0.8659759 | 0.5202481 | 1.4644767
IJK | 1.7936581 | -1.0738313 | 0.8506957 | -0.8246412 | -0.7553441 | 1.1727210
JKL | 0.2358244 | -0.3674878 | 0.9710115 | 0.5942218 | 0.0630812 | 0.6214916

3. 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 | 197.9540 | 191.9478 | 53 | Yes
S2 | 187.4138 | 231.0331 | 31 | Yes
S3 | 177.9780 | 159.0400 | 48 | No

4. 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,

5. 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`.

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

- 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 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")

```