Genomic Coordinates

To allow easy visualization of coordinate-based genomic data, GenomeSpy can concatenate the discrete chromosomes onto a single continuous linear axis. Concatenation needs the sizes and preferred order for the contigs or chromosomes. These are usually provided with a genome assembly.

To activate support for genomic coordinates, add the genome property with the name of the assembly to the top level view specification:

{
  "genome": {
    "name": "hg38"
  },
  ...
}

Only a single genome assembly

Currently, a visualization may have only a single globally configured genome assembly. Different assemblies for different scales (for x and y axes, for example) will be supported in the future.

Supported genomes

By default, GenomeSpy loads genomes from the genomespy.app website. The following assemblies are provided: "hg38", "hg19", "hg18", "mm10", "mm9", and "dm6".

Custom genomes

At minimum, a custom genome needs a list of contigs and their sizes, which can be loaded from a "chrom.sizes" file or provided inline. Cytoband and Gene annotation tracks require additional files.

As files

The baseUrl property specifies the location of genomes:

{
  "genome": {
    "name": "hg99",
    "baseUrl": "https://your.site/genomes/"
  },
  ...
}

The directory must have the following structure:

hg99/hg99.chrom.sizes
hg99/cytoBand.hg99.txt (optional)
hg99/refSeq_genes_scored_compressed.hg99.txt (optional)

Inline

Example:

{
  "genome": {
    "contigs": [
      {"name": "chr3R", "size": 32079331 },
      {"name": "chr3L", "size": 28110227 },
      {"name": "chr2R", "size": 25286936 },
      {"name": "chrX",  "size": 23542271 },
      {"name": "chr2L", "size": 23513712 },
      {"name": "chrY",  "size": 3667352 },
      {"name": "chr4",  "size": 1348131 },
    ]
  },
  ...
}

Cytobands and genome annotations cannot be provided inline.

Encoding genomic coordinates

When a genome assembly has been specified, you can encode the genomic coordinates conveniently by specifying the chromosome (chrom) and position (pos) fields as follows:

{
  ...,
  "encoding": {
    "x": {
      "chrom": "Chr",
      "pos": "Pos",
      "offset": -1.0,
      "type": "locus"
    },
    ...
  }
}

The example above specifies that the chromosome is read from the "Chr" field and the intra-chromosomal position from the "Pos" field. The "locus" data type pairs the channel with a "locus" scale, which provides a chromosome-aware axis. However, you can also use the field property with the locus data type if the coordinate has already been linearized. The offset property is explained below.

What happens under the hood

When the chrom and pos properties are used used in channel definitions, GenomeSpy inserts an implicit linearizeGenomicCoordinate transformation into the data flow. The transformation introduces a new field with the linearized coordinate for the (chromosome, position) pair. The channel definition is modified to use the new field.

In some cases you may want to insert an explicit transformation to the data flow to have better control on its behavior.

Coordinate counting

The offset property allows for aligning and adjusting for different coordinate notations: zero or one based, closed or half-open. The offset is added to the final coordinate.

GenomeSpy's "locus" scale expects half-open, zero-based coordinates.

Read more about coordinates at the UCSC Genome Browser Blog.

Examples

Point features

{
  "genome": { "name": "hg38" },
  "data": {
    "values": [
      { "chrom": "chr3", "pos": 134567890 },
      { "chrom": "chr4", "pos": 123456789 },
      { "chrom": "chr9", "pos": 34567890 }
    ]
  },
  "mark": "point",
  "encoding": {
    "x": {
      "chrom": "chrom",
      "pos": "pos",
      "type": "locus"
    }
  }
}

Segment features

{
  "genome": { "name": "hg38" },
  "data": {
    "values": [
      { "chrom": "chr3", "startpos": 100000000, "endpos": 140000000 },
      { "chrom": "chr4", "startpos": 70000000, "endpos": 170000000 },
      { "chrom": "chr9", "startpos": 50000000, "endpos": 70000000 }
    ]
  },
  "mark": "rect",
  "encoding": {
    "x": {
      "chrom": "chrom",
      "pos": "startpos",
      "type": "locus"
    },
    "x2": {
      "chrom": "chrom",
      "pos": "endpos"
    }
  }
}