@datagrok/proteomics 1.0.0 → 1.2.0

package/tools/derive-precursor-golden-sidecar.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/*
+ * Derives files/demo/spectronaut-hye-precursor-golden.json from the committed
+ * duckdb golden files/demo/spectronaut-hye-precursor-golden.tsv.
+ *
+ * This script does NO aggregation — it is a pure, lossless transcription of the
+ * already-committed duckdb output into a JSON map the in-browser `grok test`
+ * runner can read with certainty when committed-file reads are unavailable in
+ * the test runner. Because it never re-computes anything, the equivalence test
+ * stays pinned to REAL duckdb output (the D-04 oracle), not to a hand-derived
+ * approximation. Re-running it against an unchanged golden produces a
+ * byte-identical JSON.
+ *
+ * Regen chain (run in order, or the artifacts silently drift):
+ *   1. node tools/generate-spectronaut-precursor-fixture.mjs
+ *   2. tools/spectronaut-aggregate.sh files/demo/spectronaut-hye-precursor.tsv \
+ *        files/demo/spectronaut-hye-precursor-golden.tsv
+ *   3. node tools/derive-precursor-golden-sidecar.mjs   (this script)
+ *
+ * Run:  node tools/derive-precursor-golden-sidecar.mjs
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PKG_ROOT = path.resolve(__dirname, '..');
+const GOLDEN = path.join(PKG_ROOT, 'files/demo/spectronaut-hye-precursor-golden.tsv');
+const OUTPUT = path.join(PKG_ROOT, 'files/demo/spectronaut-hye-precursor-golden.json');
+
+// Quantity column preference order — same as the in-package Spectronaut parser
+// (src/parsers/spectronaut-parser.ts QUANTITY_COLUMNS).
+const QUANTITY_COLUMNS = ['PG.IBAQ', 'PG.Quantity'];
+
+const text = fs.readFileSync(GOLDEN, 'utf8');
+const lines = text.split(/\r?\n/).filter((l) => l.length > 0);
+if (lines.length < 2)
+  throw new Error(`Golden ${GOLDEN} has no data rows — run the aggregate wrapper first.`);
+
+const headers = lines[0].split('\t');
+const idx = Object.fromEntries(headers.map((h, i) => [h, i]));
+
+const protIdx = idx['PG.ProteinGroups'];
+const condIdx = idx['R.Condition'];
+const replIdx = idx['R.Replicate'];
+const qvalIdx = idx['EG.Qvalue'];
+const quantCol = QUANTITY_COLUMNS.find((c) => idx[c] !== undefined);
+
+if (protIdx === undefined || condIdx === undefined || replIdx === undefined ||
+    qvalIdx === undefined || quantCol === undefined) {
+  throw new Error(
+    `Golden ${GOLDEN} is missing an expected column. ` +
+    `Need PG.ProteinGroups / R.Condition / R.Replicate / EG.Qvalue / ` +
+    `${QUANTITY_COLUMNS.join('|')}. Got: ${headers.join(', ')}`);
+}
+const quantIdx = idx[quantCol];
+
+const out = {};
+for (let i = 1; i < lines.length; i++) {
+  const f = lines[i].split('\t');
+  const protein = f[protIdx];
+  const condition = f[condIdx];
+  const replicate = f[replIdx];
+  // Numbers exactly as duckdb wrote them. Empty q-value (TRY_CAST→NULL min,
+  // e.g. the non-numeric / empty-string-q-value proteins) → Number('') is 0;
+  // keep the verbatim transcription rather than inventing a sentinel.
+  const key = `${protein}${condition}_${replicate}`;
+  out[key] = {
+    quantity: Number(f[quantIdx]),
+    qvalue: Number(f[qvalIdx] ?? ''),
+  };
+}
+
+fs.writeFileSync(OUTPUT, JSON.stringify(out, null, 2) + '\n');
+const keys = Object.keys(out);
+console.log(`Wrote ${OUTPUT}`);
+console.log(`  ${keys.length} (protein × condition × replicate) entries ` +
+  `transcribed verbatim from ${path.basename(GOLDEN)} ` +
+  `(quantity column: ${quantCol}).`);

package/tools/generate-enrichment-fixture.sh

@@ -0,0 +1,160 @@
+#!/bin/bash
+# Engineered human Treatment-vs-Control DE result for the enrichment demo.
+# UP = cell cycle / mitosis, DOWN = oxidative phosphorylation, plus a diverse
+# non-significant background. Gene symbols are real HGNC; accessions real UniProt.
+# Fold-changes and p-values are spread with a DETERMINISTIC sin-hash jitter so
+# the volcano looks organic (no banding) yet regenerates identically anywhere.
+out=files/demo/enrichment-demo.csv
+echo "Protein ID,Gene,log2FC,p-value,adj.p-value,significant" > "$out"
+
+UP="CDK1 P06493
+CCNB1 P14635
+CCNB2 O95067
+CDC20 Q12834
+BUB1 O43683
+BUB1B O60566
+AURKA O14965
+AURKB Q96GD4
+PLK1 P53350
+CCNA2 P20248
+CDK2 P24941
+MAD2L1 Q13257
+TOP2A P11388
+KIF11 P52732
+CENPA P49450
+CENPE Q02224
+NDC80 O14777
+CDC6 Q99741
+CDC45 O75419
+MCM2 P49736
+MCM3 P25205
+MCM4 P33991
+MCM5 P33992
+MCM6 Q14566
+MCM7 P33993
+CDC25C P30307
+CDK4 P11802
+CCNE1 P24864
+CHEK1 O14757
+WEE1 P30291"
+
+DOWN="NDUFA9 Q16795
+NDUFS1 P28331
+NDUFS2 O75306
+NDUFB10 O96000
+NDUFV1 P49821
+NDUFA4 O00483
+NDUFB8 O95169
+SDHA P31040
+SDHB P21912
+UQCRC1 P31930
+UQCRC2 P22695
+UQCRFS1 P47985
+CYC1 P08574
+COX4I1 P13073
+COX5A P20674
+COX5B P10606
+COX6C P09669
+COX7A2 P14406
+COX6B1 P14854
+ATP5F1A P25705
+ATP5F1B P06576
+ATP5F1C P36542
+ATP5PO P48047
+ATP5PB P24539
+ATP5MC1 P05496"
+
+BG="GAPDH P04406
+ACTB P60709
+TUBB P07437
+ALB P02768
+ENO1 P06733
+PKM P14618
+LDHA P00338
+PGK1 P00558
+ALDOA P04075
+TPI1 P60174
+GPI P06744
+PGAM1 P18669
+HSPA8 P11142
+HSP90AA1 P07900
+HSPA5 P11021
+HSPD1 P10809
+CALR P27797
+CANX P27824
+PDIA3 P30101
+P4HB P07237
+VIM P08670
+FLNA P21333
+ACTN1 P12814
+TLN1 Q9Y490
+CFL1 P23528
+PFN1 P07737
+GSN P06396
+CAP1 Q01518
+ANXA1 P04083
+ANXA2 P07355
+ANXA5 P08758
+S100A4 P26447
+YWHAZ P63104
+YWHAE P62258
+YWHAB P31946
+PPIA P62937
+PPIB P23284
+SOD1 P00441
+SOD2 P04179
+CAT P04040
+PRDX1 Q06830
+PRDX2 P32119
+GSTP1 P09211
+TXN P10599
+FTL P02792
+FTH1 P02794
+TF P02787
+CTSD P07339
+CTSB P07858
+LGALS1 P09382
+LGALS3 P17931
+CD44 P16070
+ITGB1 P05556
+EEF1A1 P68104
+EEF2 P13639
+RPS3 P23396
+RPL4 P36578
+RPLP0 P05388
+NPM1 P06748
+NCL P19338
+HNRNPK P61978
+SRSF1 Q07955
+G3BP1 Q13283
+DDX5 P17844"
+
+# deterministic pseudo-random in [0,1) from a seed integer and a multiplier
+emit() { # $1=list  $2=sign(+1/-1) for sig sets, 0=background
+  local sign="$2"; local i=0
+  while read -r gene acc; do
+    [ -z "$gene" ] && continue
+    awk -v i="$i" -v gene="$gene" -v acc="$acc" -v sign="$sign" 'BEGIN{
+      h1=sin((i+1)*12.9898)*43758.5453; j1=h1-int(h1); if(j1<0)j1+=1
+      h2=sin((i+1)*78.2330)*24634.6345; j2=h2-int(h2); if(j2<0)j2+=1
+      if (sign!=0) {
+        fc=sign*(1.2 + j1*2.3)                 # |fc| 1.2..3.5
+        e=2.5 + j2*4.5                          # -log10(p) 2.5..7.0
+        p=exp(-e*log(10)); adj=2*p
+        printf "%s,%s,%.3f,%.2e,%.2e,true\n", acc, gene, fc, p, adj
+      } else {
+        fc=-1.3 + j1*2.6                        # spread -1.3..1.3
+        p=0.06 + j2*0.90                        # 0.06..0.96  (never significant)
+        adj=p*1.05; if(adj>0.99)adj=0.99
+        printf "%s,%s,%.3f,%.3f,%.3f,false\n", acc, gene, fc, p, adj
+      }
+    }' >> "$out"
+    i=$((i+1))
+  done <<< "$1"
+}
+
+emit "$UP" 1
+emit "$DOWN" -1
+emit "$BG" 0
+
+echo "rows: $(($(wc -l < "$out") - 1)) (sig=$(grep -c ',true$' "$out"), ns=$(grep -c ',false$' "$out"))"

package/tools/generate-spectronaut-candidates-fixture.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/*
+ * Generates files/demo/spectronaut-hye-candidates.tsv from the already-shipped
+ * files/demo/spectronaut-hye-mix.tsv (HYE three-species mix, SpectroPipeR origin).
+ *
+ * Source data is real Spectronaut long-format PG quantification. The Candidates
+ * report it ships alongside is DERIVED — we run our own Welch's t-test with BH
+ * FDR correction in this script and emit the result formatted as a Spectronaut
+ * Candidates report. This is not a verbatim Spectronaut export; it exists to
+ * exercise the Candidates import path with values that line up with the source
+ * PG file so the two demo fixtures tell the same story.
+ *
+ * Run:  node tools/generate-spectronaut-candidates-fixture.mjs
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import jStat from 'jstat';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PKG_ROOT = path.resolve(__dirname, '..');
+const SOURCE = path.join(PKG_ROOT, 'files/demo/spectronaut-hye-mix.tsv');
+const OUTPUT = path.join(PKG_ROOT, 'files/demo/spectronaut-hye-candidates.tsv');
+
+// Numerator (group1) and denominator (group2) per Spectronaut convention.
+// AVG Log2 Ratio = log2(numerator / denominator). The HYE mix is symmetric;
+// labelling B as the numerator just keeps the convention legible.
+const NUMERATOR = 'HYE mix B';
+const DENOMINATOR = 'HYE mix A';
+
+/** Read TSV file into header + rows. */
+function readTsv(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8');
+  const lines = text.split(/\r?\n/);
+  const headers = lines[0].split('\t');
+  const idx = Object.fromEntries(headers.map((h, i) => [h, i]));
+  const rows = [];
+  for (let i = 1; i < lines.length; i++) {
+    if (!lines[i]) continue;
+    const fields = lines[i].split('\t');
+    rows.push(fields);
+  }
+  return {headers, idx, rows};
+}
+
+/** Pivot long PG report: protein -> {sampleKey -> IBAQ}. First-encountered
+ * non-empty IBAQ wins per protein × sample (constant per protein × sample in
+ * SpectroPipeR's report; mirrors the in-package Spectronaut parser). */
+function pivotProteinIbaq(headers, idx, rows) {
+  const protein = {};
+  for (const r of rows) {
+    const pg = r[idx['PG.ProteinGroups']];
+    const cond = r[idx['R.Condition']];
+    const repl = r[idx['R.Replicate']];
+    const ibaqRaw = r[idx['PG.IBAQ']];
+    const org = r[idx['PG.Organisms']];
+    if (!pg || !cond || !repl) continue;
+    const ibaq = Number(ibaqRaw);
+    if (!Number.isFinite(ibaq) || ibaq <= 0) continue;
+    const sampleKey = `${cond}|${repl}`;
+    if (!protein[pg]) protein[pg] = {samples: {}, organism: org || ''};
+    if (protein[pg].samples[sampleKey] === undefined)
+      protein[pg].samples[sampleKey] = ibaq;
+    if (!protein[pg].organism && org) protein[pg].organism = org;
+  }
+  return protein;
+}
+
+/** Welch's two-sample t-test using jStat. Returns null when either sample has
+ * fewer than two finite values. */
+function welchTTest(a, b) {
+  const af = a.filter(Number.isFinite);
+  const bf = b.filter(Number.isFinite);
+  if (af.length < 2 || bf.length < 2) return null;
+  const meanA = jStat.mean(af);
+  const meanB = jStat.mean(bf);
+  const varA = jStat.variance(af, true);
+  const varB = jStat.variance(bf, true);
+  const seA = varA / af.length;
+  const seB = varB / bf.length;
+  const se = Math.sqrt(seA + seB);
+  if (se === 0) return {t: 0, df: af.length + bf.length - 2, p: 1, meanA, meanB};
+  const t = (meanB - meanA) / se;
+  // Welch–Satterthwaite degrees of freedom
+  const df = Math.pow(seA + seB, 2) /
+    (Math.pow(seA, 2) / (af.length - 1) + Math.pow(seB, 2) / (bf.length - 1));
+  const pTwoSided = 2 * (1 - jStat.studentt.cdf(Math.abs(t), df));
+  return {t, df, p: pTwoSided, meanA, meanB};
+}
+
+/** Benjamini–Hochberg FDR correction. Returns array of adjusted p-values aligned
+ * to input order; entries left as null where the input is null. */
+function bhAdjust(pvals) {
+  const indexed = pvals.map((p, i) => ({p, i})).filter((x) => x.p !== null);
+  indexed.sort((a, b) => a.p - b.p);
+  const n = indexed.length;
+  const adj = new Array(pvals.length).fill(null);
+  let cumMin = 1;
+  for (let rank = n; rank >= 1; rank--) {
+    const e = indexed[rank - 1];
+    const q = e.p * n / rank;
+    cumMin = Math.min(cumMin, q);
+    adj[e.i] = Math.min(cumMin, 1);
+  }
+  return adj;
+}
+
+function main() {
+  const {headers, idx, rows} = readTsv(SOURCE);
+  console.log(`Read ${rows.length} long-format rows, ${headers.length} columns.`);
+
+  const protein = pivotProteinIbaq(headers, idx, rows);
+  const proteins = Object.keys(protein).sort();
+  console.log(`Pivoted to ${proteins.length} protein groups.`);
+
+  // Sample keys per group
+  const sampleKey = (c, r) => `${c}|${r}`;
+  const groupSamples = (cond) => [1, 2, 3, 4].map((r) => sampleKey(cond, String(r)));
+  const numKeys = groupSamples(NUMERATOR);
+  const denKeys = groupSamples(DENOMINATOR);
+
+  // Per-protein log2FC + raw p-value
+  const proteinStats = proteins.map((pg) => {
+    const samples = protein[pg].samples;
+    const num = numKeys.map((k) => samples[k]).filter(Number.isFinite);
+    const den = denKeys.map((k) => samples[k]).filter(Number.isFinite);
+    const numLog2 = num.map((x) => Math.log2(x));
+    const denLog2 = den.map((x) => Math.log2(x));
+    const t = welchTTest(denLog2, numLog2);  // a=denominator, b=numerator
+    if (!t) {
+      return {
+        pg,
+        organism: protein[pg].organism,
+        log2fc: null,
+        p: null,
+        meanNum: num.length > 0 ? jStat.mean(num) : null,
+        meanDen: den.length > 0 ? jStat.mean(den) : null,
+        nRatios: Math.min(num.length, den.length),
+        valid: false,
+      };
+    }
+    return {
+      pg,
+      organism: protein[pg].organism,
+      log2fc: t.meanB - t.meanA,  // log2(num) - log2(den)
+      p: t.p,
+      meanNum: jStat.mean(num),
+      meanDen: jStat.mean(den),
+      nRatios: Math.min(num.length, den.length),
+      valid: true,
+    };
+  });
+
+  const adj = bhAdjust(proteinStats.map((s) => s.p));
+
+  // Write Candidates TSV
+  const outHeaders = [
+    'Valid', 'Comparison (group1/group2)',
+    'Condition Numerator', 'Condition Denominator',
+    '# of Ratios', 'Group',
+    'AVG Group Quantity Numerator', 'AVG Group Quantity Denominator',
+    'AVG Log2 Ratio', 'Absolute AVG Log2 Ratio',
+    '% Change', 'Ratio',
+    'Pvalue', 'Qvalue',
+    'ProteinGroups', 'Genes', 'UniProtIds', 'Organisms',
+  ];
+  const comparison = `${NUMERATOR} / ${DENOMINATOR}`;
+
+  const lines = [outHeaders.join('\t')];
+  let nSig = 0, nUp = 0, nDown = 0;
+  for (let i = 0; i < proteinStats.length; i++) {
+    const s = proteinStats[i];
+    const q = adj[i];
+    const ratio = (s.meanNum != null && s.meanDen != null && s.meanDen > 0)
+      ? (s.meanNum / s.meanDen) : null;
+    const pctChange = ratio != null ? (ratio - 1) * 100 : null;
+    const row = [
+      s.valid ? 'True' : 'False',
+      comparison,
+      NUMERATOR,
+      DENOMINATOR,
+      String(s.nRatios),
+      s.pg,
+      s.meanNum != null ? s.meanNum.toFixed(4) : '',
+      s.meanDen != null ? s.meanDen.toFixed(4) : '',
+      s.log2fc != null ? s.log2fc.toFixed(6) : '',
+      s.log2fc != null ? Math.abs(s.log2fc).toFixed(6) : '',
+      pctChange != null ? pctChange.toFixed(4) : '',
+      ratio != null ? ratio.toFixed(6) : '',
+      s.p != null ? s.p.toExponential(6) : '',
+      q != null ? q.toExponential(6) : '',
+      s.pg,                                        // ProteinGroups (same as Group here)
+      '',                                          // Genes (HYE PG report has no symbols)
+      s.pg,                                        // UniProtIds (PG.ProteinGroups in this dataset are UniProt accs)
+      s.organism,
+    ];
+    lines.push(row.join('\t'));
+
+    if (s.log2fc != null && q != null && Math.abs(s.log2fc) >= 1 && q <= 0.05) {
+      nSig++;
+      if (s.log2fc > 0) nUp++; else nDown++;
+    }
+  }
+
+  fs.writeFileSync(OUTPUT, lines.join('\n') + '\n');
+  console.log(`Wrote ${OUTPUT}`);
+  console.log(`  ${proteinStats.length} rows; ${nSig} significant (${nUp} up, ${nDown} down) at |log2FC|>=1, q<=0.05`);
+}
+
+main();

