@datagrok/proteomics 1.0.0 → 1.2.0

package/src/analysis/subcellular-location.ts

@@ -0,0 +1,431 @@
+import * as grok from 'datagrok-api/grok';
+
+/**
+ * Shared UniProt subcellular-location service.
+ *
+ * The classifier, keyword map, and hex palette are ported VERBATIM from the
+ * locked CK-omics contract (~/Downloads/ck/CKomics_tool2.py:1384-1436
+ * `parse_subcellular_location` / `get_location_colors` and
+ * Subcellular_Location_Classification_README.txt). Any divergence is a parity
+ * regression — do not re-derive. Pure functions do no I/O.
+ */
+
+// --- Verbatim CK-omics 11-category keyword map (dict insertion order matters:
+//     it is the tie-break for equal-position matches). ---
+
+export const LOCATION_KEYWORDS: Record<string, string[]> = {
+  'Nucleus': ['nucleus', 'nuclear', 'nucleoplasm', 'chromatin', 'nucleolus',
+    'nuclear envelope', 'nuclear membrane', 'nuclear pore', 'nuclear speck',
+    'cajal body', 'nuclear body'],
+  'Cytoplasm': ['cytoplasm', 'cytosol', 'cytoplasmic', 'cytoskeleton',
+    'microtubule', 'actin', 'intermediate filament', 'sarcomere', 'myofibril',
+    'z disc', 'z disk', 'spindle', 'centriole', 'centrosome', 'cilium',
+    'flagellum', 'stress fiber'],
+  'Mitochondria': ['mitochondria', 'mitochondrial', 'mitochondrion',
+    'mitochondrial matrix', 'mitochondrial membrane',
+    'mitochondrial inner membrane', 'mitochondrial outer membrane',
+    'mitochondrial intermembrane space'],
+  'ER': ['endoplasmic reticulum', 'sarcoplasmic reticulum',
+    'rough endoplasmic reticulum', 'smooth endoplasmic reticulum',
+    'er-golgi intermediate compartment', 'ergic'],
+  'Golgi': ['golgi', 'trans-golgi', 'golgi apparatus', 'golgi membrane',
+    'cis-golgi', 'trans-golgi network', 'tgn'],
+  'Plasma Membrane': ['plasma membrane', 'cell membrane', 'cell surface',
+    'tight junction', 'gap junction', 'adherens junction', 'desmosome',
+    'focal adhesion', 'cell junction', 'synapse', 'postsynaptic',
+    'presynaptic', 'neuromuscular junction'],
+  'Lysosome': ['lysosome', 'lysosomal', 'vacuole', 'lysosomal membrane',
+    'autophagosome', 'phagosome'],
+  'Peroxisome': ['peroxisome', 'peroxisomal', 'glyoxysome'],
+  'Ribosome': ['ribosome', 'ribosomal', 'ribosomal protein', 'polysome'],
+  'Extracellular': ['extracellular', 'secreted', 'extracellular space',
+    'extracellular matrix', 'basement membrane', 'basal lamina', 'collagen',
+    'ecm'],
+  'Vesicles': ['vesicle', 'endosome', 'transport vesicle', 'secretory vesicle',
+    'early endosome', 'late endosome', 'recycling endosome',
+    'clathrin-coated vesicle', 'coated vesicle'],
+};
+
+/** Locked hex palette (README §COLOR SCHEME) as ARGB ints — same 0xFF… form as
+ * volcano.ts:60-62. 11 categories + Unknown. */
+export const LOCATION_COLORS: Record<string, number> = {
+  'Nucleus': 0xFF000000 | parseInt('FF6B6B', 16),
+  'Cytoplasm': 0xFF000000 | parseInt('ECDC44', 16),
+  'Mitochondria': 0xFF000000 | parseInt('45B7D1', 16),
+  'ER': 0xFF000000 | parseInt('96CEB4', 16),
+  'Golgi': 0xFF000000 | parseInt('FAAFFE', 16),
+  'Plasma Membrane': 0xFF000000 | parseInt('DDA0DD', 16),
+  'Lysosome': 0xFF000000 | parseInt('F39C12', 16),
+  'Peroxisome': 0xFF000000 | parseInt('E17055', 16),
+  'Ribosome': 0xFF000000 | parseInt('A29BFE', 16),
+  'Extracellular': 0xFF000000 | parseInt('FD79A8', 16),
+  'Vesicles': 0xFF000000 | parseInt('FDCB6E', 16),
+  'Unknown': 0xFF000000 | parseInt('CCCCCC', 16),
+};
+
+/** Escapes regex metacharacters (mirrors Python `re.escape` faithfully — the
+ * current keywords contain none, but stay defensive). */
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** First location keyword (by earliest character position across ALL
+ * categories) in the lowercased RAW text. Ties keep the first-iterated
+ * category (strict `<`), so keyword-map insertion order is the tie-break.
+ * The raw string is NOT pre-stripped (Pitfall 2). */
+function findFirstLocation(text: string): string | null {
+  if (!text) return null;
+  const lower = text.toLowerCase();
+  let earliestMatch: string | null = null;
+  let earliestPos = Infinity;
+  for (const category of Object.keys(LOCATION_KEYWORDS)) {
+    for (const keyword of LOCATION_KEYWORDS[category]) {
+      const m = new RegExp('\\b' + escapeRegex(keyword) + '\\b', 'i').exec(lower);
+      if (m && m.index < earliestPos) {
+        earliestPos = m.index;
+        earliestMatch = category;
+      }
+    }
+  }
+  return earliestMatch;
+}
+
+/** Verbatim port of CK-omics `parse_subcellular_location`: subcellular field is
+ * scanned fully first, GO cellular-component is fallback only, else 'Unknown'. */
+export function parseSubcellularLocation(
+  subcell: string | null | undefined,
+  go: string | null | undefined,
+): string {
+  const subcellText = subcell == null ? '' : subcell;
+  const goText = go == null ? '' : go;
+  let location = findFirstLocation(subcellText);
+  if (location) return location;
+  location = findFirstLocation(goText);
+  if (location) return location;
+  return 'Unknown';
+}
+
+/** Result of parsing one UniProt stream TSV body. */
+export interface StreamTsvResult {
+  locByAcc: Map<string, string>;
+  geneByAcc: Map<string, string>;
+  /** Whether the winning location for an accession came from a reviewed entry. */
+  reviewedByAcc: Map<string, boolean>;
+}
+
+/**
+ * Pure positional parse of a UniProt stream TSV (fields order:
+ * accession, cc_subcellular_location, go_c, reviewed, gene_primary). The first
+ * line is the display-name header and is skipped; columns are read by POSITION
+ * (`parts[0..4]`), never by header name (Pitfall 1). Within the text, the
+ * priority merge is: first occurrence sets; a reviewed non-Unknown overwrites;
+ * an existing Unknown is overwritten by any non-Unknown.
+ */
+export function mergeStreamTsv(text: string): StreamTsvResult {
+  const locByAcc = new Map<string, string>();
+  const geneByAcc = new Map<string, string>();
+  const reviewedByAcc = new Map<string, boolean>();
+  const lines = text.trim().split('\n');
+  for (let li = 1; li < lines.length; li++) {
+    const line = lines[li];
+    if (!line) continue;
+    const p = line.split('\t');
+    const acc = (p[0] ?? '').trim();
+    if (!acc) continue;
+    const subcell = p[1] ?? '';
+    const goc = p[2] ?? '';
+    const reviewed = (p[3] ?? '').toLowerCase() === 'reviewed';
+    const gene = (p[4] ?? '').trim();
+    const cat = parseSubcellularLocation(subcell, goc);
+
+    if (!locByAcc.has(acc)) {
+      locByAcc.set(acc, cat);
+      reviewedByAcc.set(acc, reviewed);
+    } else if (reviewed && cat !== 'Unknown') {
+      locByAcc.set(acc, cat);
+      reviewedByAcc.set(acc, true);
+    } else if (locByAcc.get(acc) === 'Unknown' && cat !== 'Unknown') {
+      locByAcc.set(acc, cat);
+      reviewedByAcc.set(acc, reviewed);
+    }
+    if (gene && (!geneByAcc.has(acc) || reviewed))
+      geneByAcc.set(acc, gene);
+  }
+  return {locByAcc, geneByAcc, reviewedByAcc};
+}
+
+// --- Fetch + cache + D-03 fallback (Task 2) ---
+
+/** Organism g:Profiler code → NCBI (species-level) taxonomy id. Covers all 9
+ * organisms in enrichment's `ORGANISM_LIST`. Species-level ids are used so the
+ * UniProt `taxonomy_id:` filter (hierarchical — matches the taxon and its
+ * descendants) stays inclusive of strains (e.g. E. coli K-12 under 562).
+ * Only the gene-fallback pass narrows by this; accession queries do not (A1:
+ * accessions are globally unique, so filtering them risks excluding valid hits). */
+export const ORGANISM_TAXONOMY: Record<string, number> = {
+  hsapiens: 9606, mmusculus: 10090, rnorvegicus: 10116, scerevisiae: 4932,
+  ecoli: 562, drerio: 7955, dmelanogaster: 7227, athaliana: 3702, celegans: 6239,
+};
+
+/** userDataStorage key for the cross-session accession → category cache.
+ * Exported so the volcanoOptions OK handler can peek the cache to decide
+ * which pre-OK toast wording (cold vs warm) to show — see package.ts
+ * volcanoOptions. */
+export const STORE = 'proteomics-subcell-loc';
+/** Bump only if the locked keyword map ever changes (D-04: it is a contract,
+ * so this is effectively fixed). Mismatch → stale cache discarded. */
+const SCHEMA_V = '13-04-1';
+const SCHEMA_KEY = '__schema_v';
+const ACC_CHUNK = 100;
+const GENE_CHUNK = 20;
+
+/** Progress callback shape used by getSubcellularLocations and forwarded by
+ * ensureLocationColumn / recomputeVolcano / volcanoOptions. The dialog's
+ * DG.TaskBarProgressIndicator.update is the call site that consumes this.
+ *
+ * - 'fetch-acc'    — Pass 1 chunked accession-stream UniProt queries.
+ * - 'fetch-gene'   — Pass 2 reviewed-by-gene fallback queries.
+ * - 'init-column'  — bulk-init of the LOCATION_COL column on the DataFrame
+ *                    (in volcano.ts) AFTER the network work completes. */
+export type ProgressCb = (done: number, total: number,
+  phase: 'fetch-acc' | 'fetch-gene' | 'init-column') => void;
+
+/** Maximum in-flight UniProt stream chunks. 6 is a compromise: 4× the
+ * sequential baseline on a real ~80-chunk Spectronaut Candidates file while
+ * staying well under rest.uniprot.org's documented limits. Increase only
+ * with measured evidence; UniProt's stream endpoint is shared infrastructure. */
+const FETCH_CONCURRENCY = 6;
+
+/** Wall-clock interval between incremental cache flushes during a fetch.
+ * A single setInterval-driven flush from the orchestrator (not from inside
+ * workers) sidesteps the per-chunk-counter race that a previous draft hit
+ * when two workers reached the flush check between `await` points. */
+const CACHE_FLUSH_INTERVAL_MS = 5000;
+
+const VALID_CATEGORIES = new Set<string>([...Object.keys(LOCATION_KEYWORDS), 'Unknown']);
+
+const STREAM_FIELDS = 'accession,cc_subcellular_location,go_c,reviewed,gene_primary';
+const GENE_FIELDS = 'accession,gene_primary,cc_subcellular_location,go_c';
+
+function chunk<T>(arr: T[], size: number): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+/** Index-based worker pool. Maintains a shared `nextIndex` counter; launches
+ * `limit` async workers; each worker pulls indices and awaits `work(items[i], i)`,
+ * storing results at `results[i]`; resolves with the full results array when
+ * every worker drains. Used by getSubcellularLocations Pass 1/2 to cap
+ * concurrent UniProt fetchProxy calls at FETCH_CONCURRENCY.
+ *
+ * Exported only so the test suite can verify the concurrency cap directly
+ * with synthetic deferred-promise tasks (no network). */
+export async function runWithConcurrency<T, R>(
+  items: T[], limit: number, work: (item: T, idx: number) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let nextIndex = 0;
+  const workerCount = Math.min(Math.max(1, limit), items.length || 1);
+  const workers: Promise<void>[] = [];
+  for (let w = 0; w < workerCount; w++) {
+    workers.push((async () => {
+      while (true) {
+        const i = nextIndex++;
+        if (i >= items.length) return;
+        results[i] = await work(items[i], i);
+      }
+    })());
+  }
+  await Promise.all(workers);
+  return results;
+}
+
+function taxonomyClause(organism?: string): string {
+  const tax = organism ? ORGANISM_TAXONOMY[organism] : undefined;
+  return tax ? ` AND (taxonomy_id:${tax})` : '';
+}
+
+async function loadCache(): Promise<Record<string, string>> {
+  try {
+    const raw = (await grok.dapi.userDataStorage.get(STORE)) ?? {};
+    if (raw[SCHEMA_KEY] !== SCHEMA_V)
+      return {[SCHEMA_KEY]: SCHEMA_V}; // stale → discard
+    return raw as Record<string, string>;
+  } catch {
+    return {[SCHEMA_KEY]: SCHEMA_V};
+  }
+}
+
+/**
+ * Resolves accession → subcellular category for every requested accession.
+ * Cache-first (cross-session userDataStorage map, `__schema_v`-keyed), then a
+ * chunked UniProt stream fetch via grok.dapi.fetchProxy (no raw fetch — CORS),
+ * then the D-03 reviewed-by-gene fallback for Unknown+gene accessions. Never
+ * throws out of the fetch loop: a failed batch warns and continues.
+ */
+export async function getSubcellularLocations(
+  accessions: string[],
+  organism?: string,
+  progress?: ProgressCb,
+): Promise<Map<string, string>> {
+  const unique = [...new Set(accessions.filter((a) => a && a.length > 0))];
+  const cache = await loadCache();
+
+  const resolved = new Map<string, string>();
+  const misses: string[] = [];
+  for (const acc of unique) {
+    const c = cache[acc];
+    if (c !== undefined && VALID_CATEGORIES.has(c)) resolved.set(acc, c);
+    else misses.push(acc);
+  }
+
+  const geneByAcc = new Map<string, string>();
+  const fetched: Record<string, string> = {};
+  // Applied ONLY to the Pass 2 gene fallback below — gene symbols are shared
+  // across species, so without this a rat gene resolves to the human entry.
+  const taxClause = taxonomyClause(organism);
+
+  // Single timer-driven incremental flush. Workers DO NOT touch the cache —
+  // they only mutate `resolved`/`fetched`/`geneByAcc`. The timer reads the
+  // current `fetched` map at its tick and writes through, so a session
+  // interrupted mid-fetch keeps every accession that finished. The previous
+  // draft folded the flush into the per-chunk worker body and hit a documented
+  // double-flush race when two workers reached the check between `await`
+  // points — see plan 13-08 BLOCKER FIX notes.
+  const flushCache = async (): Promise<void> => {
+    if (Object.keys(fetched).length === 0) return;
+    try {
+      await grok.dapi.userDataStorage.put(STORE,
+        {...cache, ...fetched, [SCHEMA_KEY]: SCHEMA_V});
+    } catch (e: any) {
+      console.warn(`Subcellular-location cache write failed: ${e?.message ?? e}`);
+    }
+  };
+  const flushTimer = setInterval(() => { flushCache().catch(() => {}); },
+    CACHE_FLUSH_INTERVAL_MS);
+
+  try {
+    // Pass 1: chunked accession stream queries, run with bounded concurrency.
+    const accChunks = chunk(misses, ACC_CHUNK);
+    const totalAcc = accChunks.length;
+    let doneAcc = 0;
+    await runWithConcurrency(accChunks, FETCH_CONCURRENCY, async (group) => {
+      // Pass 1 is deliberately NOT taxonomy-filtered: accessions are globally
+      // unique, so a wrong/mis-set organism must never exclude a valid protein.
+      const q = group.map((a) => `accession:${a}`).join(' OR ');
+      const url = 'https://rest.uniprot.org/uniprotkb/stream' +
+        `?query=(${encodeURIComponent(q)})` +
+        `&fields=${STREAM_FIELDS}&format=tsv`;
+      try {
+        const resp = await grok.dapi.fetchProxy(url);
+        if (!resp.ok) {
+          console.warn(`UniProt stream returned status ${resp.status}; continuing`);
+          return;
+        }
+        const {locByAcc, geneByAcc: g} = mergeStreamTsv(await resp.text());
+        for (const [acc, loc] of locByAcc) {
+          resolved.set(acc, loc);
+          fetched[acc] = loc;
+        }
+        for (const [acc, gene] of g) geneByAcc.set(acc, gene);
+      } catch (e: any) {
+        console.warn(`UniProt stream batch failed: ${e?.message ?? e}; continuing`);
+      }
+      // Increment AFTER the chunk completes — bounded concurrency means
+      // worker order can interleave, so the callback signal is non-decreasing
+      // (not strictly monotonic). Tests assert the non-decreasing invariant.
+      doneAcc++;
+      progress?.(doneAcc, totalAcc, 'fetch-acc');
+    });
+
+    // Pass 2 (D-03): reviewed-by-gene fallback for Unknown accessions with a gene.
+    const geneToUnknownAccs = new Map<string, string[]>();
+    for (const acc of misses) {
+      const loc = resolved.get(acc) ?? 'Unknown';
+      const gene = geneByAcc.get(acc);
+      if (loc === 'Unknown' && gene) {
+        if (!geneToUnknownAccs.has(gene)) geneToUnknownAccs.set(gene, []);
+        geneToUnknownAccs.get(gene)!.push(acc);
+      }
+    }
+    const genes = [...geneToUnknownAccs.keys()];
+    const geneChunks = chunk(genes, GENE_CHUNK);
+    const totalGene = geneChunks.length;
+    let doneGene = 0;
+    await runWithConcurrency(geneChunks, FETCH_CONCURRENCY, async (group) => {
+      const q = group.map((g) => `gene_exact:${g}`).join(' OR ');
+      const url = 'https://rest.uniprot.org/uniprotkb/stream' +
+        `?query=(${encodeURIComponent(q)}) AND (reviewed:true)${encodeURIComponent(taxClause)}` +
+        `&fields=${GENE_FIELDS}&format=tsv`;
+      try {
+        const resp = await grok.dapi.fetchProxy(url);
+        if (!resp.ok) {
+          console.warn(`UniProt gene fallback returned status ${resp.status}; continuing`);
+          return;
+        }
+        // Positional: accession, gene_primary, cc_subcellular_location, go_c.
+        const lines = (await resp.text()).trim().split('\n');
+        for (let li = 1; li < lines.length; li++) {
+          const parts = lines[li].split('\t');
+          const gene = (parts[1] ?? '').trim();
+          const loc = parseSubcellularLocation(parts[2] ?? '', parts[3] ?? '');
+          if (!gene || loc === 'Unknown') continue;
+          for (const acc of geneToUnknownAccs.get(gene) ?? []) {
+            resolved.set(acc, loc);
+            fetched[acc] = loc;
+          }
+        }
+      } catch (e: any) {
+        console.warn(`UniProt gene fallback batch failed: ${e?.message ?? e}; continuing`);
+      }
+      doneGene++;
+      progress?.(doneGene, totalGene, 'fetch-gene');
+    });
+
+    // Anything still unresolved → Unknown (explicit, also cached so we don't
+    // re-query it every session).
+    for (const acc of unique) {
+      if (!resolved.has(acc)) resolved.set(acc, 'Unknown');
+      if (fetched[acc] === undefined) fetched[acc] = resolved.get(acc)!;
+    }
+  } finally {
+    clearInterval(flushTimer);
+    // Single final write-through. Schema invariant preserved on every flush —
+    // tests assert this.
+    await flushCache();
+  }
+
+  const out = new Map<string, string>();
+  for (const acc of unique) out.set(acc, resolved.get(acc) ?? 'Unknown');
+  return out;
+}
+
+// --- Cached per-accession UniProt JSON (closes the folded cache-uniprot todo;
+//     uniprot-panel.ts delegates here so re-clicking a protein doesn't refetch). ---
+
+const _entryCache = new Map<string, unknown>();
+
+/** Cached single-accession UniProt JSON fetch. Mirrors the original panel
+ * discipline: grok.dapi.fetchProxy, warn + null on !resp.ok, warn + null on
+ * throw. Successful and definitive-miss (non-OK) results are cached for the
+ * session; transient throws are not. */
+export async function fetchUniProtEntry(accession: string): Promise<unknown | null> {
+  if (_entryCache.has(accession)) return _entryCache.get(accession) ?? null;
+  const url = `https://rest.uniprot.org/uniprotkb/${encodeURIComponent(accession)}.json` +
+    '?fields=accession,protein_name,gene_names,organism_name,cc_function,go';
+  try {
+    const resp = await grok.dapi.fetchProxy(url);
+    if (!resp.ok) {
+      console.warn(`UniProt fetch for ${accession} returned status ${resp.status}`);
+      _entryCache.set(accession, null);
+      return null;
+    }
+    const json = await resp.json();
+    _entryCache.set(accession, json);
+    return json;
+  } catch (e: any) {
+    console.warn(`UniProt fetch for ${accession} failed:`, e?.message ?? e);
+    return null;
+  }
+}

