@datagrok/proteomics 1.0.1 → 1.2.1

package/src/tests/fragpipe-e2e.ts

@@ -0,0 +1,74 @@
+import {category, test, expect} from '@datagrok-libraries/test/src/test';
+import {parseFragPipeText} from '../parsers/fragpipe-parser';
+import {setGroups} from '../analysis/experiment-setup';
+import {medianNormalize} from '../analysis/normalization';
+import {imputeMean} from '../analysis/imputation';
+import {runDifferentialExpression} from '../analysis/differential-expression';
+import {SEMTYPE} from '../utils/proteomics-types';
+import {_package} from '../package-test';
+
+const FIXTURE_PATH = 'demo/fragpipe-smoke-test.tsv';
+
+const GROUPS = {
+  group1: {name: 'Control', columns: ['log2(Ctrl_1 MaxLFQ Intensity)', 'log2(Ctrl_2 MaxLFQ Intensity)']},
+  group2: {name: 'Treatment', columns: ['log2(Treat_1 MaxLFQ Intensity)', 'log2(Treat_2 MaxLFQ Intensity)']},
+};
+
+const UP_GENES = ['TP53', 'AKT1', 'F2'];
+const DOWN_GENES = ['BRCA1', 'PRKCD'];
+const UNCHANGED_GENES = ['EGFR', 'MTOR', 'HRAS'];
+
+category('FragPipe E2E', () => {
+  test('full pipeline (parse → normalize → impute → DE) on fragpipe-smoke-test.tsv', async () => {
+    const text = await _package.files.readAsText(FIXTURE_PATH);
+    const df = await parseFragPipeText(text);
+
+    expect(df.rowCount, 8);
+    expect(df.getTag('proteomics.source'), 'fragpipe');
+    expect(df.col('Protein ID')!.semType, SEMTYPE.PROTEIN_ID);
+    expect(df.col('Gene')!.semType, SEMTYPE.GENE_SYMBOL);
+    expect(df.col('log2(Ctrl_1 MaxLFQ Intensity)') !== null, true);
+    expect(df.col('log2(Treat_2 MaxLFQ Intensity)') !== null, true);
+
+    setGroups(df, GROUPS);
+    expect(df.getTag('proteomics.groups') !== null, true);
+
+    const log2Cols = [...GROUPS.group1.columns, ...GROUPS.group2.columns];
+    medianNormalize(df, log2Cols);
+    expect(df.getTag('proteomics.normalized'), 'true');
+    for (const name of log2Cols)
+      expect(Math.abs(df.col(name)!.stats.med) < 1e-4, true);
+
+    imputeMean(df, log2Cols);
+    expect(df.getTag('proteomics.imputed'), 'true');
+
+    runDifferentialExpression(df, GROUPS.group1.columns, GROUPS.group2.columns,
+      'Control', 'Treatment', 1.0, 0.05);
+    expect(df.getTag('proteomics.de_complete'), 'true');
+    expect(df.col('log2FC') !== null, true);
+    expect(df.col('p-value') !== null, true);
+    expect(df.col('adj.p-value') !== null, true);
+    expect(df.col('significant') !== null, true);
+
+    const geneRow: Record<string, number> = {};
+    const geneCol = df.col('Gene')!;
+    for (let i = 0; i < df.rowCount; i++)
+      geneRow[geneCol.get(i) as string] = i;
+
+    const fc = df.col('log2FC')!;
+    const sig = df.col('significant')!;
+
+    for (const g of UP_GENES) {
+      expect(fc.get(geneRow[g]) > 1.0, true);
+      expect(sig.get(geneRow[g]), true);
+    }
+    for (const g of DOWN_GENES) {
+      expect(fc.get(geneRow[g]) < -1.0, true);
+      expect(sig.get(geneRow[g]), true);
+    }
+    for (const g of UNCHANGED_GENES) {
+      expect(Math.abs(fc.get(geneRow[g])) < 0.5, true);
+      expect(sig.get(geneRow[g]), false);
+    }
+  });
+});

package/src/tests/fragpipe-parser.ts

