Create a NG-CHM

This vignette demonstrates how to construct a simple NG-CHM, export it to a file, and embed it into RMarkdown.

Sample NG-CHM Data

This vignette uses an additional package of demo data, NGCHMDemoData, which can be installed from our R-Universe repository:

install.packages('NGCHMDemoData', repos = c('https://md-anderson-bioinformatics.r-universe.dev', 'https://cloud.r-project.org'))

and loaded into the current environment:

library(NGCHMDemoData)

The sample data includes a matrix of gene expression data, TCGA.BRCA.Expression, containing 3437 genes (rows) and 200 samples (columns) of breast cancer data from The Cancer Genome Atlas (TCGA). IMPORTANT: In order to be used as the basis for an NG-CHM, a matrix should have both rownames and colnames. Here the rownames are genes and the colnames are TCGA sample identifiers:

BRCA Expression Data Matrix:

TCGA.BRCA.ExpressionData[1:4,1:2]
#>        TCGA-AO-A0JJ-01A TCGA-E9-A1R4-01A
#> TSPAN6         11.83881         9.483816
#> CFH            12.03377        10.835261
#> ENPP4          11.37287        10.749031
#> SEMA3F         12.72281        12.393122

The sample data also includes a vector of TP35 mutation status for the TCGA samples in the matrix. This data will be used to construct a covariate bar in Covariate Bars and Discrete Color Maps. IMPORTANT: In order to be used as the basis for a covariate bar, a vector should have at least one name in common with the colnames of the matrix.

TP53 Mutation Data Vector:

TCGA.BRCA.TP53MutationData[1:2]
#> TCGA-AO-A0JJ-01A TCGA-E9-A1R4-01A 
#>             "WT"             "WT"

Creating a NG-CHM

Using the data loaded above, the chmNew() function can be used to create an NG-CHM:

library(NGCHM)
hm <- chmNew('tcga-brca', TCGA.BRCA.ExpressionData)

A covariate bar of the TP53 mutation status can be added with:

covariateBar <- chmNewCovariate('TP53 Mutation',TCGA.BRCA.TP53MutationData)
hm <- chmAddCovariateBar(hm, 'column', covariateBar)

Export to File

The NG-CHM can be exported to two different file types:

1. A stand-alone HTML file that can be emailed to collaborators, opened in a standard browser, or embedded
   in an RMarkdown file.
2. A ‘.ngchm’ file that can be opened in the NGCHM Viewer.

Both methods use files from the NGCHMSupportFiles package referenced in the Installation page. When loaded, NGCHMSupportFiles sets environment variables pointing to these additional files.

library(NGCHMSupportFiles)
#> Environment variable SHAIDYMAPGEN set to /Users/runner/work/_temp/Library/NGCHMSupportFiles/java/ShaidyMapGen.jar
#> Environment variable NGCHMWIDGETPATH set to /Users/runner/work/_temp/Library/NGCHMSupportFiles/js/ngchmWidget-min.js

The NG-CHM can be exported as a stand-alone HTML file with the chmExportToHTML() function. The first argument is the NG-CHM created above. The second argument is the desired filename.

chmExportToHTML(hm,'tcga-brca.html')

The file ‘tcga-brca.html’ can be shared with collaborators and opened in a standard web browser.

Alternatively, .ngchm file can be created with the chmExportToFile() function.

chmExportToFile(hm,'tcga-brca.ngchm')

The file ‘tcga-brca.ngchm’ can be opened in the NG-CHM Viewer. IMPORTANT: The filename must end with ‘.ngchm’ to open in the NG-CHM Viewer.

Embed into RMarkdown

The .html file can be embedded into RMarkdown via htmltools::includeHTML():

library('htmltools')
filePath = paste(getwd(),'/tcga-brca.html',sep='')
htmltools::includeHTML(filePath)
#> Warning: `includeHTML()` was provided a `path` that appears to be a complete HTML document.
#> ✖ Path: /Users/runner/work/NGCHM-R/NGCHM-R/vignettes/tcga-brca.html
#> ℹ Use `tags$iframe()` to include an HTML document. You can either ensure `path` is accessible in your app or document (see e.g. `shiny::addResourcePath()`) and pass the relative path to the `src` argument. Or you can read the contents of `path` and pass the contents to `srcdoc`.