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.

Read labels

Read labels display per-read text annotations directly on the pileup track. Labels are rendered with intelligent collision detection so that only non-overlapping labels are shown; when space is limited, labels with higher importance (determined by a stable hash of the read ID) are kept visible.

readLabels - Controls which fields are shown in the label. Set to an object with fields and separator keys to enable labels, or null to disable (default).

Available fields: id, pos, strand, mapq, readName, or any custom field present on the read object.

"readLabels": {
  "fields": ["readName", "mapq"],
  "separator": " | "
}

readLabelPosition - Where the label text is anchored relative to the read body. One of "left", "center" (default), or "right".

• "left" — label starts at the left edge of the read
• "center" — label is centred over the read (default)
• "right" — label ends at the right edge of the read

maxReadLabels - Maximum number of labels shown at once (default: 200). Lowering this improves performance in dense regions.

readLabelFontSize - Font size in pixels (default: 10).

readLabelFontFamily - Font family (default: "Arial").

readLabelColor - Label text color as a hex integer (default: 0x333333).

readLabelStrokeColor - Color of the text outline, which improves legibility over reads (default: 0xffffff).

readLabelStrokeThickness - Thickness of the text outline in pixels (default: 2).

Full example with all label options:

"options": {
  "readLabels": {
    "fields": ["readName", "pos", "strand", "mapq"],
    "separator": " "
  },
  "readLabelPosition": "left",
  "maxReadLabels": 100,
  "readLabelFontSize": 10,
  "readLabelFontFamily": "Arial",
  "readLabelColor": 3355443,
  "readLabelStrokeColor": 16777215,
  "readLabelStrokeThickness": 2
}

Click Handler API

The pileup track automatically publishes click events with detailed read information. You can subscribe to these events to implement custom click interactions.

Subscribing to Click Events (Recommended)

The easiest way to handle clicks is to subscribe to the app.trackClick event published by the track:

// Get the HiGlass viewer and track reference
const hgv = hglib.viewer(element, viewConfig);

// Wait for track to initialize, then subscribe to click events
setTimeout(() => {
  const track = hgv.getTrackObject(viewId, trackId);
  
  if (track && track.pubSub) {
    track.pubSub.subscribe('app.trackClick', (eventData) => {
      console.log('Genomic position:', eventData.data.genomicPosition);
      console.log('Chromosome position:', eventData.data.chrPosition);
      
      if (eventData.data.read) {
        console.log('Read ID:', eventData.data.read.id);
        console.log('Position:', eventData.data.read.from, '->', eventData.data.read.to);
        console.log('MAPQ:', eventData.data.read.mapq);
        console.log('Strand:', eventData.data.read.strand);
        
        // Access substitutions
        if (eventData.data.substitution) {
          console.log('Substitution type:', eventData.data.substitution.type);
          console.log('Substitution position:', eventData.data.substitution.pos);
        }
        
        // Access extra BAM fields
        if (eventData.data.read.extra) {
          console.log('Extra fields:', eventData.data.read.extra);
        }
      }
    });
  }
}, 1000);

Event Data Structure

The app.trackClick event provides an object with the following structure:

{
  trackId: 'track-id',        // Track identifier
  trackUid: 'track-id',       // Track unique identifier
  viewId: 'view-id',          // View identifier
  viewUid: 'view-id',         // View unique identifier
  data: {
    genomicPosition: 123456,  // Genomic coordinate (number)
    chrPosition: ['chr1', 123456],  // [chromosome name, position]
    read: {                   // Full read object (null if no read at click position)
      id: 'read-id',
      from: 123000,
      to: 123500,
      mapq: 60,
      strand: '+',
      row: 5,
      groupKey: 'group-key',
      chrName: 'chr1',        // If available
      chrOffset: 0,           // If available
      substitutions: [...],   // Array of all substitutions in read
      mate_ids: [...],        // Mate read IDs for paired-end reads
      extra: {...}            // Additional BAM tags
    },
    substitution: {           // Nearest substitution within 10px (null if none)
      type: 'X',              // 'X'=mismatch, 'D'=deletion, 'I'=insertion, 'S'=soft clip, 'H'=hard clip
      pos: 45,                // Position relative to read start
      length: 1,
      base: 'A',              // Reference base (for mismatches)
      variant: 'T'            // Variant base (for mismatches)
    }
  }
}

Using getMouse Directly (Advanced)

You can also call the getMouse method directly for more control:

// Get a reference to the track
const track = hgv.getTrackObject(viewId, trackId);

// Call getMouse with track coordinates
track.getMouse(trackX, trackY, (result) => {
  console.log('Genomic position:', result.genomicPosition);
  if (result.read) {
    console.log('Read ID:', result.read.id);
    // ... process read and substitution data
  }
});

Method Signature

getMouse(trackX, trackY, callback)

Parameters:

• trackX (number): X coordinate in track space
• trackY (number): Y coordinate in track space
• callback (function, optional): Callback function that receives the result object with read data

Returns: An object with genomic and chromosome position (synchronous). If a callback is provided, it will be called with the complete result including read and substitution data.

Return Value

The getMouse method returns an object immediately with position data, and optionally calls the callback with the full result:

• genomicPosition (number): The genomic coordinate at the click position
• chrPosition (array): The chromosome position as [chromosomeName, position]
• read (object | null): Full read information if a read is under the cursor, or null if none
• substitution (object | null): Substitution information if one is under the cursor (within 10px), or null if none

Note: Since read data may need to be fetched asynchronously from a worker thread, the callback pattern ensures you always receive the complete data. If the data is cached (e.g., from a recent hover), the callback is called immediately.

Example

// Using callback pattern (recommended)
track.getMouse(trackX, trackY, (result) => {
  console.log('Genomic position:', result.genomicPosition);
  console.log('Chromosome position:', result.chrPosition);
  
  if (result.read) {
    console.log('Read ID:', result.read.id);
    console.log('Read position:', result.read.from, '-', result.read.to);
    console.log('MAPQ:', result.read.mapq);
    console.log('Strand:', result.read.strand);
    
    if (result.substitution) {
      console.log('Nearest substitution type:', result.substitution.type);
      console.log('Substitution position:', result.substitution.pos);
      if (result.substitution.variant) {
        console.log('Base change:', result.substitution.base, '->', result.substitution.variant);
      }
    }
  }
});

// Immediate return value (position only, read data populated asynchronously)
const immediate = track.getMouse(trackX, trackY);
console.log('Position:', immediate.genomicPosition); // Available immediately
console.log('Read:', immediate.read); // May be null until async fetch completes

Read Object Properties

When a read is present, the read object contains:

• id: Read identifier
• from: Start genomic position
• to: End genomic position
• mapq: Mapping quality score
• strand: Read strand ('+' or '-')
• row: Visual row the read is displayed on
• groupKey: Group identifier
• chrName: Chromosome name (if available)
• chrOffset: Chromosome offset (if available)
• substitutions: Array of substitution objects
• mate_ids: Array of mate read IDs (for paired-end reads)
• extra: Additional BAM tags and fields

Substitution Object Properties

When a substitution is present, the substitution object contains:

• pos: Position relative to read start
• type: Substitution type ('X' for mismatch, 'D' for deletion, 'I' for insertion, 'S' for soft clip, 'H' for hard clip)
• length: Length of the substitution
• base: Reference base (for mismatches)
• variant: Variant base (for mismatches)

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