Skip to contents

Architecture

Source: vignettes/Architecture.Rmd
Architecture.Rmd

An MCView app needs two components in order to run:

  1. Configuration file (config.yaml).
  2. Cached data of one or more datasets.

The app can use additional files that are not essential:

  1. help.yaml - custom help messages.
  2. about.Rmd - custom “About” page.

In order to bundle together the configuration and cached data, MCView supports a concept of a ‘project’.

Projects

A project is a standard library structure that binds config and cache, e.g.:

my_project
├── config
│   ├── about.Rmd
│   ├── config.yaml
│   └── help.yaml
└── cache
    ├── ko
    └── wt

The above example shows the directory structure of a project named my_project that contains two metacell datasets - wt and ko. Multiple functions in the MCView package would accept the project path and would expect to find the configuration files and cache in the standard relative path.

Creation of a project can be done by running:

MCView::create_project("my_project")

Which would open a text editor in order to edit the configuration file.

Configuration files

An MCView project can have 3 configuration files:

  1. config.yaml - main configuration file (required)
  2. help.yaml - help text messages (optional)
  3. about.Rmd - text for the about tab (optional)

The main configuration file (config/config.yaml) contains the parameters:

title: MCView
tabs: ["QC", "Manifold", "Genes", "Markers", "Gene modules", "Diff. Expression", "Cell types", "Annotate", "About"] # which tabs to show
help: false # set to true to show introjs help on start
selected_gene1: Foxc1 # Default selected gene1 (optional)
selected_gene2: Twist1 # Default selected gene2 (optional)
selected_mc1: 1 # Default selected metacell1 
selected_mc2: 2 # Default selected metacell2
datasets: # optional parameters per dataset
  PBMC163k:
    min_d: 0.3 # default minimal edge distance to show in projection plots
    # projection_point_size: 1 # Default size for projection points
    # projection_stroke: 0.1 # Default line stroke for projection points
    # scatters_point_size: 2 # Default size for scatter plot (such as gene gene plots)
    # scatters_stroke_size: 0.1 # Default line stroke for scatter plot (such as gene gene plots)

title

The title of the app. This would be shown on the top left of the screen.

tabs

Controls which tabs to show in the left sidebar and their order. Options are:

["QC", "Manifold", "Genes", "Query", "Atlas", "Markers", "Gene modules", "Projected-fold", "Diff. Expression", "Cell types", "Flow", "Annotate", "About"]

Why would you want to add or remove tabs?

Many times we would want to separate between a the ‘development’ version of an MCView app which allows users to re-annotate the data and a ‘production’ version which only contains data analysis tabs. This can be done by removing “Annotate” from the tabs field. In addition, you might want to always start the app from the “Genes” tab instead of the “Manifold”, which can be done by changing the order in the tabs field. And lastly, some tabs such as “Query”, “Atlas” and “Flow” are not enabled by default and should be added explicitly to the tabs section of the config file.

help

Controls wether to start the app with a help modal (from introjs). Help messages can be edited in help.yaml file (see below).

selected_gene1/selected_gene2 (optional)

The default genes that would be selected (in any screen with gene selection). If this parameter is missing, the 2 genes with highest max(expr)-min(expr) in the first dataset would be chosen.

selected_mc1/selected_mc2

The default metacells that would be selected in the Diff. Expression tab.

datasets (optional)

Additional per-dataset parameters. Current parameters include default visualization properties of projection and scatter plots.

help.yaml

This file contains the help messages used by introjs. It shouldn’t be changed in general, except maybe the introduction message. Note that the messages refer to shiny elements, so you would have to look at the code itself in order to identify the element of each message.

about.Rmd

This Rmarkdown file contains the contents of the about page. Edit it as you wish, and remember that you can remove the “About” tab altogether using the tabs parameter in config.yaml.

Cached data

In order to run, MCView needs to pre-process the metacell matrix and cluster annotations. This can be done by the MCView::import_dataset function which accepts a project path, dataset name and path to the h5ad file that was generated from metacell1.

The cached files would be saved under the cache section in the project folder, in a separate folder for each dataset. In the above example:

└── cache
    ├── ko
    └── wt

You can list the datasets in the project using:

MCView::dataset_ls("my_project")

And removal of a dataset can be done by:

MCView::dataset_rm("my_project", "dataset")

Running the app

Running the app can be done by running:

MCView::run_app(project = "/path/to/my/project")

Deployment

MCView can generate a ‘deployment ready’ version of the app by running:

MCView::create_bundle(project = "/path/to/my/project", path = "/path/to/the/bundle", name = "my_project")

This would create a minimal shiny app in “/path/to/the/bundle/my_project” directory which would contain:

  1. app.R file.
  2. project config and cache.

Note: The bundle would use use the installed version of MCView in server. If you want to create a ‘self-contained’ bundle that would include MCView code as well, set self_contained=TRUE.

The bundle can then be deployed in shiny-server by running:

rsconnect::deployApp(appDir = "/path/to/the/bundle/my_project")

or any other environment that supports serving shiny apps.

Note that when deploying to these services make sure you have the MCView package installed.