package/src/demo/enrichment-demo.ts

@@ -0,0 +1,94 @@
+import * as grok from 'datagrok-api/grok';
+import * as DG from 'datagrok-api/dg';
+
+import {_package} from '../package';
+import {setGroups} from '../analysis/experiment-setup';
+import {runEnrichmentPipeline} from '../analysis/enrichment';
+import {openEnrichmentVisualization} from '../viewers/enrichment-viewers';
+import {createVolcanoPlot} from '../viewers/volcano';
+import {focusProtein} from '../panels/protein-focus';
+import {SEMTYPE, DEFAULT_FC_THRESHOLD, DEFAULT_P_THRESHOLD} from '../utils/proteomics-types';
+
+/**
+ * Single-organism pathway-enrichment demo. Loads a small engineered HUMAN
+ * differential-expression result (Treatment vs Control) whose regulated proteins
+ * form two coherent, textbook-enriched sets — cell-cycle / mitosis UP and
+ * oxidative phosphorylation DOWN — over a diverse non-significant background, so
+ * g:Profiler returns crisp, recognizable terms. It opens the volcano, runs
+ * enrichment (GO / KEGG / Reactome / WikiPathways), and docks the enrichment
+ * charts cross-linked to the volcano: selecting a term highlights its proteins.
+ *
+ * This is the counterpart to the main `Proteomics Demo`, which uses the
+ * three-species HYE benchmark — a mix that is deliberately unsuitable for
+ * enrichment (g:Profiler assumes a single organism). The dataset ships at
+ * `files/demo/enrichment-demo.csv` (see `files/demo/README.md`).
+ *
+ * Enrichment calls g:Profiler over the network; if the service is unreachable
+ * the demo still opens the DE table + volcano and explains how to retry.
+ */
+export async function runEnrichmentDemo(): Promise<void> {
+  const pi = DG.TaskBarProgressIndicator.create('Loading enrichment demo…');
+  try {
+    pi.update(10, 'Loading human DE result…');
+    const text = await _package.files.readAsText('demo/enrichment-demo.csv');
+    const df = DG.DataFrame.fromCsv(text);
+    // Kept free of "Enrichment" so the derived enrichment view reads cleanly as
+    // "<source> — Enrichment" (mirrors the QC demo's "<source> — QC" naming).
+    df.name = 'Treatment vs Control (human)';
+
+    // Semantic-type the columns so the pipeline and panels find them by type,
+    // not by name — mirrors what the parsers do on a real import.
+    const setSem = (name: string, sem: string): void => {
+      const c = df.col(name);
+      if (c) c.semType = sem;
+    };
+    setSem('Protein ID', SEMTYPE.PROTEIN_ID);
+    setSem('Gene', SEMTYPE.GENE_SYMBOL);
+    setSem('log2FC', SEMTYPE.LOG2FC);
+    setSem('p-value', SEMTYPE.P_VALUE);
+    setSem('adj.p-value', SEMTYPE.P_VALUE);
+
+    // A pre-computed DE result (like a Spectronaut Candidates import): mark DE
+    // complete and record group NAMES so the volcano legend reads naturally.
+    // There are no per-sample columns, so the group column lists stay empty.
+    df.setTag('proteomics.source', 'generic');
+    df.setTag('proteomics.de_method', 'precomputed');
+    df.setTag('proteomics.de_complete', 'true');
+    setGroups(df, {group1: {name: 'Treatment', columns: []}, group2: {name: 'Control', columns: []}});
+
+    const tv = grok.shell.addTableView(df);
+    const volcano = createVolcanoPlot(df);
+    tv.dockManager.dock(volcano, DG.DOCK_TYPE.RIGHT, null, 'Volcano', 0.5);
+
+    // Headline protein (row 0 = a cell-cycle hit) selected for its UniProt panel.
+    focusProtein(df, 0);
+
+    pi.update(45, 'Running g:Profiler enrichment (GO / KEGG / Reactome)…');
+    try {
+      const {enrichmentDf, mapped, total} = await runEnrichmentPipeline(
+        df, DEFAULT_FC_THRESHOLD, DEFAULT_P_THRESHOLD, 'hsapiens',
+        ['GO:BP', 'GO:MF', 'GO:CC', 'KEGG', 'REAC', 'WP'], true);
+      pi.update(90, 'Opening enrichment charts…');
+      // openEnrichmentVisualization opens the enrichment view and makes it current.
+      // Name it "<source> — Enrichment" (mirrors the DE demo's "<source> — QC" tab)
+      // and land back on the main view, so the demo-app framework's leaf-rename puts
+      // "Enrichment Analysis" on the main view — matching where the DE demo lands.
+      const enrichTv = openEnrichmentVisualization(enrichmentDf, df);
+      enrichTv.name = `${df.name} — Enrichment`;
+      grok.shell.v = tv;
+      grok.shell.info(
+        `Enrichment demo: ${enrichmentDf.rowCount} over-represented terms across ${mapped}/${total} genes. ` +
+        'Up-regulated proteins are enriched for cell-cycle / mitosis; down-regulated for oxidative ' +
+        'phosphorylation. Select a term row to highlight its proteins on the volcano.');
+    } catch (e: any) {
+      grok.shell.warning(
+        `Enrichment demo: g:Profiler enrichment could not run (${e?.message ?? e}). ` +
+        'The DE table and volcano are open — retry via Proteomics | Enrichment Analysis ' +
+        'once the service is reachable.');
+    }
+
+    pi.update(100, 'Done');
+  } finally {
+    pi.close();
+  }
+}