@@ -0,0 +1,147 @@
+import {category, test, expect} from '@datagrok-libraries/test/src/test';
+import {parseFragPipeText} from '../parsers/fragpipe-parser';
+import {SEMTYPE} from '../utils/proteomics-types';
+
+/** Builds a minimal FragPipe combined_protein.tsv string. */
+function makeTsv(rows: string[][], headers: string[]): string {
+  return [headers.join('\t'), ...rows.map((r) => r.join('\t'))].join('\n');
+}
+
+const BASE_HEADERS = [
+  'Protein', 'Protein ID', 'Entry Name', 'Gene', 'Length', 'Organism', 'Protein Description',
+  'Sample1 Spectral Count', 'Sample1 Intensity', 'Sample1 MaxLFQ Intensity',
+  'Sample2 Spectral Count', 'Sample2 Intensity', 'Sample2 MaxLFQ Intensity',
+];
+
+function baseRow(proteinId: string, gene: string,
+  s1Int: string, s1Lfq: string, s2Int: string, s2Lfq: string): string[] {
+  return [
+    `sp|${proteinId}|${gene}_HUMAN`, proteinId, `${gene}_HUMAN`, gene, '500', 'Homo sapiens', `${gene} protein`,
+    '12', s1Int, s1Lfq, '15', s2Int, s2Lfq,
+  ];
+}
+
+category('FragPipe', () => {
+  test('parses standard rows', async () => {
+    const tsv = makeTsv([
+      baseRow('P12345', 'BRCA1', '10000', '12000', '20000', '24000'),
+      baseRow('Q67890', 'TP53', '30000', '36000', '40000', '48000'),
+    ], BASE_HEADERS);
+    const df = await parseFragPipeText(tsv);
+    expect(df.rowCount, 2);
+  });
+
+  test('filters contam_ rows', async () => {
+    const tsv = makeTsv([
+      baseRow('P12345', 'BRCA1', '10000', '12000', '20000', '24000'),
+      baseRow('contam_P99999', 'KRT1', '30000', '36000', '40000', '48000'),
+    ], BASE_HEADERS);
+    const df = await parseFragPipeText(tsv);
+    expect(df.rowCount, 1);
+    expect(df.col('Protein ID')!.get(0), 'P12345');
+  });
+
+  test('filters rev_ rows', async () => {
+    const tsv = makeTsv([
+      baseRow('P12345', 'BRCA1', '10000', '12000', '20000', '24000'),
+      baseRow('rev_P99999', 'DECOY', '30000', '36000', '40000', '48000'),
+    ], BASE_HEADERS);
+    const df = await parseFragPipeText(tsv);
+    expect(df.rowCount, 1);
+  });
+
+  test('filters CON__/REV__ rows for MaxQuant-style FASTAs', async () => {
+    const tsv = makeTsv([
+      baseRow('P12345', 'BRCA1', '10000', '12000', '20000', '24000'),
+      baseRow('CON__P99999', 'KRT1', '30000', '36000', '40000', '48000'),
+      baseRow('REV__P88888', 'FAKE1', '50000', '60000', '70000', '80000'),
+    ], BASE_HEADERS);
+    const df = await parseFragPipeText(tsv);
+    expect(df.rowCount, 1);
+  });
+
+  test('assigns semantic types', async () => {
+    const tsv = makeTsv([
+      baseRow('P12345', 'BRCA1', '10000', '12000', '20000', '24000'),
+    ], BASE_HEADERS);
+    const df = await parseFragPipeText(tsv);
+    expect(df.col('Protein ID')?.semType, SEMTYPE.PROTEIN_ID);
+    expect(df.col('Gene')?.semType, SEMTYPE.GENE_SYMBOL);
+    // Only the chosen primary quant (MaxLFQ) gets SEMTYPE.INTENSITY. Redundant
+    // bare-Intensity / Razor columns are intentionally NOT tagged so they don't
+    // show up in downstream intensity-column pickers.
+    expect(df.col('Sample1 MaxLFQ Intensity')?.semType, SEMTYPE.INTENSITY);
+  });
+
+  test('prefers MaxLFQ for log2 transform', async () => {
+    const tsv = makeTsv([
+      baseRow('P12345', 'BRCA1', '1024', '2048', '4096', '8192'),
+    ], BASE_HEADERS);
+    const df = await parseFragPipeText(tsv);
+    // MaxLFQ columns get log2-transformed; bare Intensity ones do not
+    expect(df.col('log2(Sample1 MaxLFQ Intensity)') !== null, true);
+    expect(df.col('log2(Sample2 MaxLFQ Intensity)') !== null, true);
+    expect(df.col('log2(Sample1 Intensity)'), null);
+    const log2Col = df.col('log2(Sample1 MaxLFQ Intensity)')!;
+    expect(Math.abs(log2Col.get(0)! - 11.0) < 0.001, true);
+  });
+
+  test('falls back to bare Intensity when no MaxLFQ present', async () => {
+    const headers = [
+      'Protein', 'Protein ID', 'Gene',
+      'Sample1 Spectral Count', 'Sample1 Intensity',
+      'Sample2 Spectral Count', 'Sample2 Intensity',
+    ];
+    const tsv = makeTsv([
+      ['sp|P12345|BRCA1_HUMAN', 'P12345', 'BRCA1', '12', '1024', '15', '4096'],
+    ], headers);
+    const df = await parseFragPipeText(tsv);
+    expect(df.col('log2(Sample1 Intensity)') !== null, true);
+    expect(df.col('log2(Sample2 Intensity)') !== null, true);
+    const log2Col = df.col('log2(Sample1 Intensity)')!;
+    expect(Math.abs(log2Col.get(0)! - 10.0) < 0.001, true);
+  });
+
+  test('zero intensity produces FLOAT_NULL in log2', async () => {
+    const tsv = makeTsv([
+      baseRow('P12345', 'BRCA1', '0', '0', '4096', '8192'),
+    ], BASE_HEADERS);
+    const df = await parseFragPipeText(tsv);
+    const log2Col = df.col('log2(Sample1 MaxLFQ Intensity)')!;
+    expect(log2Col.isNone(0), true);
+  });
+
+  test('primary protein ID extracted from semicolon-delimited', async () => {
+    const tsv = makeTsv([
+      ['sp|P12345|BRCA1_HUMAN', 'P12345;Q67890', 'BRCA1_HUMAN', 'BRCA1;BRCA2', '500',
+        'Homo sapiens', 'BRCA1 protein',
+        '12', '10000', '12000', '15', '20000', '24000'],
+    ], BASE_HEADERS);
+    const df = await parseFragPipeText(tsv);
+    const primaryId = df.col('Primary Protein ID');
+    expect(primaryId !== null, true);
+    if (primaryId)
+      expect(primaryId.get(0), 'P12345');
+    const primaryGene = df.col('Primary Gene Name');
+    expect(primaryGene !== null, true);
+    if (primaryGene)
+      expect(primaryGene.get(0), 'BRCA1');
+  });
+
+  test('proteomics.source tag set to fragpipe', async () => {
+    const tsv = makeTsv([
+      baseRow('P12345', 'BRCA1', '10000', '12000', '20000', '24000'),
+    ], BASE_HEADERS);
+    const df = await parseFragPipeText(tsv);
+    expect(df.getTag('proteomics.source'), 'fragpipe');
+  });
+
+  test('intensity columns survive as raw plus log2 pair', async () => {
+    const tsv = makeTsv([
+      baseRow('P12345', 'BRCA1', '10000', '12000', '20000', '24000'),
+    ], BASE_HEADERS);
+    const df = await parseFragPipeText(tsv);
+    expect(df.col('Sample1 MaxLFQ Intensity') !== null, true);
+    expect(df.col('log2(Sample1 MaxLFQ Intensity)') !== null, true);
+  });
+});

