HiGlass Pileup Track

Viewer for sequence alignments.

Note: This is the source code for the pileup only! You might want to check out the following repositories as well:

• HiGlass viewer: https://github.com/higlass/higlass
• HiGlass server: https://github.com/higlass/higlass-server
• HiGlass docker: https://github.com/higlass/higlass-docker

Installation

npm install higlass-pileup

Usage

The live scripts can be found at:

• https://unpkg.com/higlass-pileup/dist/higlass-pileup.min.js

Things that haven't been thoroughly tested

1. Group by strand when using single vs. paired end reads
2. Group by HP tag when using single vs. paired end reads

Client

1. Make sure you load this track prior to hglib.js. For example:

<script src="/higlass-pileup-track.js"></script>
<script src="hglib.js"></script>
<script>
  ...
</script>

2. Now, configure the track in your view config and be happy!

{
  "editable": true,
  "trackSourceServers": [
    "http://higlass.io/api/v1"
  ],
  "exportViewUrl": "/api/v1/viewconfs",
  "views": [
    {
      "initialXDomain": [
        0,
        100000
      ],
      "tracks": {
        "top": [
          {
            "type": "pileup",
            "options": {
              "axisPositionHorizontal": "right",
              "axisLabelFormatting": "normal",
              "showCoverage": false,
              "colorScale": [
                // A T G C N Other
                "#2c7bb6",
                "#92c5de",
                "#ffffbf",
                "#fdae61",
                "#808080",
                "#DCDCDC"
              ]
            },
            "height": 180,
            "uid": "FylkvVBTSumoJ959HT4-5A",
            "data": {
              "type": "bam",
              "bamUrl": "https://pkerp.s3.amazonaws.com/public/bamfile_test/SRR1770413.sorted.bam",
              "baiUrl": "https://pkerp.s3.amazonaws.com/public/bamfile_test/SRR1770413.sorted.bam.bai",
              "chromSizesUrl": "https://pkerp.s3.amazonaws.com/public/bamfile_test/GCF_000005845.2_ASM584v2_genomic.chrom.sizes",
              {
                "options": {
                  "maxTileWidth": 30000
                }
              }
            },
            "width": 470
          }
        ]
      },
      "layout": {
        "w": 12,
        "h": 6,
        "x": 0,
        "y": 0
      }
    }
  ]
}

3. To use in higlass.io:

• Modify the viewconf above to specify the URL for your BAM file.
• Either remove or update the chromSizesUrl entry to point to a chromosome sizes file for the assembly that your BAM file is aligned to. If it's omitted, the chromosome sizes will be extracted directly from the BAM file and ordered best-guess semantically (i.e. chr1, chr2, ...., chrM, chrX, chrY).
• Save the viewconf as a JSON file.
• Navigate to higlass.io/app and drag the JSON file onto the viewer.
• Browse away!

Options

Data config

maxTileWidth - To limit the amount of data that is fetched from the server, HiGlass sets a default maximum tile width. This can be modified in the data section of the track config. Setting it to a large file will let you zoom out further while still fetching data. This is useful for viewing low coverage BAM files.

Track options

colorScale - Array that controls the color of substitutions and highlighted reads. It can take 6, 11, 21, or 26 values:

• 6 values: DNA bases (A, T, G, C, N, other)
• 11 values: DNA bases + highlighted read colors (see highlightReadsBy option)
• 21 values: Protein amino acids (ALA, ARG, ASN, ASP, CYS, GLN, GLU, GLY, HIS, ILE, LEU, LYS, MET, PHE, PRO, SER, THR, TRP, TYR, VAL, STOP)
• 26 values: Protein amino acids + highlighted read colors

DNA example:

"colorScale": [
  "#2c7bb6", //color of A substitutions
  "#92c5de", //color of T substitutions
  "#ffffbf", //color of G substitutions
  "#fdae61", //color of C substitutions
  "#808080", //color of N substitutions
  "#DCDCDC", //color of other substitutions
  "#FF0000", //color of reads with large insert size
  "#0000D1", //color of reads with small insert size
  "#00D1D1", //color of reads with LL orientation
  "#555CFA", //color of reads with RR orientation
  "#02A221", //color of reads with RL orientation
]

Protein example:

"colorScale": [
  "#CCCCCC", //ALA - Alanine
  "#0000FF", //ARG - Arginine (basic)
  "#00FFFF", //ASN - Asparagine (polar)
  "#FF0000", //ASP - Aspartic acid (acidic)
  "#FFFF00", //CYS - Cysteine (sulfur)
  "#00FFFF", //GLN - Glutamine (polar)
  "#FF0000", //GLU - Glutamic acid (acidic)
  "#E6E6E6", //GLY - Glycine (small)
  "#0000FF", //HIS - Histidine (basic)
  "#00FF00", //ILE - Isoleucine (hydrophobic)
  "#00FF00", //LEU - Leucine (hydrophobic)
  "#0000FF", //LYS - Lysine (basic)
  "#00FF00", //MET - Methionine (hydrophobic)
  "#00FF00", //PHE - Phenylalanine (hydrophobic)
  "#FF8000", //PRO - Proline (special)
  "#00FFFF", //SER - Serine (polar)
  "#00FFFF", //THR - Threonine (polar)
  "#00FF00", //TRP - Tryptophan (hydrophobic)
  "#00FFFF", //TYR - Tyrosine (polar)
  "#00FF00", //VAL - Valine (hydrophobic)
  "#000000"  //STOP - Stop codon
]

