Indexed FASTA Sequence Track

This example shows how to render reference bases from an indexed FASTA file. GenomeSpy fetches sequence chunks only for the visible genomic region, splits the sequence into individual bases, and draws each nucleotide as a colored rectangle with a text label.

{
  "description": [
    "Indexed FASTA Sequence Track",
    "Shows reference bases from an indexed UCSC hg38 FASTA by loading visible sequence chunks, splitting them into base-level rows, and drawing colored nucleotide labels.",
    "Data source: UCSC hg38 / GRCh38 reference FASTA (`goldenPath/hg38/bigZips/latest/hg38.fa.gz`). Terms: UCSC downloadable data files are freely reusable."
  ],

  "assembly": "hg38",

  "data": {
    "lazy": {
      "type": "indexedFasta",
      "url": "https://data.genomespy.app/genomes/hg38/hg38.fa"
    }
  },

  "transform": [
    {
      "type": "flattenSequence",
      "field": "sequence",
      "as": ["rawPos", "base"]
    },
    { "type": "formula", "expr": "datum.rawPos + datum.start", "as": "pos" }
  ],

  "scales": {
    "x": {
      "domain": [
        { "chrom": "chr7", "pos": 20003500 },
        { "chrom": "chr7", "pos": 20003540 }
      ]
    }
  },

  "encoding": {
    "x": {
      "chrom": "chrom",
      "pos": "pos",
      "type": "locus"
    },
    "color": {
      "field": "base",
      "type": "nominal",
      "scale": {
        "domain": ["A", "C", "T", "G", "a", "c", "t", "g", "N"],
        "range": [
          "#7BD56C",
          "#FF9B9B",
          "#86BBF1",
          "#FFC56C",
          "#7BD56C",
          "#FF9B9B",
          "#86BBF1",
          "#FFC56C",
          "#E0E0E0"
        ]
      }
    }
  },

  "layer": [
    { "mark": "rect" },
    {
      "mark": {
        "type": "text",
        "size": 13,
        "fitToBand": true,
        "paddingX": 1.5,
        "paddingY": 1,
        "opacity": 0.7,
        "flushX": false,
        "tooltip": null
      },
      "encoding": {
        "color": { "value": "black" },
        "text": { "field": "base" }
      }
    }
  ]
}

The visualization uses a mirrored, indexed copy of UCSC's hg38 / GRCh38 reference FASTA from goldenPath/hg38/bigZips/latest/hg38.fa.gz. UCSC states that its downloadable data files and database tables are freely available for public and commercial use, subject to any upstream restrictions noted for the original assembly data.

What to notice

The example is zoomed to a short chr7 interval so individual bases fit on the screen. The indexedFasta source returns sequence chunks with chromosome, start, and sequence fields. The spec then expands each chunk into base-level rows and computes each base-pair position before encoding the result on a locus scale.

The rectangle layer provides a compact color-coded sequence overview, while the text layer uses ranged text to fit the base letters inside the rectangles at close zoom levels. Both layers use the same base-level rows, keeping labels and colored cells aligned during pan and zoom.

GenomeSpy Features

This example combines several GenomeSpy capabilities in one compact track:

• Lazy data sources load reference sequence only for the visible region.
• flattenSequence expands each FASTA sequence chunk into one row per base.
• formula converts chunk-relative base offsets into genomic positions.
• The locus scale places bases by chromosome and position.
• layer combines nucleotide rectangles with readable base labels.
• text uses ranged placement to fit nucleotide letters inside each base-pair rectangle.