package/src/tests/gene-label-resolver.ts

@@ -0,0 +1,387 @@
+import * as DG from 'datagrok-api/dg';
+import * as grok from 'datagrok-api/grok';
+import {category, test, expect} from '@datagrok-libraries/test/src/test';
+import {SEMTYPE} from '../utils/proteomics-types';
+import {
+  resolveGeneLabels, STORE_GENE_LABELS, SCHEMA_V_GENE_LABELS,
+  detectSpecies, isEnsemblEligible, isPredicted,
+  extractReadableDescription, applyMarkerRules,
+  lookupEnsemblBatch, type EnsemblEntry,
+} from '../utils/gene-label-resolver';
+import {parseMaxQuantText} from '../parsers/maxquant-parser';
+import {parseFragPipeText} from '../parsers/fragpipe-parser';
+import {parseSpectronautCandidatesText} from '../parsers/spectronaut-candidates-parser';
+import {parseSpectronautText} from '../parsers/spectronaut-parser';
+
+/** Build a fake Response that the test mock for grok.dapi.fetchProxy can return. */
+function makeResponse(body: any, opts: {status?: number; retryAfter?: string} = {}): Response {
+  const status = opts.status ?? 200;
+  const headers = new Headers();
+  if (opts.retryAfter != null) headers.set('Retry-After', opts.retryAfter);
+  // node-fetch / browser Response constructors accept (BodyInit, ResponseInit).
+  return new Response(body == null ? null : JSON.stringify(body), {status, headers});
+}
+
+/** Replaces grok.dapi.fetchProxy with `fn` for the duration of `run`, then
+ * restores the original. Patches BOTH the dapi instance (own property) and its
+ * shared prototype: older Datagrok exposes `fetchProxy` on the prototype, while
+ * newer builds define it as an own/bound property on the instance — where a
+ * prototype-only patch is invisible to the source's `grok.dapi.fetchProxy`
+ * call and the real network gets hit (CI "latest" failure mode). Patching both
+ * covers either shape. (See project memory reference_dapi_fresh_instance_patch.) */
+async function withFetchProxy(
+  fn: (url: string, init?: RequestInit) => Promise<Response>,
+  run: () => Promise<void>,
+): Promise<void> {
+  const dapi: any = grok.dapi;
+  const proto = Object.getPrototypeOf(dapi);
+  const hadOwn = Object.prototype.hasOwnProperty.call(dapi, 'fetchProxy');
+  const origOwn = hadOwn ? dapi.fetchProxy : undefined;
+  const origProto = proto.fetchProxy;
+  dapi.fetchProxy = fn;
+  proto.fetchProxy = fn;
+  try {
+    await run();
+  } finally {
+    if (hadOwn) dapi.fetchProxy = origOwn;
+    else delete dapi.fetchProxy;
+    proto.fetchProxy = origProto;
+  }
+}
+
+/** Replaces grok.dapi.userDataStorage methods for the duration of `run`. */
+async function withUserDataStorage(
+  store: Map<string, any>,
+  run: () => Promise<void>,
+): Promise<void> {
+  const uds: any = grok.dapi.userDataStorage;
+  const proto = Object.getPrototypeOf(uds);
+  const origGet = proto.get;
+  const origPut = proto.put;
+  proto.get = async (key: string) => store.get(key) ?? null;
+  proto.put = async (key: string, value: any) => { store.set(key, value); };
+  try {
+    await run();
+  } finally {
+    proto.get = origGet;
+    proto.put = origPut;
+  }
+}
+
+/** Replaces grok.shell.warning with a no-op for the duration of `run` and
+ * returns the captured warnings. */
+async function captureWarnings(run: () => Promise<void>): Promise<string[]> {
+  const captured: string[] = [];
+  const shell: any = grok.shell;
+  const original = shell.warning;
+  shell.warning = (msg: string) => { captured.push(msg); };
+  try {
+    await run();
+  } finally {
+    shell.warning = original;
+  }
+  return captured;
+}
+
+category('Proteomics: 14-01', () => {
+  test('geneLabelResolverSemTypes: SEMTYPE constants are the locked strings', async () => {
+    expect(SEMTYPE.DISPLAY_NAME, 'Proteomics-DisplayName');
+    expect(SEMTYPE.SOURCE_ID, 'Proteomics-SourceId');
+    expect(SEMTYPE.NUMERATOR_MEAN, 'Proteomics-NumeratorMean');
+    expect(SEMTYPE.DENOMINATOR_MEAN, 'Proteomics-DenominatorMean');
+    const all = new Set([
+      SEMTYPE.DISPLAY_NAME, SEMTYPE.SOURCE_ID,
+      SEMTYPE.NUMERATOR_MEAN, SEMTYPE.DENOMINATOR_MEAN,
+      SEMTYPE.PROTEIN_ID, SEMTYPE.GENE_SYMBOL, SEMTYPE.INTENSITY,
+      SEMTYPE.LOG2FC, SEMTYPE.P_VALUE, SEMTYPE.SUBCELLULAR_LOCATION,
+    ]);
+    expect(all.size, 10);
+  });
+
+  test('geneLabelResolverDetectorMirror: SEMTYPE values are valid Column.semType strings', async () => {
+    const df = DG.DataFrame.fromColumns([
+      DG.Column.fromStrings('Display Name', ['Myh7†', 'Tnnt3']),
+      DG.Column.fromStrings('Source ID', ['ENSRNOG0001', '']),
+      DG.Column.fromFloat32Array('Numerator Mean', new Float32Array([1.0, 2.0])),
+      DG.Column.fromFloat32Array('Denominator Mean', new Float32Array([1.5, 2.5])),
+    ]);
+    df.col('Display Name')!.semType = SEMTYPE.DISPLAY_NAME;
+    df.col('Source ID')!.semType = SEMTYPE.SOURCE_ID;
+    df.col('Numerator Mean')!.semType = SEMTYPE.NUMERATOR_MEAN;
+    df.col('Denominator Mean')!.semType = SEMTYPE.DENOMINATOR_MEAN;
+    expect(df.col('Display Name')!.semType, 'Proteomics-DisplayName');
+    expect(df.col('Source ID')!.semType, 'Proteomics-SourceId');
+    expect(df.col('Numerator Mean')!.semType, 'Proteomics-NumeratorMean');
+    expect(df.col('Denominator Mean')!.semType, 'Proteomics-DenominatorMean');
+  });
+
+  test('detectSpecies: maps prefixes per CK-omics species table', async () => {
+    expect(detectSpecies('ENSG00000123'), 'homo_sapiens');
+    expect(detectSpecies('ENSMUSG00000456'), 'mus_musculus');
+    expect(detectSpecies('MGP_C57BL6NJ_G0000001'), 'mus_musculus');
+    expect(detectSpecies('ENSRNOG00000789'), 'rattus_norvegicus');
+    expect(detectSpecies('ENSRNO00000001'), 'rattus_norvegicus');
+    expect(detectSpecies('ENSDARG00000222'), 'danio_rerio');
+    expect(detectSpecies('LOC123456'), null);
+    expect(detectSpecies('RGD7890'), null);
+    expect(detectSpecies('AABR07012345'), null);
+  });
+
+  test('isEnsemblEligible: filters LOC/RGD/AABR per CK-omics line 933', async () => {
+    expect(isEnsemblEligible('ENSG00000001'), true);
+    expect(isEnsemblEligible('ENSMUSG00000123'), true);
+    expect(isEnsemblEligible('ENSRNOG00000456'), true);
+    expect(isEnsemblEligible('ENSDARG00000789'), true);
+    expect(isEnsemblEligible('MGP_C57BL6NJ_G0000001'), true);
+    expect(isEnsemblEligible('LOC123456'), false);
+    expect(isEnsemblEligible('RGD789'), false);
+    expect(isEnsemblEligible('AABR07012345'), false);
+  });
+
+  test('isPredicted: locked CK-omics prefix list', async () => {
+    expect(isPredicted('ENSRNOG00000001'), true);
+    expect(isPredicted('LOC987'), true);
+    expect(isPredicted('AABR07'), true);
+    expect(isPredicted('Myh7'), false);
+    expect(isPredicted('Tnnt3'), false);
+  });
+
+  test('extractReadableDescription: strips Predicted-to prefixes and species suffixes', async () => {
+    expect(extractReadableDescription('Predicted to enable actin binding [Rattus norvegicus]'),
+      'Actin binding');
+    expect(extractReadableDescription('Predicted to be involved in transport. Additional sentence.'),
+      'Transport');
+    expect(extractReadableDescription('Myosin heavy chain_RAT'), 'Myosin heavy chain');
+    expect(extractReadableDescription(''), null);
+    expect(extractReadableDescription(null), null);
+    expect(extractReadableDescription('uncharacterized protein'), null);
+  });
+
+  test('applyMarkerRules: appends * and † per CK-omics line 1011', async () => {
+    expect(applyMarkerRules('Myh7', false, true), 'Myh7†');
+    expect(applyMarkerRules('Myh7', true, true), 'Myh7*†');
+    expect(applyMarkerRules('LOC123', false, true), 'LOC123†');
+    expect(applyMarkerRules('Tnnt3', false, false), 'Tnnt3');
+    expect(applyMarkerRules('Tnnt3', true, false), 'Tnnt3*');
+  });
+
+  test('lookupEnsemblBatch: POSTs ids and parses response', async () => {
+    let capturedUrl = '';
+    let capturedInit: RequestInit | undefined;
+    await withFetchProxy(
+      async (url, init) => {
+        capturedUrl = url;
+        capturedInit = init;
+        return makeResponse({
+          'ENSRNOG00000001': {external_name: 'Myh7', description: 'Myosin heavy chain 7'},
+          'ENSRNOG00000002': null,
+        });
+      },
+      async () => {
+        const out = await lookupEnsemblBatch(['ENSRNOG00000001', 'ENSRNOG00000002']);
+        expect(capturedUrl, 'https://rest.ensembl.org/lookup/id');
+        expect(capturedInit?.method, 'POST');
+        const body = JSON.parse((capturedInit?.body as string) ?? '{}');
+        expect(Array.isArray(body.ids), true);
+        expect(body.ids.length, 2);
+        expect(out.size, 1);
+        expect(out.get('ENSRNOG00000001')?.external_name, 'Myh7');
+      },
+    );
+  });
+
+  test('lookupEnsemblBatch: retries once on 429 with Retry-After', async () => {
+    let calls = 0;
+    await withFetchProxy(
+      async () => {
+        calls++;
+        if (calls === 1) return makeResponse(null, {status: 429, retryAfter: '0'});
+        return makeResponse({'ENSG00000001': {external_name: 'TP53'}});
+      },
+      async () => {
+        const out = await lookupEnsemblBatch(['ENSG00000001']);
+        expect(calls, 2);
+        expect(out.get('ENSG00000001')?.external_name, 'TP53');
+      },
+    );
+  });
+
+  test('resolveGeneLabels: no-op path still creates Display Name + Source ID columns', async () => {
+    const df = DG.DataFrame.fromColumns([
+      DG.Column.fromStrings('Protein ID', ['P12345', 'Q67890', 'O11111']),
+      DG.Column.fromStrings('Gene name', ['Myh7', 'Tnnt3', 'Actb']),
+    ]);
+    df.col('Gene name')!.semType = SEMTYPE.GENE_SYMBOL;
+    df.col('Protein ID')!.semType = SEMTYPE.PROTEIN_ID;
+    await withFetchProxy(async () => { throw new Error('should not fetch'); }, async () => {
+      await resolveGeneLabels(df);
+    });
+    const dn = df.col('Display Name');
+    const sid = df.col('Source ID');
+    expect(dn != null, true);
+    expect(sid != null, true);
+    expect(dn!.semType, 'Proteomics-DisplayName');
+    expect(sid!.semType, 'Proteomics-SourceId');
+    expect(dn!.get(0), 'Myh7');
+    expect(dn!.get(1), 'Tnnt3');
+    expect(sid!.get(0), '');
+  });
+
+  test('resolveGeneLabels: LOC/RGD/AABR keep raw ID + †, never sent to Ensembl', async () => {
+    const df = DG.DataFrame.fromColumns([
+      DG.Column.fromStrings('Gene name', ['LOC123', 'RGD456', 'AABR789']),
+    ]);
+    df.col('Gene name')!.semType = SEMTYPE.GENE_SYMBOL;
+    let postCount = 0;
+    await withUserDataStorage(new Map(), async () => {
+      await withFetchProxy(
+        async () => { postCount++; return makeResponse({}); },
+        async () => {
+          await resolveGeneLabels(df);
+        },
+      );
+    });
+    expect(postCount, 0);
+    expect(df.col('Display Name')!.get(0), 'LOC123†');
+    expect(df.col('Display Name')!.get(1), 'RGD456†');
+    expect(df.col('Display Name')!.get(2), 'AABR789†');
+    expect(df.col('Source ID')!.get(0), 'LOC123');
+    expect(df.col('Source ID')!.get(1), 'RGD456');
+    expect(df.col('Source ID')!.get(2), 'AABR789');
+  });
+
+  test('resolveGeneLabels: disambiguates duplicates with (Source ID) suffix and warns', async () => {
+    const df = DG.DataFrame.fromColumns([
+      DG.Column.fromStrings('Gene name', ['ENSRNOG00000001', 'ENSRNOG00000002', 'Actb']),
+    ]);
+    df.col('Gene name')!.semType = SEMTYPE.GENE_SYMBOL;
+    const warnings = await captureWarnings(async () => {
+      await withUserDataStorage(new Map(), async () => {
+        await withFetchProxy(
+          async () => makeResponse({
+            'ENSRNOG00000001': {external_name: 'Myh7'},
+            'ENSRNOG00000002': {external_name: 'Myh7'},
+          }),
+          async () => {
+            await resolveGeneLabels(df);
+          },
+        );
+      });
+    });
+    expect(df.col('Display Name')!.get(0), 'Myh7† (ENSRNOG00000001)');
+    expect(df.col('Display Name')!.get(1), 'Myh7† (ENSRNOG00000002)');
+    expect(df.col('Display Name')!.get(2), 'Actb');
+    const dupWarn = warnings.find((w) => w.includes('duplicate gene names'));
+    expect(dupWarn != null, true);
+  });
+
+  test('resolveGeneLabels: cache short-circuits second call', async () => {
+    const store = new Map<string, any>();
+    let postCount = 0;
+    const mockFetch = async () => {
+      postCount++;
+      return makeResponse({'ENSRNOG00000001': {external_name: 'Myh7'}});
+    };
+
+    const df1 = DG.DataFrame.fromColumns([
+      DG.Column.fromStrings('Gene name', ['ENSRNOG00000001']),
+    ]);
+    df1.col('Gene name')!.semType = SEMTYPE.GENE_SYMBOL;
+
+    const df2 = DG.DataFrame.fromColumns([
+      DG.Column.fromStrings('Gene name', ['ENSRNOG00000001']),
+    ]);
+    df2.col('Gene name')!.semType = SEMTYPE.GENE_SYMBOL;
+
+    await withUserDataStorage(store, async () => {
+      await withFetchProxy(mockFetch, async () => {
+        await resolveGeneLabels(df1);
+        const firstCount = postCount;
+        await resolveGeneLabels(df2);
+        expect(postCount, firstCount); // second call must NOT POST again
+      });
+    });
+    expect(df2.col('Display Name')!.get(0), 'Myh7†');
+    // Cache write happened against our store under the correct schema key.
+    const cached = store.get(STORE_GENE_LABELS) ?? {};
+    expect(cached['__schema_v'], SCHEMA_V_GENE_LABELS);
+  });
+
+  test('resolveGeneLabels: degrades gracefully on fetchProxy throw', async () => {
+    const df = DG.DataFrame.fromColumns([
+      DG.Column.fromStrings('Gene name', ['ENSRNOG00000001', 'Actb']),
+    ]);
+    df.col('Gene name')!.semType = SEMTYPE.GENE_SYMBOL;
+    const warnings = await captureWarnings(async () => {
+      await withUserDataStorage(new Map(), async () => {
+        await withFetchProxy(async () => { throw new Error('network down'); }, async () => {
+          await resolveGeneLabels(df);
+        });
+      });
+    });
+    expect(df.col('Display Name')!.get(0), 'ENSRNOG00000001†');
+    expect(df.col('Display Name')!.get(1), 'Actb');
+    expect(df.col('Source ID')!.get(0), 'ENSRNOG00000001');
+    const failWarn = warnings.find((w) => w.includes('Ensembl gene-label resolution unavailable'));
+    expect(failWarn != null, true);
+  });
+
+  test('parser integration: every parser produces Display Name + Source ID columns', async () => {
+    // The 4 sync-text parsers all go through the resolver before return. Spectronaut
+    // streaming has its own test elsewhere; the text path shares finalizeSpectronaut
+    // with the stream path so we cover both via parseSpectronautText.
+    const mq = await parseMaxQuantText([
+      'Protein IDs\tMajority protein IDs\tGene names\tPotential contaminant\tReverse\t' +
+        'Only identified by site\tLFQ intensity Sample1\tLFQ intensity Sample2\tiBAQ',
+      'P12345\tP12345\tBRCA1\t\t\t\t1000\t2000\t500',
+    ].join('\n'));
+    expect(mq.col('Display Name')?.semType, 'Proteomics-DisplayName');
+    expect(mq.col('Source ID')?.semType, 'Proteomics-SourceId');
+
+    const fp = await parseFragPipeText([
+      'Protein\tGene\tDescription\tMaxLFQ Intensity Sample1\tMaxLFQ Intensity Sample2',
+      'P12345\tBRCA1\tProtein BRCA1\t1000\t2000',
+    ].join('\n'));
+    expect(fp.col('Display Name')?.semType, 'Proteomics-DisplayName');
+    expect(fp.col('Source ID')?.semType, 'Proteomics-SourceId');
+
+    const sc = await parseSpectronautCandidatesText([
+      'PG.ProteinGroups\tPG.Genes\tComparison (group1/group2)\tAVG Log2 Ratio\tQvalue\tPvalue',
+      'P12345\tBRCA1\tA / B\t2.5\t0.001\t0.0005',
+    ].join('\n'));
+    expect(sc.col('Display Name')?.semType, 'Proteomics-DisplayName');
+    expect(sc.col('Source ID')?.semType, 'Proteomics-SourceId');
+
+    const sp = await parseSpectronautText([
+      'PG.ProteinGroups\tPG.Genes\tR.Condition\tR.Replicate\tR.FileName\tPG.Qvalue\tPG.Quantity',
+      'P12345\tBRCA1\tCtrl\t1\tF1\t0.0001\t1000',
+      'P12345\tBRCA1\tCtrl\t2\tF2\t0.0001\t1200',
+      'P12345\tBRCA1\tTrt\t1\tF3\t0.0001\t2000',
+      'P12345\tBRCA1\tTrt\t2\tF4\t0.0001\t2400',
+    ].join('\n'));
+    expect(sp.col('Display Name')?.semType, 'Proteomics-DisplayName');
+    expect(sp.col('Source ID')?.semType, 'Proteomics-SourceId');
+  });
+
+  test('resolveGeneLabels: three-level fallback uses description when external_name missing', async () => {
+    const df = DG.DataFrame.fromColumns([
+      DG.Column.fromStrings('Gene name', ['ENSRNOG00000099']),
+    ]);
+    df.col('Gene name')!.semType = SEMTYPE.GENE_SYMBOL;
+    await withUserDataStorage(new Map(), async () => {
+      await withFetchProxy(
+        async () => makeResponse({
+          'ENSRNOG00000099': {description: 'Predicted to enable kinase activity [Rattus norvegicus]'},
+        }),
+        async () => { await resolveGeneLabels(df); },
+      );
+    });
+    // pickBestName uses entry.description.split('[')[0].trim() → 'Predicted to enable kinase activity'
+    // which still starts with the literal 'Predicted to' — but pickBestName only rejects on the locked
+    // PREDICTED_PREFIXES list (ENSRNOG, etc.), not on free-text 'Predicted to'. CK-omics behavior:
+    // such a candidate IS accepted by pickBestName; only the readable-description fallback runs the
+    // 'Predicted to ...' regex cleanup. Asserting the verbatim CK-omics behavior here.
+    expect(df.col('Display Name')!.get(0), 'Predicted to enable kinase activity†');
+    expect(df.col('Source ID')!.get(0), 'ENSRNOG00000099');
+  });
+});