Skip to main content

Create Single Track Visualization

This tutorial will guide you step by step in writing the JSON specification to create an interactive cytoband visualization in Gosling. You will learn about:

You are encouraged to follow the tutorial, interact with the Gosling visualizations, and modify the visualizations yourself.

Loading Data​

In this tutorial, we use a CSV data that contains UCSC hg38 cytoband information (the complete data file).

ChromosomechromStartchromEndNameStain
chr102300000p36.33gneg
chr123000005300000p36.32gpos25
chr15300000770000p36.31gneg
...

To start with, we load this data through URL to a visualization (i.e., a track). The track.data property specifies how to fetch and process the data.

{
    "tracks":[{
        // Load a csv data file through URL
        "data": {
            "url": "https://raw.githubusercontent.com/sehilyi/gemini-datasets/master/data/UCSC.HG38.Human.CytoBandIdeogram.csv",
            "chromosomeField": "Chromosome",
            "type": "csv",
            "genomicFields": ["chromStart", "chromEnd"]
        }
    }]
}

Encoding Data with Marks​

After loading the data, we now specify how to visualize the data. This process is achieved by binding the values of data fields to the visual channels (e.g., color, size) of a graphic element (i.e., mark).

Let's say we use a rect mark for the loaded csv data. Each rect represents a chromosome. The x-coordinate of the mark's start (x) and end (xe) position indicate the chromStart and the chromeEnd, respectively. The color indicates the stain value.

For each visual channel, Gosling creates a mapping from the values of the data field (e.g., [gnes, gpos25, gpos50, ...]) to the values of the visual channel (e.g., color). We call the values of data field domain and the values of the visual channel range. This mapping is specified by the following properties:

visual channel propertiestypedescription
fieldstringspecify name of the data field
typestringspecify type of the data field. support "genomic", "nominal", "quantitative"
domain[number, number]| string[]specify values of the data field
range[number, number]| string[]specify values of the visual channel
The fallback content to display on prerendering

You have just created a scalable and interactive visualization in Gosling! 🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉
You can interact with the visualization you just created in the online editor through zoom and pan. Or, you can keep reading the tutorial and make your visualizations even more fancy.

Transforming Data​

Gosling supports filtering out uninterested data through the dataTransform property. For example, we can add a filter to only visualize chromosomes whose stain result is one of "gpos25", "gpos50", "gpos75", or "gpos100".

The fallback content to display on prerendering

gvar (purple rect) and gneg (white rect) are not shown in the updated visualization.

Overlaying Multiple Marks​

Multiple mark shapes can be put on the top of one another by setting alignment as "overlay". In the code below, a chromosome is visualized as a triangleRight mark if its stain result is acen and its name includes q; a chromosome is visualized as a triangleLeft mark if its stain result is acen and its name includes p. The rect mark, the triangleRight mark, and the triangleLeft mark are overlaid on the same genomic coordinate by setting alignment as "overlay".

The fallback content to display on prerendering