{
"cells": [
{
"cell_type": "markdown",
"metadata": {
"id": "yY2RCWLis1Oy"
},
"source": [
"# Session 3: Semantic Zooming\n",
"This notebook demonstrates a way to use a unique primitive, i.e., **semantic zooming**, in Gosling to reveal patterns across scales.\n"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "ScTPHRO1tj4f"
},
"source": [
"## What Is \"Semantic Zooming\"?\n",
"\n",
"### _\"Allowing objects to be represented differently at different scales.\"_ ([Cockburn, Karlson, Bederson. 2006](https://doi.org/10.1145/1456650.1456652))\n",
"\n",
"A typical example of semantic zooming we find in the real world is Google Maps where you can see detailed information upon zooming in, such as store icons, names, streets.\n",
"\n",
"\n",
"\n",
"![](\"https://user-images.githubusercontent.com/9922882/175837927-cd43f7fc-c256-4e11-bf06-82d6486c4cd6.png\"/) | \n",
"![](\"https://user-images.githubusercontent.com/9922882/175837925-f0131aef-a6b0-427a-ac6b-6d60d52b67ac.png\"/) | \n",
"
\n",
"
\n",
"\n",
"_**Figure 1: Semantic Zooming in Google Maps.** The level of details is controlled by zoom levels. When zoomed in enough, more detailed information is displayed with icons, labels, etc._"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "_f8qH2aUzcuj"
},
"source": [
"## How To Use Semantic Zooming In Gosling?\n",
"\n",
"Gosling enables you to dynamically change visual representations based on the zoom levels. The following Gosling variant track, for example, shows the individual variants in detail with a lollipop representation when zoomed in. The representation dynamically switches to stacked bar charts to show overall distributions when zoomed out.\n",
"\n",
"![](\"https://user-images.githubusercontent.com/9922882/175838420-e3956bda-7132-4331-b2d0-cd8535221353.png\"/)
\n",
"\n",
"_**Figure 2: Scalable variant track in the high zoom level.** This representation shows every variants with a lollipop representation. The narrow red rectangle on the chromosome 3 ideogram indicates the genomic location shown in the variant track._\n",
"\n",
"![](\"https://user-images.githubusercontent.com/9922882/175944801-3d816dac-3875-45ea-a845-444d160bc597.png\"/)
\n",
"\n",
"_**Figure 3: Scalable variant track that switches between two representations.** The lollipop representation is smoothly transitioned into stacked bar charts. The narrow red rectangle on the chromosome 3 ideogram indicates the genomic location shown in the variant track._\n",
"\n",
"![](\"https://user-images.githubusercontent.com/9922882/175838417-63ff1a8f-ca51-4780-b395-32d2a549b129.png\"/)
\n",
"\n",
"_**Figure 4: Scalable variant track in the high zoom level.** The lollipop representation is switched to stacked bar charts, showing overall distributions. The red rectangle on the chromosome 3 ideogram indicates the genomic location shown in the variant track._\n",
"\n",
"So, how can you use semantic zooming in Gosling? You can do this by overlaying multiple tracks (here, the lollipop plot and the stacked bar chart), and determining when to show each track using a `visibility_*` property.\n",
"\n",
"```python\n",
"# define two tracks\n",
"lollipop = gos.Track(data)...\n",
"stacked_bar_chart = gos.Track(data)...\n",
"\n",
"# determine when to display each track\n",
"lollipop.visibility_lt( # lt refers to less than\n",
" measure=\"zoomLevel\",\n",
" target=\"mark\",\n",
" threshold=100000 # one hundred thousand bases\n",
")\n",
"\n",
"stacked_bar_chartbars.visibility_gt( # gt refers to greater than\n",
" measure=\"zoomLevel\",\n",
" target=\"mark\",\n",
" threshold=100000 # one hundred thousand bases\n",
")\n",
"\n",
"# overlay multiple tracks\n",
"gos.overlay(\n",
" lollipop,\n",
" stacked_bar_chart\n",
")\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "DzhKEQ0h1WGU"
},
"source": [
"More details about the options can be found at http://gosling-lang.org/docs/semantic-zoom"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "GN7tNkLa06Em"
},
"source": [
""
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "RQ-Lq_1j1CB9"
},
"source": [
""
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "gCosrvPuwc4C"
},
"source": [
"## 🧑💻 Exercises\n",
"\n",
"Let's try semantic zooming in Gosling!"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/"
},
"id": "-qQ4w8nPSLTN",
"outputId": "bae16a02-2aaf-4070-a1cb-303233719782"
},
"outputs": [],
"source": [
"!pip install gosling==0.0.9\n",
"import gosling as gos"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "Qvd9KXAvU1ND"
},
"source": [
"### Exercise 1: Text Labels in Ideogram\n",
"\n",
"Here is an ideogram track that we created in the previous session."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 227
},
"id": "NIhRuDGtQQZE",
"outputId": "b6f0ad93-8414-40fe-91ee-11da99d7e539"
},
"outputs": [],
"source": [
"# genomic position to display\n",
"xDomain = gos.GenomicDomain(chromosome=\"chr1\", interval=[80000000, 180000000])\n",
"\n",
"data = gos.csv(\n",
" url=\"https://raw.githubusercontent.com/sehilyi/gemini-datasets/master/data/UCSC.HG38.Human.CytoBandIdeogram.bed\",\n",
" headerNames=['chrom', 'chromStart', 'chromEnd', 'name', 'stain'],\n",
" chromosomeField=\"chrom\",\n",
" genomicFields=[\"chromStart\", \"chromEnd\"],\n",
" separator=\"\\t\"\n",
")\n",
"\n",
"arms = gos.Track(data).mark_rect().transform_filter_not(\n",
" \"stain\", oneOf=[\"acen\"]\n",
").encode(\n",
" # defines start and end of rectangle mark\n",
" x=gos.X(\"chromStart:G\", axis=\"top\"),\n",
" xe=gos.Xe(\"chromEnd:G\"),\n",
" # defines how to map Giemsa-stain factor to colors\n",
" color=gos.Color(\n",
" \"stain:N\", \n",
" domain=[\"gneg\", \"gpos25\", \"gpos50\", \"gpos75\", \"gpos100\", \"gvar\"],\n",
" range=[\"white\", \"#D9D9D9\", \"#979797\", \"#636363\", \"black\", \"#A0A0F2\"]\n",
" ),\n",
" # customize the style of the visual marks.\n",
" size=gos.value(20),\n",
" stroke=gos.value(\"gray\"),\n",
" strokeWidth=gos.value(0.5)\n",
")\n",
"\n",
"centromere_base = gos.Track(data).encode(\n",
" x=gos.X(\"chromStart:G\"),\n",
" xe=\"chromEnd:G\",\n",
" color=gos.value('red'),\n",
" size=gos.value(20),\n",
").transform_filter(\n",
" \"stain\", oneOf=[\"acen\"]\n",
")\n",
"\n",
"centromere_1 = centromere_base.mark_triangleLeft().transform_filter(\n",
" \"name\", include=\"p\"\n",
")\n",
"\n",
"centromere_2 = centromere_base.mark_triangleRight().transform_filter(\n",
" \"name\", include=\"q\"\n",
")\n",
"\n",
"ideogram = gos.overlay(arms, centromere_1, centromere_2).properties(xDomain=xDomain)\n",
"\n",
"ideogram"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "Llo86Ls9ZMto"
},
"source": [
"Now, we want to display more detailed information by adding text labels for each region (i.e., `name`). Let's do this in a simple way."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 227
},
"id": "pipOz8YxZeux",
"outputId": "3a8132a5-4c15-4ae7-fbfc-cd1d3750aef2"
},
"outputs": [],
"source": [
"arm_labels = arms.mark_text().encode(\n",
" # defines the text contents\n",
" text=\"name:N\",\n",
" # defines the text colors\n",
" color=gos.Color(\"stain:N\",\n",
" domain=[\"gneg\", \"gpos25\", \"gpos50\", \"gpos75\", \"gpos100\", \"gvar\"],\n",
" range=[\"black\", \"#636363\", \"black\", \"#D9D9D9\", \"white\", \"black\"],\n",
" ),\n",
" # defines the font size in px\n",
" size=gos.value(10),\n",
" # defines the outline width and color of text labels\n",
" strokeWidth=gos.value(0),\n",
" stroke=gos.value('black')\n",
")\n",
"\n",
"ideogram = gos.overlay(\n",
" arms, \n",
" arm_labels, # newly added track\n",
" centromere_1, \n",
" centromere_2\n",
").properties(xDomain=xDomain)\n",
"\n",
"ideogram"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "wvD9Mlf8al3o"
},
"source": [
"This seems to work fine. But, what if you zoom out to see an entire chromosome?"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 227
},
"id": "0qHC9zzLbI16",
"outputId": "9ce51ed3-9cd9-4dec-8168-8bed442d160b"
},
"outputs": [],
"source": [
"ideogram.properties(xDomain=gos.GenomicDomain(chromosome=\"chr1\"))"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "eHqvlSwdczG3"
},
"source": [
"It is so cluttered that you cannot read labels! \n",
"\n",
"How to address this and make visualization more readable? You can use semantic zooming! \n",
"\n",
"Let's modify the code a little bit.\n",
"\n",
"\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 227
},
"id": "D-rVv3rPd3wX",
"outputId": "690356e8-2a5f-4c3e-8e90-b2d5fc18c9b1"
},
"outputs": [],
"source": [
"# determines when to display individual text labels\n",
"arm_labels = arm_labels.visibility_lt(\n",
" target='mark', # control visibility of `mark` or entire `track`?\n",
" measure='width', # measurement to compare with threshold\n",
" threshold='|xe-x|', # this refers to the assigned width of a text label (i.e., same as the size of `rect`) \n",
" # transitionPadding=4 # padding in px to enable smooth transition using transparency\n",
")\n",
"\n",
"ideogram = gos.overlay(\n",
" arms, \n",
" arm_labels, # track with semantic zooming\n",
" centromere_1, \n",
" centromere_2\n",
").properties(xDomain=gos.GenomicDomain(chromosome='chr1'))\n",
"\n",
"ideogram"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "PZXYKUMHgUEW"
},
"source": [
"Now, the visualization only displays text labels that are within the each rectangle.\n",
"\n",
"You can zoom in and out using your mouse wheel to see how text labels are dynamically shown.\n",
"\n",
"This is perhaps the simplest example for using semantic zooming in Gosling, and there are many cool ways of using it!"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "9yJEv2_jhH1o"
},
"source": [
"### Exercise 2: Scalable Sequence Track\n",
"\n",
"Using the similar way, you can make you sequence track scalable, showing both distributions in low resolutions and individual bases in highest resolutions."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 227
},
"id": "ZChzXsSChNMY",
"outputId": "235f755b-32d0-4787-e7c0-680a974b81e4"
},
"outputs": [],
"source": [
"data = gos.multivec(\n",
" url=\"https://server.gosling-lang.org/api/v1/tileset_info/?d=sequence-multivec\",\n",
" row=\"base\",\n",
" column=\"position\",\n",
" value=\"count\",\n",
" categories=[\"A\", \"T\", \"G\", \"C\"]\n",
")\n",
"\n",
"bar = gos.Track(data).mark_bar().encode(\n",
" x=\"position:G\",\n",
" y=gos.Y(\"count:Q\", axis=\"none\"),\n",
" color=gos.Color(\"base:N\", domain=[\"A\", \"T\", \"G\", \"C\"], legend=True)\n",
")\n",
"\n",
"text = gos.Track(data).mark_text().encode(\n",
" x=\"start:G\",\n",
" xe=\"end:G\",\n",
" size=gos.value(24),\n",
" color=gos.value(\"white\"),\n",
" text=\"base:N\",\n",
").transform_filter_not(\"count\", oneOf=[0])\n",
"\n",
"# Exercise: Uncomment the following lines and fill in the properties\n",
"# determines visibility of the text labels\n",
"text = text.visibility_lt(\n",
" # add here\n",
" # target=?,\n",
" # measure=?,\n",
" # threshold=?,\n",
" # transitionPadding=?\n",
")\n",
"\n",
"sequence = gos.overlay(bar, text).properties(\n",
" xDomain=gos.GenomicDomain(interval=[1000000, 1000010])\n",
")\n",
"\n",
"sequence"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "_oZHhdxyiRDU"
},
"source": [
"### Exercise 3: Scalable Variant Track\n",
"\n",
"Previous examples focused only on text lables, but semantic zooming can be applied to any marks supported in Gosling. Let's look at the following variant track.\n",
"\n",
"The data sources for this section are derived from the VCF at:\n",
"\n",
"- https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz\n",
"\n",
"The two derived ClinVar datasets are:\n",
"\n",
"- `clinvar.bed.beddb` - the individual variants and classifications in multires bed-like format\n",
"\n",
"- `density.multires.mv5` - a precomputed, multiresolution aggregation of variant classifications genome-wide\n",
"\n",
"Our dataset includes sevaral categories of clinical relevance, and we make a mapping of each category to a color for our visualization."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "gwMjUuW_iytR"
},
"outputs": [],
"source": [
"categories = [\n",
" \"Benign\", \n",
" \"Benign/Likely_benign\", \n",
" \"Likely_benign\", \n",
" \"Uncertain_significance\",\n",
" \"Likely_pathogenic\", \n",
" \"Pathogenic/Likely_pathogenic\",\n",
" \"Pathogenic\",\n",
"]\n",
"\n",
"colors = [\"#5A9F8C\", \"#5A9F8C\", \"#029F73\", \"gray\", \"#CB96B3\", \"#CB71A3\", \"#CB3B8C\"]"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "VahYu1oUjI_B"
},
"source": [
"#### (1) Lolipop represenation of individual variants\n",
"\n",
"First we encode the individual variants using a lolipop representation, which layers `bar` and `point` marks."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 247
},
"id": "ey33_D__jMzl",
"outputId": "8c6fabdc-e287-4564-cedb-cb669c87d96c"
},
"outputs": [],
"source": [
"# define our data source \n",
"variants = gos.beddb(\n",
" url=\"https://server.gosling-lang.org/api/v1/tileset_info/?d=clinvar-beddb\",\n",
" genomicFields=[{\"index\": 1, \"name\": \"start\"}, {\"index\": 2, \"name\": \"end\"}],\n",
" valueFields=[{\"index\": 7, \"name\": \"significance\", \"type\": \"nominal\"}],\n",
")\n",
"\n",
"# some constants\n",
"lollipop_height = 200\n",
"dy = lollipop_height / len(categories) / 2\n",
"\n",
"strips = gos.Track(variants).mark_bar().encode(\n",
" x=\"start:G\",\n",
" y=gos.Y(\n",
" \"significance:N\",\n",
" domain=categories,\n",
" range=[lollipop_height + dy, dy],\n",
" baseline=\"Uncertain_significance\",\n",
" ),\n",
" ye=gos.value(lollipop_height/2),\n",
" size=gos.value(1),\n",
" color=gos.value(\"lightgray\"),\n",
" stroke=gos.value(\"lightgray\"),\n",
" strokeWidth=gos.value(1),\n",
" opacity=gos.value(0.3),\n",
").transform_filter('significance', oneOf=categories).properties(height=lollipop_height)\n",
"\n",
"# just the \"handles\" of the lolipop\n",
"strips.view()"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 247
},
"id": "awbOolFPjPRa",
"outputId": "dee43a4c-e557-4a5b-8a72-b2edb3275597"
},
"outputs": [],
"source": [
"# just the \"tops\" of the lolipop\n",
"points = gos.Track(variants).mark_point().encode(\n",
" x=\"start:G\",\n",
" color=gos.Color(\"significance:N\", domain=categories, range=colors),\n",
" row=gos.Row(\"significance:N\", domain=categories),\n",
" size=gos.value(7),\n",
" opacity=gos.value(0.8),\n",
").properties(height=lollipop_height)\n",
"\n",
"points.view()"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 247
},
"id": "yw7GiTU4jQ0T",
"outputId": "a223bfa6-b525-4b08-e1ec-4973929f1f7e"
},
"outputs": [],
"source": [
"# combined\n",
"gos.overlay(strips, points)"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "UbUbp77MjXhf"
},
"source": [
"#### (2) Density representation of variant classifications\n",
"\n",
"Next we use a `bar` encoding to display the multiresolution aggregate density of each variant classification."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 227
},
"id": "taIomd8xjfVM",
"outputId": "8e0cc6f9-5ace-40cd-9806-675228f3bac5"
},
"outputs": [],
"source": [
"density = gos.multivec(\n",
" url=\"https://server.gosling-lang.org/api/v1/tileset_info/?d=clinvar-multivec\",\n",
" row=\"significance\",\n",
" column=\"position\",\n",
" value=\"count\",\n",
" categories=categories,\n",
" binSize=4,\n",
")\n",
"\n",
"bars = gos.Track(density).mark_bar().encode(\n",
" x=\"start:G\",\n",
" xe=\"end:G\",\n",
" y=gos.Y(\"count:Q\", axis=\"none\"),\n",
" color=gos.Color(\"significance:N\", domain=categories, range=colors, legend=True)\n",
")\n",
"\n",
"bars.view().properties(xDomain=gos.GenomicDomain(chromosome=\"chr17\"))"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "KEf95Lo7jhev"
},
"source": [
"#### (3) Combined semantic zoom track\n",
"\n",
"Now that we have defined our visualizations in isolation, we can combine them into a single view that switches the visual enocoding when zooming. We the semantic zoom properties with `visibility_lt` and `visibility_gt` options."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"colab": {
"base_uri": "https://localhost:8080/",
"height": 247
},
"id": "yugpePEDjjXk",
"outputId": "a1bcfc99-89aa-4e1f-ca83-0d8b1d410321"
},
"outputs": [],
"source": [
"lolipop = gos.overlay(\n",
" strips,\n",
" # show when zoom level is less than 100,000 bases\n",
" # .visibility_?(\n",
" # measure=?,\n",
" # target=\"mark\",\n",
" # threshold=?,\n",
" # transitionPadding=?,\n",
" # ),\n",
" points,\n",
" # show when zoom level is less than 1,000,000 bases\n",
" # .visibility_?(\n",
" # measure=?,\n",
" # target=\"mark\",\n",
" # threshold=?,\n",
" # transitionPadding=?,\n",
" # ),\n",
" bars,\n",
" # show when zoom level is less than 500,000 bases\n",
" # .visibility_?(\n",
" # measure=?,\n",
" # target=\"mark\",\n",
" # threshold=?,\n",
" # transitionPadding=?,\n",
" # )\n",
")\n",
"lolipop.properties(\n",
" xDomain=gos.GenomicDomain(chromosome=\"17\"),\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "qicv0NMyyvv1"
},
"source": [
"## Additional Resources\n",
"- Documentation: http://gosling-lang.org/docs/semantic-zoom\n",
"- Sequence example\n",
" - https://gosling.js.org/?example=SEQUENCE\n",
" - https://gosling-lang.github.io/gos/gallery/multiscale_sequence.html\n",
"- Lollipop example\n",
" - https://gosling.js.org/?example=SEMANTIC_ZOOM\n",
" - https://gosling-lang.github.io/gos/gallery/multiscale_lollipop_plot.html"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "8i7E1aKwtT8c"
},
"outputs": [],
"source": []
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "gli0oO6yszUm"
},
"outputs": [],
"source": []
}
],
"metadata": {
"colab": {
"collapsed_sections": [],
"name": "Session 3: Semantic Zooming.ipynb",
"provenance": [],
"toc_visible": true
},
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.9.12"
}
},
"nbformat": 4,
"nbformat_minor": 1
}