# 5.2 HiGlass
## iGlass
1. Distinguished features
2. Get Started
2.1. Concept1: Anatomy of HiGlass view board
2.2. Concept2: Track types
[HiGlass](http://higlass.io) is a web-based tool for exploring genomic contact matrices and tracks.HiGlass is a viewer for HiC and other genomic data. It can be used online or run locally with private data(docker). It uses a client-server architecture to allow users to view large contact matrices in a web browser. [Publication](https://www.biorxiv.org/content/early/2017/10/30/121889)
## Distinguished features
* smooth navigation, continuous interface
* multiple datasets, map link, auto sync, optional sync(by loc or zoom)
* various representations (horizontal triangular, vertical triangular, 2D heatmap, 1D track)
* highly configurable
* diff scale of data (linear, log)
* export (SVG, JSON config) with metadata rather than lengthy url records everything
* share data local net or publicly
* locally or web databased
## Get Started
We will unfold the main features of Higlass as follows: 1. Show anatomy of HiGlass **view** board. 2. Show the category of **tracks** which represents multi-omics data. 3. Show how to upload your **own** datasets, which is the most important part.
Just a reminder, all the information illustrated here can be learned from: [\[1\]](https://github.com/hms-dbmi/higlass/wiki) [\[2\]](https://hms-dbmi.github.io/hic-data-analysis-bootcamp) We're trying our best to walk you through the gist of this software within the least of your time by our understanding and reorganized materials :D
### Concept1: Anatomy of HiGlass view board
"Tracks" and "Views" are the two most basic ingredients of a Higlass view. Each view is composed of a set of tracks which share common axes. All view operations can be found [here](https://github.com/hms-dbmi/higlass/wiki/View-Operations).
* A **view** is simply the area with a gray bar at the top. A view can be understood as a canvas, and **tracks** are figures on this canvas. There is nothing else. **Tracks** are of various types and will be elaborated later.
**Operations for Views includes:**
**a) Resize views before adding(copying) new views.**
We want to create four views in total showing two different data sets. To start, we'll resize the current view and replicate it twice
**b) Cross-view operations**
transferring or linking parameters (such as **scaling factor** and **location**) between two separate views. Examples: Let's make sure the top two rows and the bottom two rows always show the same locations as each other.
**c) View synchronization**
location or zoom or both(just for two views at a time, if you want to sync many views, you have to do it pair by pair).
**d) Go to interesting location**
**e) Project viewport**
**f) Unclock and close**
### Concept2: Track types
**Common feeatures for every track:**
* Label (Positions, color, opacity, background color).
* Color mmap:from matplotlib or custom [defined](https://github.com/hms-dbmi/higlass/wiki/Rectangular-heatmap). **Configure Series --> Color map.**
* Zoom limit.
**Different tracks( Icon | Higlass-wiki | Special-features):**
| [](https://github.com/hms-dbmi/higlass/wiki/Rectangular-heatmap) | [Rectangular heatmap](https://github.com/hms-dbmi/higlass/wiki/Rectangular-heatmap) | Transforms(ICE,KR,etc)-see Chap3.2Value scaling(linear,log)Zoom limit(5k-20M) |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [](https://github.com/hms-dbmi/higlass/wiki/Horizontal-and-vertical-heatmaps) | [Horizontal and vertical heatmaps](https://github.com/hms-dbmi/higlass/wiki/Horizontal-and-vertical-heatmaps) | 45° roatate of 2D heatmapCan be added lef,right,top,bottomDefault faces: down & right(can be fpliiped) |
| [](https://github.com/hms-dbmi/higlass/wiki/Line-tracks) | [Line](https://github.com/hms-dbmi/higlass/wiki/Line-tracks) | Scaling(linear,log)Label positionAxis positionStroke color |
| [](https://github.com/hms-dbmi/higlass/wiki/Chromosome-grid) | [Chromosome grid](https://github.com/hms-dbmi/higlass/wiki/Chromosome-grid) | Grid on chromosome scaleUser can define the scale |
| [](https://github.com/hms-dbmi/higlass/wiki/Chromosome-axis) | [Chromosome axis](https://github.com/hms-dbmi/higlass/wiki/Chromosome-axis) | Diff scale for zoom in\&outUser can define the scale |
| [](https://github.com/hms-dbmi/higlass/wiki/Viewport-projection) | [Viewport projection](https://github.com/hms-dbmi/higlass/wiki/Viewport-projection) | show one dataset with two different resolutionsOpen from view |
| [](https://github.com/hms-dbmi/higlass/wiki/Gene-annotations) | [Gene annotations](https://github.com/hms-dbmi/higlass/wiki/Gene-annotations) | [Developer docs](https://github.com/hms-dbmi/clodius/wiki/Gene-annotations) |
#### Upload your own data
In most cases, people would like to upload their own data for different tracks. To embed your own data and present them on your own browser, you should follow these steps.
* Download docker
* Install python package: cooler and clodius
* Capsule your data into docker container
**Install docker:**
[Docker](https://www.docker.com) is a computer program that performs operating-system-level virtualization also known as containerization. It resembles VM in some ways but much thinner. Instead of virtualizing hardware, containers rest on top of a single Linux instance. This means you can leave behind the useless elements, leaving you with a small, neat capsule containing your application. Higlass also embrace docker.
To **install** docker, you can first download and install it on your local machine or server [docker CE](https://www.docker.com/community-edition)(community edition). Win and Mac users can directly use it by openning it. Linux users need to start the service by running the following command with root privileges.
```
service docker start
```
**Install & Run higlass container**
Next, **pull down** the higlass-container from higlass-docker repository [(tutorial)](https://github.com/hms-dbmi/higlass-docker). After that, you can try to create an instance on that container and open your own higlass website in your own browser [(tutorial)](https://github.com/hms-dbmi/higlass/wiki#processing-and-importing-data). However, you may get confused about some commands if you're new to Docker. To solve this, you can refer to [docker's docs](https://docs.docker.com/engine/reference/commandline/docker/) or to make life easier: [Docker cheat sheet](https://www.docker.com/sites/default/files/Docker_CheatSheet_08.09.2016_0.pdf).
```
docker pull gehlenborglab/higlass
# If no version tag is specified, docker will download the latest.
```
One important thing is that you can not change parameters of an already setup container, you have to stop it first, remove that and create a new one. This also suggests that we'd better not put your data into a container, instead, we store the data locally and map it to a different container by `docker --run -volume`.
```
docker stop higlass-container
docker rm higlass-container
docker run --detach \ # start the container background, it will last until you rm your container
--publish 8888:80 \ # map a container’s port(80) to the host(8880) so that you can visit it with localhost:8888
--volume ~/hg-data:/data \ # map local data dir ~/hg-data to container dir /data
--volume ~/hg-tmp:/tmp \
--name higlass-container \ # name of your container
gehlenborglab/higlass
```
Here you go, if you intsall docker on your own computer then you can visit your higlass by `localhost:8888.com`. If you install docker on a server with IP:AA:BBB:CC:DD, then with url `AA:BBB:CC:DD:8888` you can see your own viewer on your browser.
**Create your own tracks data**
You can use your own data to substitute tracks with specific format and datatype. Refer to [here](https://github.com/hms-dbmi/higlass/wiki#processing-and-importing-data) for more details.
| Tracks | Tools | Filetype |
| --------------- | ------- | ---------------- |
| Contact matrix | cooler | cool |
| Line | clodius | BigWig\bedGraphs |
| TAD annotation | clodius | bed-like |
| Gene annotation | clodius | bed-like |
**Tools: Cooler**
[Cooler](https://pypi.org/project/cooler/) is a support library for a sparse, compressed, binary persistent storage format, called cool, used to store genomic interaction data, such as Hi-C contact matrices. To get started you can try this [walkthrough](https://github.com/mirnylab/cooler-binder/blob/master/cooler_cli.ipynb). Basically, this tool includes some useful functions listed below (not all included).
* Do contact matrix balancing
* Create and load contact matrix
* generate zoom levels for Higlass viewer
* Display a contact matrix
* ...