package/tools/generate-spectronaut-precursor-fixture.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/*
+ * Generates files/demo/spectronaut-hye-precursor.tsv — a small SYNTHETIC
+ * precursor-level Spectronaut long-format report used to exercise the streaming
+ * import path (Plan 02) and the duckdb-equivalence golden test (Plan 03).
+ *
+ * The fixture carries the D-01 precursor signature columns
+ * (EG.ModifiedPeptide / FG.Charge / PEP.StrippedSequence) so the header-sniff
+ * routes it to the streaming aggregator, uses CondA/CondB (so the committed
+ * tools/spectronaut-aggregate.sql DMD↔WT flip is a structural no-op), keeps the
+ * quantity value CONSTANT per (protein × condition × replicate) so duckdb max()
+ * equals the parser's first-encountered value, and carries NO
+ * PG.Genes/PG.ProteinAccessions columns (the real hye-mix demo lacks them and
+ * the committed SQL drops the matching any_value SELECT terms for this reason).
+ *
+ * It deliberately includes one CON__ row, one REV__ row, one protein whose
+ * precursors mix a >0.01 sub-threshold q-value with a passing one, one
+ * non-numeric-q-value protein, and one empty-q-value protein so every R2 filter
+ * branch is exercised by a single fixture.
+ *
+ * Pure standalone Node (no datagrok-api import); the row shape mirrors the
+ * extended makeLongFormatTsv in src/tests/spectronaut-parser.ts.
+ *
+ * Run:  node tools/generate-spectronaut-precursor-fixture.mjs
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PKG_ROOT = path.resolve(__dirname, '..');
+const OUTPUT = path.join(PKG_ROOT, 'files/demo/spectronaut-hye-precursor.tsv');
+
+const CONDITIONS = ['CondA', 'CondB'];
+const REPLICATES = [1, 2, 3];
+
+// Column order mirrors the extended makeLongFormatTsv header. NO
+// PG.Genes/PG.ProteinAccessions — see doc block.
+const HEADERS = [
+  'R.FileName', 'R.Condition', 'R.Replicate', 'PG.ProteinGroups',
+  'PG.Organisms', 'PG.Quantity', 'EG.Qvalue', 'PEP.StrippedSequence',
+  'EG.ModifiedPeptide', 'FG.Charge', 'FG.Id',
+];
+
+// Two distinct precursors per (protein × condition × replicate). Quantity is
+// held constant within each group; only precursor identity varies, so duckdb
+// max() collapses to the same value the parser's first-encountered-wins logic
+// produces.
+const PRECURSORS = [
+  {strip: 'PEPTIDER', mod: '_PEPTIDER_', charge: '2', fg: 'FG1'},
+  {strip: 'ANOTHERPEP', mod: '_ANOTHERPEP_', charge: '3', fg: 'FG2'},
+];
+
+const ORGANISMS = ['Homo sapiens', 'Saccharomyces cerevisiae', 'Escherichia coli'];
+
+const rows = [HEADERS.join('\t')];
+let nDataRows = 0;
+const proteinSet = new Set();
+const sampleSet = new Set();
+
+function emit(fileName, cond, rep, id, organism, quantity, qVal) {
+  for (const p of PRECURSORS) {
+    rows.push([fileName, cond, String(rep), id, organism,
+      String(quantity), String(qVal), p.strip, p.mod, p.charge, p.fg].join('\t'));
+    nDataRows++;
+  }
+}
+
+function emitProtein(id, organism, qVal, quantity) {
+  proteinSet.add(id);
+  for (const cond of CONDITIONS) {
+    for (const rep of REPLICATES) {
+      const fileName = `run_${cond}_${rep}`;
+      sampleSet.add(`${cond}_${rep}`);
+      emit(fileName, cond, rep, id, organism, quantity, qVal);
+    }
+  }
+}
+
+// ── Regular passing proteins: a few dozen, three-species mix, all q<=0.01 ──
+const N_REGULAR = 36;
+let quant = 1000;
+for (let i = 0; i < N_REGULAR; i++) {
+  const id = `P${String(i).padStart(5, '0')}`;
+  const organism = ORGANISMS[i % ORGANISMS.length];
+  emitProtein(id, organism, 0.001, quant++);
+}
+
+// ── Decoy / contaminant rows (dropped by the WHERE CON__/REV__ filter) ──
+emitProtein('CON__P99999', 'Homo sapiens', 0.001, 9000);
+emitProtein('REV__Q88888', 'Homo sapiens', 0.001, 9001);
+
+// ── Mixed sub-threshold protein: one passing precursor, one >0.01 dropped ──
+// Emit the rows by hand so the two precursors carry DIFFERENT q-values.
+{
+  const id = 'P70001';
+  proteinSet.add(id);
+  for (const cond of CONDITIONS) {
+    for (const rep of REPLICATES) {
+      const fileName = `run_${cond}_${rep}`;
+      sampleSet.add(`${cond}_${rep}`);
+      // passing precursor
+      rows.push([fileName, cond, String(rep), id, 'Homo sapiens',
+        '7000', '0.002', PRECURSORS[0].strip, PRECURSORS[0].mod,
+        PRECURSORS[0].charge, PRECURSORS[0].fg].join('\t'));
+      nDataRows++;
+      // sub-threshold precursor (q-value 0.05 > 0.01 → dropped by WHERE)
+      rows.push([fileName, cond, String(rep), id, 'Homo sapiens',
+        '7000', '0.05', PRECURSORS[1].strip, PRECURSORS[1].mod,
+        PRECURSORS[1].charge, PRECURSORS[1].fg].join('\t'));
+      nDataRows++;
+    }
+  }
+}
+
+// ── Non-numeric q-value protein ('Profiled' → TRY_CAST NULL → passes) ──
+emitProtein('P70002', 'Saccharomyces cerevisiae', 'Profiled', 6500);
+
+// ── Empty-string q-value protein (nullstr → NULL → passes) ──
+emitProtein('P70003', 'Escherichia coli', '', 6600);
+
+fs.writeFileSync(OUTPUT, rows.join('\n') + '\n');
+console.log(`Wrote ${OUTPUT}`);
+console.log(`  ${nDataRows} data rows, ${proteinSet.size} protein groups ` +
+  `(incl. CON__/REV__/edge), ${sampleSet.size} samples ` +
+  `(${CONDITIONS.length} conditions × ${REPLICATES.length} replicates).`);

package/tools/spectronaut-aggregate.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Collapse a long-form Spectronaut Report into the protein-group × sample shape
+# the Proteomics package's parseSpectronautText parser consumes.
+#
+# This is the documented MANUAL FALLBACK for a Spectronaut report too large for
+# the in-browser streaming importer: run it locally, then import the small
+# aggregated .tsv it produces. It is also the D-04 equivalence oracle the Wave-0
+# golden test pins to (see files/demo/README.md).
+#
+# Run: tools/spectronaut-aggregate.sh <input.tsv> [output.tsv]
+#
+# Requires the `duckdb` CLI on PATH (v1.3.0 used to derive the committed golden).
+
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: $0 <input.tsv> [output.tsv]" >&2
+  exit 1
+fi
+
+IN="$1"
+OUT="${2:-${IN%.tsv}.aggregated.tsv}"
+SQL="$(dirname "$0")/spectronaut-aggregate.sql"
+
+if [[ ! -f "$IN" ]]; then
+  echo "Input not found: $IN" >&2
+  exit 1
+fi
+
+echo "Aggregating: $IN"
+echo "Output:      $OUT"
+
+# Substitute paths into the SQL template. DuckDB's COPY ... TO doesn't accept
+# variables, so we materialize the SQL first. SQL single-quote escaping: double up
+# any embedded ' in the paths.
+IN_ESC="${IN//\'/\'\'}"
+OUT_ESC="${OUT//\'/\'\'}"
+TMP_SQL="$(mktemp -t spectronaut-aggregate.XXXXXX.sql)"
+trap 'rm -f "$TMP_SQL"' EXIT
+sed -e "s|__IN_PATH__|${IN_ESC}|g" -e "s|__OUT_PATH__|${OUT_ESC}|g" "$SQL" > "$TMP_SQL"
+
+duckdb < "$TMP_SQL"
+
+echo
+echo "Input size:  $(du -h "$IN"  | cut -f1)"
+echo "Output size: $(du -h "$OUT" | cut -f1)"