---
title: ""
author: "Authors: Jianhai Zhang, Jordan Hayes, Le Zhang, Bing Yang, Wolf B. Frommer, Julia Bailey-Serres, and Thomas Girke"
date: "Last update: `r format(Sys.time(), '%d %B, %Y')`"
output:
  BiocStyle::html_document:
    css: file/custom.css
    toc: false
    toc_float:
        collapsed: true
        smooth_scroll: true
    toc_depth: 4
    fig_caption: yes
    code_folding: hide
    number_sections: true
    self_contained: false
fontsize: 14pt
bibliography: bibtex.bib
package: spatialHeatmap
vignette: >
  %\VignetteIndexEntry{spatialHeatmap: Visualizing Spatial Assays in Anatomical Images and Network Graphs}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{css, echo=FALSE}
pre code {
white-space: pre !important;
overflow-x: scroll !important;
word-break: keep-all !important;
word-wrap: initial !important;
}
```

```{r global_options, include=FALSE}
## ThG: chunk added to enable global knitr options. The below turns on
## caching for faster vignette re-build during text editing.
#knitr::opts_chunk$set(cache=TRUE)
```
<!-- 

<style type="text/css">
 .main-container { max-width: 1800px; margin-left: 5px; margin-right: auto; }
</style>

<style>body { text-align: justify }</style>  


```{r css, echo = FALSE, results = 'asis'}
BiocStyle::markdown(css.files=c('file/custom.css'))
```

-->

```{r setup0, eval=TRUE, echo=FALSE, message=FALSE, warning=FALSE}
library(knitr); opts_chunk$set(message=FALSE, warning=FALSE)
```

Authors: Jianhai Zhang, Jordan Hayes, Le Zhang, Bing Yang, Wolf B. Frommer, Julia Bailey-Serres, and Thomas Girke  

# Summary

This Shiny app is an integrated implementation of the R/Bioconductor package [spatialHeatmap](http://www.bioconductor.org/packages/release/bioc/vignettes/spatialHeatmap/inst/doc/spatialHeatmap.html){target="_blank"}. It is designed for interactively visualizing numeric values in biological assays (e.g. RNA-seq, microarray, qPCR) on an anotomical aSVG image. First, the core feature "Spatial Heatmap" maps numeric values of target assayed items (genes, proteins, metabolites, etc) to matching spatial features (cells, tissues, organs, etc) in the aSVG image. In this process, the values are translated into different colors and these colors are used to paint the spatial features. The resulting images are called spatial heatmaps (SHMs). Second, nearest neighbors of each target assayed item are selected by most similar expression profiles independently. All target items and their nearest neighbors are hierachically clustered and visualized as interactive matrix heatmap. Third, network modules are identified internally and the module containing a target item is displayed as interactive network graph.     

In addition to the primary visualizaion, the Spatial Enrichment (SE) is specialized in identifying spatial feature-specific genes in RNA-seq count data.  

This app is a general visualization tool, not limited to biological data. Operations on this app are expected to follow the order as each panel appears. Otherwise if errors arise, the webpage should be refreshed.

**For a quick test, select one example under "Data & aSVGs" on the Landing Page, or select "customData", download the example data and aSVG, and upload them to respective fields.**     

# Input

**Step1: choose custom or default data sets** There are pre-configured examples (e.g. mouse_Merkin) for demonstration, and the "customData" allows to upload aSVG file(s) and data matrix generated by users.  

**Step 2: upload custom data**   
**2A: Upload formatted data matrix** Upload the data matrix in tabular file where target samples should have matching spatial features (shapes) in the aSVG(s). Note, the file name should not contain parenthesis. E.g. `arab_expr_example.txt` is expected while `arab_expr_example.txt(1).txt` will raise errors. The separator in the tabular file can only be one of tab, space, comma, or semicolon.  
**2B: is column or row gene?** Specify genes in row or column.
In the data matrix where row and column names are gene IDs and sample/conditions respectively, the column names MUST follow these naming scheme: 1) A sample name is followed by double underscore then the condition. E.g. in "root_pGL2__hypoxia", "root_pGL2" is the sample (atrichoblast epidermis) and "hypoxia" is the condition. 2) The "\_\_" is a reserved separator, so it cannot be used in sample or condition identifiers. 3) Each column name must be unique. To achieve such naming format, simple sample/conditions can be edited in a regular text editor/Excel, while if complex it can be generated with the function filter_data in "spatialHeatmap". One column of metadata (e.g. gene annotation) could be optinally appended to sample/condition at the end, where the column name should not include "\_\_". Only values of samples having a matching feature counterparts in the aSVG are translated to colors in spatial heatmaps.
In the case of spatial-temporal data, there are three factors: samples, conditions, and time points. The naming scheme is slightly different and includes three options: 1) combine samples and conditions to make the composite factor sample-condition, then concatenate the new factor and times with double underscore in between, i.e. "sampleCondition__time"; 2) combine samples and times to make the composite factor sample-time, then concatenate the new factor and conditions with double underscore in between, i.e. "sampleTime__condition"; or 3) combine all three factors to make the composite factor "sampleTimeCondition" without double underscore.  

**Step 3: upload custom aSVG(s)**  
**3A: upload one aSVG file** Upload an aSVG file generated by users, where the aSVG means spatial features are annotated with unique identifiers. An example aSVG is downloadable below. Note, the aSVG file name should not contain parenthesis. E.g. "arabidopsis.thaliana_root.cross_shm.svg" is expected while "arabidopsis.thaliana_root.cross_shm(1).svg" will cause errors.  

**3B (optional): upload multiple aSVG files** Upload more than one aSVGs, such as aSVGs representing organs at different growth stages. The order of aSVGs should be indicated by suffixes of "_shm1", "_shm2", ... . e.g. "arabidopsis.thaliana_organ_shm1.svg", "arabidopsis.thaliana_organ_shm2.svg". The spatial heatmaps would be a composite image including all aSVGs. This step takes precedence over "Step 3A". A pre-uploaded example is "growthStage_Mustroph" under "Step 1".   


More details about how to set up aSVG file and data matrix are provided in the [package vignette](https://jianhaizhang.github.io/SVG_tutorial_file/spatialHeatmap.html){target="_blank"} and the [SVG tutorial](https://jianhaizhang.github.io/SVG_tutorial_file/){target="_blank"}. The example aSVG files and formatted data matrices are provided on the landing page and can be uploaded directly for testing after selecting "customData".  

**Additional files**  
**Upload a config file (optional)** Optionally upload a custom configuration file in "yaml" format, where customized default parameters are set such as the color scheme, title size, etc. A specialized yaml file editor is recommended for editing this file, e.g. [onlineyamltools](https://onlineyamltools.com/edit-yaml){target='_blank'}.  

**Upload batched data, aSVGs in two separate tar files (optional)** If there are a large amount of data and aSVG files to visualize, they can be compressed in two separate tar files and uploaded in a batch. See the function "write_hdf5" for details.   

# Matrix Heatmap  

The nearest neighbors of each selected/target gene in the data matrix are selected with correlation or distance measure independently, then all target genes and their nearest neighbors are hierarchically clustered and visualized in an interactive matrix heatmap, where target genes are labeled by black lines. The interactive features include 1) mouse over a cell to see row/column labels and cell value, and 2) draw a rectangle to zoom in and double click to zoom out.  

# Network  

This section applies network analysis on the subsetted matrix in the Matrix Heatmap with WGCNA [@Langfelder2008-sg; @Langfelder2012-nv; @dynamicTreeCut]. Briefly, a correlation matrix or distance matrix is computed on all genes in Matrix Heatmap, and transformed to an adjacency matrix and topological overlap matrix (TOM) sequentially, which are advanced measures to quantify coexpression similarity. Then network modules are identified by hierarchinally clustering the TOM-transformed dissimilarity matrix 1-TOM, which are clusters of genes with highly similar coexpression profiles. The module containing a target gene is finally displayed as interactive network graph. Since this is a coexpression analysis, variables of sample/condition should be at least 5. Otherwise, resulting modules are not reliable. Refer to [package vignette](https://jianhaizhang.github.io/SVG_tutorial_file/spatialHeatmap.html){target="_blank"} for details.  

# Spatial Enrichment  

The Spatial Enrichment is specialized in detecting spatial feature-specific genes (SFSGs) in RNA-seq count data. Basically, the app compares a target feature with each reference feature by using tools of edgeR [@edgeR], DESeq2 [@DESeq2], limma [@limma], distinct [@distinct]. The target and reference features, and tools are selected by users. If more than one tools are selected, the overlaps of identified SFSGs between all selected tools are presented. These SFSGs can be selected for visualization in the spatial heatmaps.   

# Other Information  
**Data Source**   
brain_Prudencio: RNA-seq, @Prudencio2015-wd, accessed through the R package ExpressionAtlas [@ebi].   
mouse_Merkin: RNA-seq, @Merkin2012-ak, accessed through the R package ExpressionAtlas [@ebi].  
chicken_Cardoso.Moreira: RNA-seq, @Cardoso-Moreira2019-yq, accessed through the R package ExpressionAtlas [@ebi].  
shoot_Mustroph/organ_Mustroph/root_Mustroph/shootRoot_Mustroph/rootRootTip_Mustroph: microarray, @Mustroph2009-nu, accessed through the R package GEOquery [@geo].  
spatiotemporal_Narsai: RNA-seq, @Narsai2017-ql, accessed through the R package ExpressionAtlas [@ebi].  
growthStage_Mustroph: random data.  
map_Census: @US_Census_Bureau. 

**Image Source**  
brain_Prudencio/mouse_Merkin/chicken_Cardoso.Moreira: [Expression Atlas-EMBL-EBI](https://github.com/ebi-gene-expression-group/anatomogram/tree/master/src/svg){target='_blank'}  
shoot_Mustroph/organ_Mustroph/root_Mustroph/shootRoot_Mustroph/rootRootTip_Mustroph/growthStage_Mustroph: @Merkin2012-ak.  
spatiotemporal_Narsai: @Narsai2017-ql.   
map_Census: @Trip8.Co.    

**Fund source** This project has been funded by NSF awards: PGRP-1546879, PGRP-1810468, PGRP-1936492.  

# Reference







