Chromosome Ideogram from Cytobands

This example shows a chromosome ideogram built from UCSC cytoband data. The rectangles encode band intervals and staining categories, the labels use ranged text to squeeze band names into the available space, and dashed separators mark chromosome boundaries.

The spec loads UCSC's gzipped cytoband file directly. Because the file has no header line, the TSV columns are declared explicitly.

{
  "description": [
    "Chromosome Ideogram from Cytobands",
    "Shows a compact hg38 ideogram built from UCSC cytoband intervals with layered rectangles, ranged band labels, and dashed chromosome separators.",
    "Data source: mirrored copy of UCSC's hg38 cytoBand track (`cytoBand.txt.gz`). UCSC states that its downloadable data files and database tables are freely available for public and commercial use."
  ],

  "assembly": "hg38",

  "name": "ideogram-track",

  "view": { "stroke": "black" },

  "height": 24,

  "data": {
    "url": "https://data.genomespy.app/genomes/hg38/cytoBand.txt.gz",
    "format": {
      "type": "tsv",
      "columns": ["chrom", "chromStart", "chromEnd", "name", "gieStain"]
    }
  },

  "transform": [{ "type": "filter", "expr": "!test(/_/, datum.chrom)" }],

  "encoding": {
    "x": {
      "chrom": "chrom",
      "pos": "chromStart",
      "type": "locus"
    },
    "x2": { "chrom": "chrom", "pos": "chromEnd" }
  },

  "resolve": { "scale": { "color": "independent" } },

  "layer": [
    {
      "title": "Cytoband",
      "mark": "rect",
      "encoding": {
        "color": {
          "field": "gieStain",
          "type": "nominal",
          "scale": {
            "domain": [
              "gneg",
              "gpos25",
              "gpos50",
              "gpos75",
              "gpos100",
              "acen",
              "stalk",
              "gvar"
            ],
            "range": [
              "#f0f0f0",
              "#e0e0e0",
              "#d0d0d0",
              "#c0c0c0",
              "#a0a0a0",
              "#cc4444",
              "#338833",
              "#000000"
            ]
          },
          "legend": null
        }
      }
    },
    {
      "mark": {
        "type": "text",
        "align": "center",
        "baseline": "middle",
        "paddingX": 4,
        "tooltip": null
      },
      "encoding": {
        "color": {
          "field": "gieStain",
          "type": "nominal",
          "scale": {
            "domain": [
              "gneg",
              "gpos25",
              "gpos50",
              "gpos75",
              "gpos100",
              "acen",
              "stalk",
              "gvar"
            ],
            "range": [
              "black",
              "black",
              "black",
              "black",
              "black",
              "black",
              "white",
              "white"
            ]
          },
          "legend": null
        },
        "text": {
          "field": "name",
          "type": "nominal"
        }
      }
    },
    {
      "transform": [
        {
          "type": "filter",
          "expr": "datum.chromStart == 0 && datum.chrom != 'chr1'"
        }
      ],
      "encoding": {
        "x2": null
      },
      "mark": {
        "type": "rule",
        "color": "#a0a0a0",
        "strokeDash": [3, 3],
        "strokeDashOffset": 2
      }
    }
  ]
}

The visualization uses a mirrored copy of UCSC's hg38 cytoband track, distributed as cytoBand.txt.gz. UCSC states that its downloadable data files and database tables are freely available for public and commercial use.

What to notice

The ideogram has three layers:

• Background rectangles for cytobands
• Text labels for band names
• Dashed rules between chromosomes

The cytoband labels inherit the same genomic intervals as the rectangles, so GenomeSpy can hide labels that do not fit in the available width. A filter removes unlocalized and unplaced scaffolds so the track stays focused on primary chromosomes.

Data and Encoding

The cytoband file contains one row per band with chromosome, start, end, band name, and gieStain category. The genomic interval is encoded with x and x2, and the same interval is reused by both the rectangle and text layers. This keeps the band shape and label placement aligned during pan and zoom.

The gieStain field drives the band colors. The rectangle layer maps staining categories to grayscale, red centromere, green stalk, and black variable regions. The text layer uses a separate color scale for the same categories so labels stay readable on dark bands.

GenomeSpy Features

This example combines several GenomeSpy capabilities in one compact track:

• The locus scale maps chromosome names and base-pair positions onto a continuous genomic axis.
• layer combines the cytoband rectangles, labels, and chromosome separators.
• text labels use ranged text placement because they inherit both x and x2.
• filter removes scaffolds whose names contain underscores.
• Independent color scales let the background rectangles and foreground labels use different color ranges for the same gieStain categories.