View Configs

Viewconfs specify exactly what a HiGlass view should show. They contain a list of the data sources, visualization types, visible region as well as searching and styling options.

Show a specific genomic location

Say we want to have a viewconf which was centered on the gene OSR1. Its location is roughly between positions 19,500,000 and 19,600,000 on chromosome 7 of the hg19 assembly. So what should initialXDomain be set to in order to show this gene?

Because initialXDomain accepts absolute coordinates calculated by concatenating chromosomes according to a certain order, we need to calculate what chr2:19,500,000 and chr2:196,000,000 are in absolute coordinates.

To do this we will assume a chromosome ordering consisting of chr1, chr2, … This means that we need to take the length of chr1 in hg19, which is 249,250,621 base pairs, and add our positions to that, yielding positions 268,750,621 and 268,850,621 for the initialXDomain.

The chromosome order commonly used in HiGlass for hg19 can be found in the negspy repository.

Upload a viewconf to the server

A local viewconf can be sent to the server by sending a POST request. Make sure the actual viewconf is wrapped in the viewconf section of the posted json (e.g. {“viewconf”: myViewConfig}):

curl -H "Content-Type: application/json" \
     -X POST \
     -d '{"viewconf": {"editable": true, "zoomFixed": false, "trackSourceServers": ["/api/v2", "http://higlass.io/api/v1"], "exportViewUrl": "/api/v1/viewconfs/", "views": [{"tracks": {"top": [], "left": [], "center": [], "right": [], "bottom": []}, "initialXDomain": [243883495.14563107, 2956116504.854369], "initialYDomain": [804660194.1747572, 2395339805.825243], "layout": {"w": 12, "h": 12, "x": 0, "y": 0, "i": "EwiSznw8ST2HF3CjHx-tCg", "moved": false, "static": false}, "uid": "EwiSznw8ST2HF3CjHx-tCg"}], "zoomLocks": {"locksByViewUid": {}, "locksDict": {}}, "locationLocks": {"locksByViewUid": {}, "locksDict": {}}, "valueScaleLocks": {"locksByViewUid": {}, "locksDict": {}}}}' http://localhost:8989/api/v1/viewconfs/

Genome Position Search Box

The genome position search box section a view config is specific to each view. It is used to search for locations in the view. The full configuration has a pointer to a chromSizes file and an autocomplete source which will provide suggestions for gene names. The autocomplete source should point to a gene-annotations file.

UIDs

UID stands for unique identifier. Every view and track in the higlass view config has a UID. If it’s not specified in the viewconfig it’s randomly generated by the client when the view is created.

initialXDomain and initialYDomain

The fields contain the initial coordinates which are displayed when HiGlass first loads the viewconfig. If the initialYDomain is not present, it is set to equal the initialXDomain. If that isn’t present either, both are assigned values of [0,1]].

{
    views: [
        {
              "uid": "AhI0wMP6ScybnFp6BmLuPQ",
              "initialXDomain": [
                973907089.1176914,
                1196247735.9596405
              ],
              "initialYDomain": [
                -12281154450.083118,
                -12145323104.213125
              ],
            "genomePositionSearchBox": {
                "autocompleteServer": "http://higlass.io/api/v1",
                "autocompleteId": "OHJakQICQD6gTD7skx4EWA",
                "chromInfoServer": "http://higlass.io/api/v1",
                "chromInfoId": "hg19",
                "visible": true
            }
    ]
}

trackSourceServers

The field trackSourceServers at the root level of the viewconf tells higlass where it can find tracks to load. If you have a local instance running, then http://localhost/api/v1 should be included. Our public instance at http://higlass.io also provides access to a number of public datasets.

{
  "trackSourceServers": [
    "http://higlass.io/api/v1",
    "http://localhost:8989/api/v1"
  ],
}

exportViewUrl

The exportViewUrl field in the viewconf specifies which server should be used to store exported viewconfs. This server stores exported viewconfs in its database, assigns them a uid, and makes them accessible through its API at /api/v1/viewconfs/uid/.

{
    "exportViewUrl": "/api/v1/viewconfs",
}

Tracks

Tracks can be placed into four distinct areas: top, bottom, left, right or center. The location of the track determines what type of data can be shown in it. Center tracks are used to show data that can be zoomed along two axes. Horizontal (top, bottom) and vertical (left, right) are used to show data that can be zoomed along a single axis.

Each set of tracks is placed within a view.

{
  "views": [
    {
      "tracks": {
        "top": [],
        "left": [],
        "center": [],
        "bottom": [],
        "right": []
      },
    }
  ],
}

Track options

Each track can specify a set of options defining how it will be drawn. Some of the more important ones are:

• valueScaleMin and valueScaleMax: control the minimum and maximum values rendered by the track. If either is not defined, then it will be set according to the visible data (i.e. the minimum value of the scale will be the minimum value in the visible data and the same for the maximum)