@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/vendor/skills/skills/galaxy-integration/jupyterlite/examples/variant_annotation.ipynb

@@ -0,0 +1,816 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": "# Variant Annotation: Synonymous vs Nonsynonymous\n\n## What This Notebook Does\n\nThis notebook takes a list of genetic variants (mutations) and determines whether each variant:\n- **Changes the protein** (nonsynonymous) - potentially affects function\n- **Does NOT change the protein** (synonymous) - silent mutation\n- **Is outside genes** (intergenic) - not in a protein-coding region\n\n## Background: How DNA Encodes Proteins\n\n```\nDNA:     ATG  GCT  TAC  ...  (read in groups of 3 bases called \"codons\")\n         ↓    ↓    ↓\nProtein: Met  Ala  Tyr  ...  (each codon = 1 amino acid)\n```\n\nBecause the genetic code is **redundant** (multiple codons can encode the same amino acid),\nsome mutations don't change the protein:\n\n- `GCT` → Alanine\n- `GCC` → Alanine (same amino acid! This would be a **synonymous** mutation)\n- `GCT` → `GAT` → Aspartic acid (different amino acid = **nonsynonymous**)\n\n## Inputs\n\n1. **GenBank file** (dataset #13372): Contains the reference genome with gene annotations\n2. **Variant table** (dataset #13437): List of mutations found in samples"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": "---\n## Step 1: Import Libraries\n\nWe need a few Python libraries:\n- `gxy`: Galaxy-specific library to download/upload files\n- `pandas`: For working with tables (like Excel but in Python)\n- `Bio` (Biopython): For reading GenBank files and translating DNA\n- `altair`: For creating interactive visualizations"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": "# Galaxy integration - lets us download datasets from the history\nimport gxy\n\n# Pandas - work with data tables\nimport pandas as pd\n\n# Biopython - parse GenBank files and translate DNA to protein\nfrom Bio import SeqIO\nfrom Bio.Data import CodonTable\n\n# Altair - create interactive charts\nimport altair as alt\nalt.data_transformers.disable_max_rows()  # Allow large datasets\n\n# Suppress Altair/narwhals compatibility warnings (harmless but noisy)\nimport warnings\nwarnings.filterwarnings('ignore', message='.*narwhals.*')\n\nprint(\"Libraries loaded successfully!\")"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": "# Define which Galaxy datasets to use\n# These numbers correspond to the dataset IDs in your Galaxy history\n\nGENBANK_DATASET = 13372    # GenBank annotation file (contains gene locations)\nVARIANTS_DATASET = 13437   # Variant table (list of mutations)"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 2: Download Data from Galaxy\n",
+    "\n",
+    "The `gxy.get()` function downloads a dataset from your Galaxy history to this notebook's environment."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": "# Download the GenBank annotation file\ngenbank_path = await gxy.get(GENBANK_DATASET)\nprint(f\"Downloaded GenBank file to: {genbank_path}\")"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": "# Download the variant table\nvariants_path = await gxy.get(VARIANTS_DATASET)\nprint(f\"Downloaded variants file to: {variants_path}\")"
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 3: Parse the GenBank File\n",
+    "\n",
+    "### What is a GenBank file?\n",
+    "\n",
+    "A GenBank file contains:\n",
+    "1. The full genome sequence (DNA)\n",
+    "2. Annotations showing where genes are located\n",
+    "\n",
+    "Each gene has a \"CDS\" (Coding Sequence) feature that tells us:\n",
+    "- Start and end positions on the genome\n",
+    "- Gene name and protein product\n",
+    "- Which strand (+ or -) it's on"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Load the GenBank file\n",
+    "record = SeqIO.read(genbank_path, \"genbank\")\n",
+    "\n",
+    "print(f\"Genome ID: {record.id}\")\n",
+    "print(f\"Genome length: {len(record.seq):,} bases\")\n",
+    "print(f\"Description: {record.description}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Find all CDS (protein-coding) features\n",
+    "# These are the genes we'll use for annotation\n",
+    "\n",
+    "cds_features = [f for f in record.features if f.type == \"CDS\"]\n",
+    "\n",
+    "print(f\"Found {len(cds_features)} protein-coding genes (CDS features)\")\n",
+    "print(\"\\nFirst few genes:\")\n",
+    "for i, feat in enumerate(cds_features[:5]):\n",
+    "    # Get gene name from the 'gene' or 'locus_tag' field\n",
+    "    gene_name = feat.qualifiers.get(\"gene\", feat.qualifiers.get(\"locus_tag\", [\"unknown\"]))[0]\n",
+    "    product = feat.qualifiers.get(\"product\", [\"unknown\"])[0]\n",
+    "    print(f\"  {i+1}. {gene_name}: {product}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 4: Build a Lookup Table for Every Position in Every Gene\n",
+    "\n",
+    "To annotate variants, we need to know for EVERY position in the genome:\n",
+    "- Is it inside a gene?\n",
+    "- If yes, which codon does it belong to?\n",
+    "- What amino acid does that codon encode?\n",
+    "\n",
+    "We'll build a table where each row represents one nucleotide position.\n",
+    "\n",
+    "### Understanding Codon Position\n",
+    "\n",
+    "Each codon has 3 bases. The position within the codon matters:\n",
+    "\n",
+    "```\n",
+    "Codon:    A   T   G\n",
+    "Position: 1   2   3\n",
+    "          ↑       ↑\n",
+    "          |       └── 3rd position: often \"wobble\" - mutations here are often synonymous\n",
+    "          └────────── 1st position: mutations here usually change the amino acid\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def get_gene_info(feature):\n",
+    "    \"\"\"\n",
+    "    Extract useful information from a CDS feature.\n",
+    "    \n",
+    "    Returns a dictionary with gene name, product, and translation settings.\n",
+    "    \"\"\"\n",
+    "    q = feature.qualifiers\n",
+    "    \n",
+    "    return {\n",
+    "        # Gene name - try 'gene' first, fall back to 'locus_tag'\n",
+    "        \"gene\": (q.get(\"gene\") or q.get(\"locus_tag\") or [\"\"])[0],\n",
+    "        \n",
+    "        # Protein product description\n",
+    "        \"product\": (q.get(\"product\") or [\"\"])[0],\n",
+    "        \n",
+    "        # Codon start - which base of the first codon is the start\n",
+    "        # Usually 1, but can be 2 or 3 for partial genes\n",
+    "        \"codon_start\": int((q.get(\"codon_start\") or [\"1\"])[0]),\n",
+    "        \n",
+    "        # Translation table - which genetic code to use\n",
+    "        # 1 = standard, 11 = bacterial/plastid, etc.\n",
+    "        \"transl_table\": int((q.get(\"transl_table\") or [\"1\"])[0]),\n",
+    "    }\n",
+    "\n",
+    "# Test on the first gene\n",
+    "test_info = get_gene_info(cds_features[0])\n",
+    "print(\"Example gene info:\")\n",
+    "for key, value in test_info.items():\n",
+    "    print(f\"  {key}: {value}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def codon_to_amino_acid(codon, transl_table=1):\n",
+    "    \"\"\"\n",
+    "    Translate a 3-letter DNA codon to its amino acid.\n",
+    "    \n",
+    "    Examples:\n",
+    "        'ATG' -> 'M' (Methionine, start codon)\n",
+    "        'TAA' -> '*' (Stop codon)\n",
+    "        'GCT' -> 'A' (Alanine)\n",
+    "    \"\"\"\n",
+    "    # Get the correct codon table (standard = 1, bacterial = 11, etc.)\n",
+    "    table = CodonTable.unambiguous_dna_by_id.get(transl_table, \n",
+    "                                                  CodonTable.unambiguous_dna_by_id[1])\n",
+    "    \n",
+    "    codon = codon.upper()\n",
+    "    \n",
+    "    # Check if it's a stop codon\n",
+    "    if codon in table.stop_codons:\n",
+    "        return \"*\"\n",
+    "    \n",
+    "    # Look up the amino acid\n",
+    "    return table.forward_table.get(codon, \"?\")  # \"?\" if unknown\n",
+    "\n",
+    "# Test the function\n",
+    "print(\"Testing codon translation:\")\n",
+    "test_codons = [\"ATG\", \"GCT\", \"GCC\", \"TAA\", \"TGA\"]\n",
+    "for codon in test_codons:\n",
+    "    aa = codon_to_amino_acid(codon)\n",
+    "    print(f\"  {codon} -> {aa}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def build_cds_lookup_table(record):\n",
+    "    \"\"\"\n",
+    "    Build a table with one row per nucleotide for all CDS features.\n",
+    "    \n",
+    "    For each nucleotide, we record:\n",
+    "    - genome_pos: position on the genome (1-based)\n",
+    "    - gene: gene name\n",
+    "    - product: protein product\n",
+    "    - base: the nucleotide (A, T, G, or C)\n",
+    "    - codon: the 3-letter codon this base belongs to\n",
+    "    - codon_pos: position within the codon (1, 2, or 3)\n",
+    "    - aa: the amino acid the codon encodes\n",
+    "    \"\"\"\n",
+    "    rows = []  # Will hold all our data\n",
+    "    \n",
+    "    # Process each CDS feature (gene)\n",
+    "    for feature in record.features:\n",
+    "        if feature.type != \"CDS\":\n",
+    "            continue\n",
+    "        \n",
+    "        # Get gene information\n",
+    "        info = get_gene_info(feature)\n",
+    "        \n",
+    "        # Extract the CDS sequence (handles strand automatically)\n",
+    "        cds_seq = str(feature.extract(record.seq))\n",
+    "        \n",
+    "        # Get the genomic positions for each base in the CDS\n",
+    "        # This handles + and - strand genes correctly\n",
+    "        strand = feature.location.strand or 1\n",
+    "        \n",
+    "        # Build list of genome positions in transcription order\n",
+    "        genome_positions = []\n",
+    "        for part in feature.location.parts:\n",
+    "            start, end = int(part.start), int(part.end)\n",
+    "            if strand >= 0:\n",
+    "                # Forward strand: positions go 5' to 3'\n",
+    "                positions = list(range(start + 1, end + 1))  # +1 for 1-based\n",
+    "            else:\n",
+    "                # Reverse strand: positions go 3' to 5' (reverse order)\n",
+    "                positions = list(range(end, start, -1))  # Already 1-based\n",
+    "            genome_positions.extend(positions)\n",
+    "        \n",
+    "        # Handle codon_start (frame offset)\n",
+    "        frame_offset = info[\"codon_start\"] - 1\n",
+    "        \n",
+    "        # Process each nucleotide\n",
+    "        n = len(cds_seq)\n",
+    "        for i in range(n):\n",
+    "            base = cds_seq[i]\n",
+    "            \n",
+    "            # Calculate codon information\n",
+    "            in_frame = i + frame_offset\n",
+    "            codon_pos = (in_frame % 3) + 1  # 1, 2, or 3\n",
+    "            codon_number = (in_frame // 3) + 1\n",
+    "            \n",
+    "            # Get the full codon (3 bases)\n",
+    "            codon_start_idx = in_frame - (in_frame % 3) - frame_offset\n",
+    "            if codon_start_idx >= 0 and codon_start_idx + 2 < n:\n",
+    "                codon = cds_seq[codon_start_idx:codon_start_idx + 3]\n",
+    "                aa = codon_to_amino_acid(codon, info[\"transl_table\"])\n",
+    "            else:\n",
+    "                codon = \"NNN\"  # Incomplete codon\n",
+    "                aa = \"?\"\n",
+    "            \n",
+    "            # Add row to our table\n",
+    "            rows.append({\n",
+    "                \"genome_pos\": genome_positions[i],\n",
+    "                \"gene\": info[\"gene\"],\n",
+    "                \"product\": info[\"product\"],\n",
+    "                \"base\": base,\n",
+    "                \"codon\": codon,\n",
+    "                \"codon_pos\": codon_pos,\n",
+    "                \"codon_number\": codon_number,\n",
+    "                \"aa\": aa,\n",
+    "            })\n",
+    "    \n",
+    "    # Convert to DataFrame and sort by position\n",
+    "    df = pd.DataFrame(rows)\n",
+    "    df = df.sort_values([\"gene\", \"product\", \"genome_pos\"])\n",
+    "    df = df.reset_index(drop=True)\n",
+    "    \n",
+    "    return df\n",
+    "\n",
+    "print(\"Building CDS lookup table (this may take a moment)...\")\n",
+    "cds_table = build_cds_lookup_table(record)\n",
+    "print(f\"Done! Table has {len(cds_table):,} rows\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Let's look at the CDS table we built\n",
+    "print(\"CDS lookup table summary:\")\n",
+    "print(f\"  Total nucleotide positions: {len(cds_table):,}\")\n",
+    "print(f\"  Unique genes: {cds_table['gene'].nunique()}\")\n",
+    "print(f\"  Unique products: {cds_table['product'].nunique()}\")\n",
+    "\n",
+    "print(\"\\nFirst 15 rows (showing start of first gene):\")\n",
+    "cds_table.head(15)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 5: Load the Variant Table\n",
+    "\n",
+    "The variant table contains mutations found in the samples. Each row is one variant with:\n",
+    "- Position on the genome\n",
+    "- Reference allele (what the genome has)\n",
+    "- Alternate allele (what the mutation is)\n",
+    "- Frequency information"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Load the variant table\n",
+    "# This file has no header, so we specify column names\n",
+    "variants = pd.read_csv(\n",
+    "    variants_path,\n",
+    "    sep=\"\\t\",           # Tab-separated\n",
+    "    header=None,         # No header row\n",
+    "    names=[\"var_id\", \"samples\", \"af_min\", \"af_mean\", \"af_max\", \"REF\", \"ALT\"]\n",
+    ")\n",
+    "\n",
+    "print(f\"Loaded {len(variants)} variants\")\n",
+    "print(\"\\nColumn descriptions:\")\n",
+    "print(\"  var_id: Unique identifier (includes position)\")\n",
+    "print(\"  samples: Number of samples with this variant\")\n",
+    "print(\"  af_min/mean/max: Allele frequency statistics\")\n",
+    "print(\"  REF: Reference allele\")\n",
+    "print(\"  ALT: Alternate allele (the mutation)\")\n",
+    "\n",
+    "variants.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Extract the position number from the var_id column\n",
+    "# The var_id looks like \"10044GA\" - the number is the position\n",
+    "\n",
+    "variants[\"POS\"] = variants[\"var_id\"].str.extract(r\"^(\\d+)\").astype(int)\n",
+    "\n",
+    "print(\"Added POS column:\")\n",
+    "print(f\"  Position range: {variants['POS'].min()} to {variants['POS'].max()}\")\n",
+    "variants[[\"var_id\", \"POS\", \"REF\", \"ALT\"]].head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 6: Annotate Variants\n",
+    "\n",
+    "Now we'll combine the variants with our CDS lookup table to determine the effect of each mutation.\n",
+    "\n",
+    "### The Process\n",
+    "\n",
+    "For each variant:\n",
+    "1. Look up the position in the CDS table\n",
+    "2. If not found → it's **intergenic** (not in a gene)\n",
+    "3. If found:\n",
+    "   - Get the original codon and amino acid\n",
+    "   - Create the mutated codon (swap the variant base)\n",
+    "   - Translate the mutated codon\n",
+    "   - If same amino acid → **synonymous**\n",
+    "   - If different → **nonsynonymous**"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Helper function: get the complement of a DNA base\n",
+    "# This is needed for genes on the reverse strand\n",
+    "\n",
+    "COMPLEMENT = {\"A\": \"T\", \"T\": \"A\", \"G\": \"C\", \"C\": \"G\",\n",
+    "              \"a\": \"t\", \"t\": \"a\", \"g\": \"c\", \"c\": \"g\"}\n",
+    "\n",
+    "def complement(base):\n",
+    "    \"\"\"Return the complement of a DNA base (A↔T, G↔C).\"\"\"\n",
+    "    return COMPLEMENT.get(base, base)\n",
+    "\n",
+    "print(\"Testing complement:\")\n",
+    "for b in [\"A\", \"T\", \"G\", \"C\"]:\n",
+    "    print(f\"  {b} -> {complement(b)}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def annotate_variants_with_effects(variants_df, cds_df):\n",
+    "    \"\"\"\n",
+    "    Annotate each variant with its effect on the protein.\n",
+    "    \n",
+    "    Returns a new DataFrame with additional columns:\n",
+    "    - strand: '+' or '-' (which strand the gene is on)\n",
+    "    - new_codon: the codon after the mutation\n",
+    "    - new_aa: the amino acid after the mutation\n",
+    "    - effect: 'synonymous', 'nonsynonymous', or 'intergenic'\n",
+    "    \"\"\"\n",
+    "    \n",
+    "    # Merge variants with CDS table based on position\n",
+    "    # This gives us the codon/amino acid context for each variant\n",
+    "    merged = variants_df.merge(\n",
+    "        cds_df,\n",
+    "        left_on=\"POS\",\n",
+    "        right_on=\"genome_pos\",\n",
+    "        how=\"left\"  # Keep all variants, even if not in a gene\n",
+    "    )\n",
+    "    \n",
+    "    # Lists to store our results\n",
+    "    strands = []\n",
+    "    new_codons = []\n",
+    "    new_aas = []\n",
+    "    effects = []\n",
+    "    \n",
+    "    # Process each row\n",
+    "    for idx, row in merged.iterrows():\n",
+    "        \n",
+    "        # Check if this position is in a gene\n",
+    "        if pd.isna(row.get(\"codon\")):\n",
+    "            # Not in a gene\n",
+    "            strands.append(None)\n",
+    "            new_codons.append(None)\n",
+    "            new_aas.append(None)\n",
+    "            effects.append(\"intergenic\")\n",
+    "            continue\n",
+    "        \n",
+    "        # Get the values we need\n",
+    "        ref_base = str(row[\"REF\"]).upper()\n",
+    "        alt_base = str(row[\"ALT\"]).upper()\n",
+    "        cds_base = str(row[\"base\"]).upper()  # Base in the CDS (may be complemented)\n",
+    "        codon = str(row[\"codon\"]).upper()\n",
+    "        codon_pos = int(row[\"codon_pos\"])  # 1, 2, or 3\n",
+    "        old_aa = str(row[\"aa\"])\n",
+    "        \n",
+    "        # Determine strand by comparing ref_base to cds_base\n",
+    "        if ref_base == cds_base:\n",
+    "            # Same base = forward strand\n",
+    "            strand = \"+\"\n",
+    "            coding_alt = alt_base\n",
+    "        elif complement(ref_base) == cds_base:\n",
+    "            # Complement = reverse strand\n",
+    "            strand = \"-\"\n",
+    "            coding_alt = complement(alt_base)\n",
+    "        else:\n",
+    "            # Mismatch - something's wrong\n",
+    "            strands.append(\"?\")\n",
+    "            new_codons.append(None)\n",
+    "            new_aas.append(None)\n",
+    "            effects.append(\"unknown\")\n",
+    "            continue\n",
+    "        \n",
+    "        strands.append(strand)\n",
+    "        \n",
+    "        # Create the mutated codon\n",
+    "        # Replace the base at codon_pos with the new base\n",
+    "        codon_list = list(codon)\n",
+    "        codon_list[codon_pos - 1] = coding_alt  # -1 because codon_pos is 1-based\n",
+    "        new_codon = \"\".join(codon_list)\n",
+    "        new_codons.append(new_codon)\n",
+    "        \n",
+    "        # Translate the new codon\n",
+    "        new_aa = codon_to_amino_acid(new_codon)\n",
+    "        new_aas.append(new_aa)\n",
+    "        \n",
+    "        # Determine the effect\n",
+    "        if old_aa == \"?\" or new_aa == \"?\":\n",
+    "            effects.append(\"unknown\")\n",
+    "        elif new_aa == old_aa:\n",
+    "            effects.append(\"synonymous\")\n",
+    "        else:\n",
+    "            effects.append(\"nonsynonymous\")\n",
+    "    \n",
+    "    # Add our results to the DataFrame\n",
+    "    merged[\"strand\"] = strands\n",
+    "    merged[\"new_codon\"] = new_codons\n",
+    "    merged[\"new_aa\"] = new_aas\n",
+    "    merged[\"effect\"] = effects\n",
+    "    \n",
+    "    return merged\n",
+    "\n",
+    "print(\"Annotating variants (this may take a moment)...\")\n",
+    "annotated = annotate_variants_with_effects(variants, cds_table)\n",
+    "print(f\"Done! Annotated {len(annotated)} rows\")\n",
+    "print(\"\\n(Note: Some variants appear multiple times if they affect overlapping genes)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 7: View Results\n",
+    "\n",
+    "Let's see what we found!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Summary of effects\n",
+    "print(\"=\" * 50)\n",
+    "print(\"VARIANT EFFECT SUMMARY\")\n",
+    "print(\"=\" * 50)\n",
+    "print(annotated[\"effect\"].value_counts())\n",
+    "print(\"\\n\")\n",
+    "\n",
+    "# Calculate percentages\n",
+    "total = len(annotated)\n",
+    "for effect in [\"nonsynonymous\", \"synonymous\", \"intergenic\"]:\n",
+    "    count = (annotated[\"effect\"] == effect).sum()\n",
+    "    pct = 100 * count / total\n",
+    "    print(f\"  {effect}: {count} ({pct:.1f}%)\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# View the annotated variants\n",
+    "# Select the most important columns for display\n",
+    "\n",
+    "display_columns = [\n",
+    "    \"var_id\",      # Variant ID\n",
+    "    \"POS\",         # Genome position\n",
+    "    \"REF\",         # Reference allele\n",
+    "    \"ALT\",         # Alternate allele\n",
+    "    \"gene\",        # Gene name\n",
+    "    \"product\",     # Protein product\n",
+    "    \"codon\",       # Original codon\n",
+    "    \"new_codon\",   # Mutated codon\n",
+    "    \"aa\",          # Original amino acid\n",
+    "    \"new_aa\",      # New amino acid\n",
+    "    \"effect\",      # Effect type\n",
+    "    \"samples\",     # Number of samples\n",
+    "    \"af_mean\"      # Mean allele frequency\n",
+    "]\n",
+    "\n",
+    "print(\"First 20 annotated variants:\")\n",
+    "annotated[display_columns].head(20)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Summary by gene\n",
+    "print(\"Effect counts by gene:\")\n",
+    "gene_summary = annotated.pivot_table(\n",
+    "    index=\"gene\",\n",
+    "    columns=\"effect\",\n",
+    "    values=\"var_id\",\n",
+    "    aggfunc=\"nunique\",  # Count unique variants\n",
+    "    fill_value=0\n",
+    ")\n",
+    "gene_summary"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 8: Visualization\n",
+    "\n",
+    "We'll create two charts:\n",
+    "1. **Variant track**: Shows where variants are located and their effects\n",
+    "2. **Amino acid heatmap**: Shows the amino acid context across genes\n",
+    "\n",
+    "Both charts share the same X-axis (genome position), so you can zoom in on one and both will update."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Prepare data for visualization\n",
+    "\n",
+    "# For the heatmap: add a label column for amino acids\n",
+    "cds_vis = cds_table.copy()\n",
+    "cds_vis[\"aa_label\"] = cds_vis[\"aa\"].replace({\"*\": \"Stop\", \"?\": \"Unknown\"})\n",
+    "\n",
+    "# Get the order of products (genes) by their position on the genome\n",
+    "product_order = (\n",
+    "    cds_vis.groupby(\"product\")[\"genome_pos\"]\n",
+    "    .min()\n",
+    "    .sort_values()\n",
+    "    .index.tolist()\n",
+    ")\n",
+    "\n",
+    "print(f\"Products (genes) in order: {len(product_order)}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create the amino acid heatmap\n",
+    "# Each rectangle represents one nucleotide, colored by amino acid\n",
+    "\n",
+    "# Add columns for rectangle coordinates\n",
+    "cds_vis[\"x2\"] = cds_vis[\"genome_pos\"] + 1  # End of rectangle\n",
+    "\n",
+    "heatmap = alt.Chart(cds_vis).mark_rect().encode(\n",
+    "    # X-axis: genome position\n",
+    "    x=alt.X(\"genome_pos:Q\", title=\"Genome position\"),\n",
+    "    x2=\"x2:Q\",\n",
+    "    \n",
+    "    # Y-axis: gene product\n",
+    "    y=alt.Y(\"product:N\", sort=product_order, title=\"Gene\"),\n",
+    "    \n",
+    "    # Color by amino acid\n",
+    "    color=alt.Color(\"aa_label:N\", title=\"Amino acid\"),\n",
+    "    \n",
+    "    # Tooltip shows details on hover\n",
+    "    tooltip=[\"gene\", \"product\", \"genome_pos\", \"codon\", \"aa_label\", \"base\"]\n",
+    ").properties(\n",
+    "    width=900,\n",
+    "    height=max(140, 18 * len(product_order)),\n",
+    "    title=\"Amino acid context by position\"\n",
+    ")\n",
+    "\n",
+    "print(\"Heatmap created!\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create the variant track\n",
+    "# Shows variants as tick marks, colored by effect\n",
+    "\n",
+    "# Filter to only coding variants (synonymous or nonsynonymous)\n",
+    "coding_variants = annotated[\n",
+    "    annotated[\"effect\"].isin([\"synonymous\", \"nonsynonymous\"])\n",
+    "].copy()\n",
+    "\n",
+    "# Calculate allele frequency range for sizing\n",
+    "coding_variants[\"af_range\"] = coding_variants[\"af_max\"] - coding_variants[\"af_min\"]\n",
+    "\n",
+    "# Get product order for these variants\n",
+    "var_product_order = (\n",
+    "    coding_variants.groupby(\"product\")[\"POS\"]\n",
+    "    .min()\n",
+    "    .sort_values()\n",
+    "    .index.tolist()\n",
+    ")\n",
+    "\n",
+    "variant_track = alt.Chart(coding_variants).mark_tick(thickness=4).encode(\n",
+    "    # X-axis: genome position\n",
+    "    x=alt.X(\"POS:Q\", title=\"Genome position\"),\n",
+    "    \n",
+    "    # Y-axis: gene product\n",
+    "    y=alt.Y(\"product:N\", sort=var_product_order, title=\"Gene\"),\n",
+    "    \n",
+    "    # Color: green for synonymous, red for nonsynonymous\n",
+    "    color=alt.Color(\n",
+    "        \"effect:N\",\n",
+    "        title=\"Effect\",\n",
+    "        scale=alt.Scale(\n",
+    "            domain=[\"synonymous\", \"nonsynonymous\"],\n",
+    "            range=[\"#2ca02c\", \"#d62728\"]  # Green, Red\n",
+    "        )\n",
+    "    ),\n",
+    "    \n",
+    "    # Size: based on allele frequency range\n",
+    "    size=alt.Size(\"af_range:Q\", title=\"AF range\"),\n",
+    "    \n",
+    "    # Opacity: based on number of samples\n",
+    "    opacity=alt.Opacity(\"samples:Q\", title=\"Samples\"),\n",
+    "    \n",
+    "    # Tooltip shows details on hover\n",
+    "    tooltip=[\n",
+    "        \"var_id\", \"POS\", \"REF\", \"ALT\",\n",
+    "        \"gene\", \"product\", \"effect\",\n",
+    "        \"codon\", \"new_codon\", \"aa\", \"new_aa\",\n",
+    "        \"samples\", \"af_mean\"\n",
+    "    ]\n",
+    ").properties(\n",
+    "    width=900,\n",
+    "    height=max(120, 16 * len(var_product_order)),\n",
+    "    title=\"Variants by position (green=synonymous, red=nonsynonymous)\"\n",
+    ")\n",
+    "\n",
+    "print(\"Variant track created!\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Combine both charts with shared X-axis zooming\n",
+    "# Click and drag on either chart to zoom - both will update!\n",
+    "\n",
+    "# Create a selection for X-axis zooming\n",
+    "zoom = alt.selection_interval(bind=\"scales\", encodings=[\"x\"])\n",
+    "\n",
+    "# Stack the charts vertically\n",
+    "combined_chart = alt.vconcat(\n",
+    "    variant_track,   # Variants on top\n",
+    "    heatmap,         # Amino acids below\n",
+    "    spacing=10       # Gap between charts\n",
+    ").resolve_scale(\n",
+    "    x=\"shared\",          # Share the X-axis between charts\n",
+    "    color=\"independent\"  # Keep colors separate\n",
+    ").add_params(\n",
+    "    zoom  # Add zooming capability\n",
+    ")\n",
+    "\n",
+    "print(\"Combined chart ready!\")\n",
+    "print(\"Tip: Click and drag on the chart to zoom in. Double-click to reset.\")\n",
+    "\n",
+    "combined_chart"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Step 9: Save Results (Optional)\n",
+    "\n",
+    "Uncomment the cells below to save the annotated variants back to your Galaxy history."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Uncomment to save the annotated variants as a tabular file in Galaxy\n",
+    "\n",
+    "# annotated.to_csv(\"annotated_variants.tsv\", sep=\"\\t\", index=False)\n",
+    "# await gxy.put(\"annotated_variants.tsv\", output=\"Annotated Variants\", ext=\"tabular\")\n",
+    "# print(\"Saved annotated variants to Galaxy history!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Summary\n",
+    "\n",
+    "This notebook:\n",
+    "1. Downloaded GenBank annotation and variant data from Galaxy\n",
+    "2. Built a lookup table mapping every nucleotide to its codon and amino acid\n",
+    "3. Annotated each variant with its effect (synonymous, nonsynonymous, or intergenic)\n",
+    "4. Created an interactive visualization showing variant positions and effects\n",
+    "\n",
+    "**Key findings:**\n",
+    "- Most variants are nonsynonymous (change the protein)\n",
+    "- Synonymous variants are less common (\"silent\" mutations)\n",
+    "- The visualization lets you explore which genes have the most variants"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}