outlineReadOnHover - Highlights the current read on hover.

outlineMateOnHover - Highlights the mate of the current read on hover. If the mate is a split read, both alignments will be highlighted.

highlightReadsBy - Array that can take the values insertSize, pairOrientation or insertSizeAndPairOrientation:

• if insertSize is set, reads that have a large or small insert size will be highlighted. The thresholds are controlled by the largeInsertSizeThreshold and smallInsertSizeThreshold track options. largeInsertSizeThreshold defaults to 1000, i.e., 1000 bp. smallInsertSizeThreshold is not set by default, i.e, reads with small insert size won't be highlighted.
• if pairOrientation is set, reads with an abnormal mapping orientation are highlighted (e.g. ++,--,-+).
• if insertSizeAndPairOrientation is set, reads with an abnormal mapping orientation that also have abnormal insert sizes are highlighted.
• if multiple values are set, reads that fulfill any of the conditions are highlighed in the corresponding color.
• highlight colors can be controlled by extending the colorScale track option to 11 values. The additional 5 values will control the large insert size color, small insert size color and the ++, --, -+ mapping orientations (in that order).

minMappingQuality - If this is set (integer), reads with a mapping quality lower than the specified value are not displayed.

Local tiles

The higlass-pileup track supports local tiles. Local tiles can contain either BAM formatted data or they can include raw rendering objects. The following is a snippet that goes in the track section of a viewconf:

            data: {
              type: 'local-tiles',
              tilesetInfo: {
                'min_pos': [0],
                'max_pos': [14],
                'max_width': 64,
                'tile_size': 1024,
                'chromsizes': [['a', 14]],
                'max_zoom': 0,
                'max_tile_width': 100000,
                'format': 'subs'
              },
              tiles: {
                '0.0': [{
                  "id": "r1",
                  "from": 0,
                  "to": 100,
                  "substitutions": [
                    {'pos': 2, 'type': 'D', 'length': 2},
                    {'pos': 6, 'type': 'X', 'length': 1, 'base': 'A', 'variant': 'T'},
                    {'pos': 9, 'type': 'D', 'length': 2}
                  ],
                  "color": 0
                }],
              }
            }

The currently available substitution types are:

• S - corresponding to soft clipped bases
• H - corresponding to hard clipped bases
• X - corresponding to a mismatch
• I - corresponding to an insertion
• D - corresponding to a deletion

HTTP tiles

The higlass-pileup track supports pre-rendered tiles served over HTTP. This allows tiles to be pre-computed and hosted as static files (e.g. on S3), avoiding the need for a running HiGlass server.

data: {
  type: 'http-tiles',
  tilesetInfo: 'https://example.com/tiles/tileset_info.json',
  tiles: {
    '0.0': 'https://example.com/tiles/tile_0_0.json',
    '1.0': 'https://example.com/tiles/tile_1_0.json',
    '1.1': 'https://example.com/tiles/tile_1_1.json'
  }
}

• tilesetInfo - URL to a JSON file describing the tileset. The standard HiGlass tileset info fields are supported (max_width, tile_size, max_zoom, chromsizes, etc.). If the server returns max_pos instead of max_width, it will be normalized automatically.
• tiles - Object mapping tile IDs (e.g. "0.0", "1.3") to URLs. Each URL should point to a JSON file containing an array of read objects in the same format used by local tiles.

Both tilesetInfo and tile URLs support gzip-compressed JSON (files ending in .gz).

The tile data format is the same as for local tiles — an array of read objects:

[
  {
    "id": "read1",
    "from": 1000,
    "to": 1150,
    "row": 0,
    "substitutions": [
      { "pos": 10, "type": "X", "length": 1, "base": "A", "variant": "T" },
      { "pos": 40, "type": "D", "length": 3 }
    ],
    "color": 0
  }
]

Including a row field in each read allows the track to skip row assignment on the main thread, which significantly improves rendering performance for large datasets.

Protein Support

The pileup track now supports protein sequences with a 21-color amino acid color scale. The colors are mapped to amino acids based on their chemical properties:

• Basic amino acids (ARG, HIS, LYS): Blue
• Acidic amino acids (ASP, GLU): Red
• Polar amino acids (ASN, GLN, SER, THR, TYR): Cyan
• Hydrophobic amino acids (ILE, LEU, MET, PHE, TRP, VAL): Green
• Special amino acids (CYS, PRO): Yellow/Orange
• Small amino acids (ALA, GLY): Gray
• Stop codons: Black

Support

For questions, please either open an issue or ask on the HiGlass Slack channel at http://bit.ly/higlass-slack

Development

Installation

$ git clone https://github.com/higlass/higlass-pileup-track && higlass-pileup-track
$ npm install

Commands

Developmental server: npm start Production build: npm run build