package/src/demo/proteomics-demo.ts

@@ -0,0 +1,123 @@
+import * as grok from 'datagrok-api/grok';
+import * as DG from 'datagrok-api/dg';
+
+import {_package} from '../package';
+import {parseSpectronautText} from '../parsers/spectronaut-parser';
+import {getGroups} from '../analysis/experiment-setup';
+import {imputeKnn} from '../analysis/imputation';
+import {runDifferentialExpression} from '../analysis/differential-expression';
+import {createVolcanoPlot} from '../viewers/volcano';
+import {createExpressionHeatmap} from '../viewers/heatmap';
+import {openQcDashboard} from '../viewers/qc-dashboard';
+import {focusProtein} from '../panels/protein-focus';
+
+/**
+ * The package's single "richest endpoint" demo. It takes the HYE benchmark (a
+ * Spectronaut DIA report where Human, Yeast, and E. coli proteomes are mixed at
+ * known, different ratios between two conditions — HYE mix A vs B, four
+ * replicates each) all the way through the analysis pipeline and lands on the
+ * fully-analyzed protein table with the Volcano and Expression Heatmap docked,
+ * a QC dashboard on a second tab, and the most significant protein pre-selected
+ * so its UniProt entry is already showing in the context panel.
+ *
+ * HYE is chosen deliberately: two whole species shift abundance between the
+ * conditions, so hundreds of proteins are genuinely differential and the
+ * volcano shows a strong, self-evident signal — the point of a "richest
+ * endpoint" demo. (A spike-in benchmark like CPTAC is real but deliberately
+ * subtle: at n=3 a plain t-test can't clear FDR, leaving an all-grey volcano.)
+ *
+ * Enrichment is intentionally NOT part of this demo: g:Profiler enrichment
+ * assumes a single organism, and HYE is a three-species mix, so GO/pathway
+ * enrichment would only map the human subset and mislead. Enrichment belongs in
+ * a single-organism demo.
+ *
+ * The Spectronaut parser auto-annotates the two conditions from R.Condition and
+ * tags the data preNormalized, so the demo skips straight to imputation + DE and
+ * does NOT re-normalize — re-normalizing an already-normalized export would
+ * distort the known species-ratio signal. Differential expression runs the
+ * client-side Welch t-test, so the demo needs no R environment. The only network
+ * touches are best-effort and cached: the parser's Ensembl gene-label lookup and
+ * the UniProt context panel, both of which degrade gracefully offline. The
+ * dataset ships at `files/demo/spectronaut-hye-demo.tsv` (see
+ * `files/demo/README.md`).
+ */
+export async function runProteomicsDemo(): Promise<void> {
+  const pi = DG.TaskBarProgressIndicator.create('Loading proteomics demo…');
+  try {
+    pi.update(5, 'Importing HYE benchmark (Spectronaut DIA)…');
+    const text = await _package.files.readAsText('demo/spectronaut-hye-demo.tsv');
+    const df = await parseSpectronautText(text);
+    df.name = 'HYE benchmark';
+    const analysisTv = grok.shell.addTableView(df);
+
+    // Groups (HYE mix A / B) are auto-populated by the parser from R.Condition.
+    const groups = getGroups(df);
+    if (!groups) {
+      grok.shell.warning('Demo: expected two auto-annotated conditions — ' +
+        'opened the table without running differential expression.');
+      return;
+    }
+    const allCols = [...groups.group1.columns, ...groups.group2.columns];
+
+    pi.update(40, 'Imputing missing values (KNN)…');
+    imputeKnn(df, allCols);
+    df.setTag('proteomics.imputed', 'true');
+
+    pi.update(60, 'Differential expression (t-test)…');
+    runDifferentialExpression(df, groups.group1.columns, groups.group2.columns,
+      groups.group1.name, groups.group2.name);
+    df.setTag('proteomics.de_method', 't-test');
+
+    pi.update(78, 'Building volcano and heatmap…');
+    const volcano = createVolcanoPlot(df);
+    analysisTv.dockManager.dock(volcano, DG.DOCK_TYPE.RIGHT, null, 'Volcano', 0.5);
+
+    const heatmap = await createExpressionHeatmap(df, {title: 'Heatmap: Top 50 DE Proteins'});
+    analysisTv.dockManager.dock(heatmap, DG.DOCK_TYPE.DOWN, null, 'Heatmap', 0.45);
+
+    // QC dashboard on a SECOND tab. openQcDashboard docks into grok.shell.tv, so
+    // open a second table view over the same DataFrame (it becomes current), build
+    // QC there, then land back on the analysis endpoint. Sharing one DataFrame
+    // across two views is fine — QC adds its own columns; the volcano keeps its own.
+    pi.update(90, 'Building QC dashboard tab…');
+    const qcTv = grok.shell.addTableView(df);
+    qcTv.name = 'HYE benchmark — QC';
+    openQcDashboard(df);
+    grok.shell.v = analysisTv;
+
+    // Pre-select the most significant protein so the UniProt context panel is
+    // already showing — a real accession from a spiked species, not the flat
+    // human background. Shared with the import handlers (which focus row 0).
+    focusProtein(df, topHitRow(df));
+
+    pi.update(100, 'Done');
+    grok.shell.info('Proteomics demo: HYE benchmark analyzed end to end ' +
+      '(import → impute → differential expression). Yeast and E. coli proteins ' +
+      'shift abundance between the two conditions, so the volcano separates the ' +
+      'genuinely differential proteins from the constant human background. ' +
+      'QC charts are on the second tab; the top hit is selected for its UniProt panel.');
+  } finally {
+    pi.close();
+  }
+}
+
+/**
+ * Row index of the most significant protein (smallest adj.p among the
+ * significant rows) to pre-select for the UniProt panel. Falls back to row 0
+ * when there is no significant protein or no adj.p column.
+ */
+function topHitRow(df: DG.DataFrame): number {
+  const adj = df.col('adj.p-value');
+  const sig = df.col('significant');
+  if (!adj) return 0;
+
+  let best = -1;
+  let bestP = Infinity;
+  for (let i = 0; i < df.rowCount; i++) {
+    if (sig && !sig.get(i)) continue;
+    if (adj.isNone(i)) continue;
+    const p = adj.get(i) as number;
+    if (p < bestP) { bestP = p; best = i; }
+  }
+  return best < 0 ? 0 : best;
+}

package/src/global.d.ts

@@ -0,0 +1,15 @@
+// Ambient module declarations for webpack `asset/source` raw-text imports.
+// Used by src/tests/spectronaut-parser.ts to inline the committed
+// tools/spectronaut-aggregate.{sql,sh} as strings (Plan 12-03 R5 drift guard);
+// the tools/ dir is not deployed under files/, so it is unreachable via
+// _package.files at runtime — webpack asset/source is the only way to pin the
+// committed fallback content into the test bundle.
+declare module '*.sql' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.sh' {
+  const content: string;
+  export default content;
+}