@datagrok/proteomics 1.0.0 → 1.2.0

package/src/panels/protein-focus.ts

@@ -0,0 +1,63 @@
+import * as grok from 'datagrok-api/grok';
+import * as DG from 'datagrok-api/dg';
+
+import {findColumn} from '../utils/column-detection';
+import {SEMTYPE} from '../utils/proteomics-types';
+
+const PROTEIN_ID_HINTS =
+  ['primary protein id', 'pg.proteingroups', 'protein id', 'uniprot', 'accession'];
+
+/**
+ * Selects a protein row so the semType-registered UniProt panel populates in the
+ * context panel, opens the context panel, and (best-effort) expands the UniProt
+ * pane so the result is actually visible rather than one click away.
+ *
+ * Shared by two callers: every import handler passes the default row 0 (a small
+ * "it works" cue the moment a file opens), and the demo passes its top
+ * differential-expression hit. No-op if the table has no recognizable protein-id
+ * column, so it's safe to call after any import.
+ */
+export function focusProtein(df: DG.DataFrame, rowIdx: number = 0): void {
+  if (df.rowCount === 0 || rowIdx < 0 || rowIdx >= df.rowCount) return;
+  const idCol = findColumn(df, SEMTYPE.PROTEIN_ID, PROTEIN_ID_HINTS);
+  if (!idCol) return;
+  df.currentCell = df.cell(rowIdx, idCol.name);
+  grok.shell.windows.showContextPanel = true;
+  void expandUniProtPane();
+}
+
+/**
+ * Best-effort: expands the UniProt widget in the semantic context panel so the
+ * protein result is visible immediately.
+ *
+ * There is no supported API to expand a semantic sub-accordion pane from a
+ * package function — `onAccordionConstructed` only surfaces the top-level
+ * `Actions` accordion, while the UniProt widget is rendered inside the platform's
+ * semantic panel — so this reaches into the context-panel DOM. It is EXPAND-ONLY
+ * (it clicks a pane header only when it lacks the `expanded` class, so it never
+ * collapses a pane the user already opened) and fully guarded: if the platform
+ * DOM ever changes shape, the panel simply stays collapsed, exactly as if this
+ * helper were absent. The panel content itself is populated either way by the
+ * current-cell selection in `focusProtein`.
+ */
+async function expandUniProtPane(): Promise<void> {
+  const wanted = ['Proteomics', 'UniProt']; // group pane, then the widget inside it
+  for (let attempt = 0; attempt < 12; attempt++) {
+    await new Promise((r) => setTimeout(r, 250));
+    try {
+      const acc = document.querySelector('[d4-title="semantic meta.Proteomics-ProteinId"]');
+      if (!acc) continue;
+      let allExpanded = true;
+      for (const name of wanted) {
+        const header = Array.from(acc.querySelectorAll('.d4-accordion-pane-header'))
+          .find((h) => h.textContent?.trim() === name) as HTMLElement | undefined;
+        if (!header) { allExpanded = false; continue; }
+        if (!header.classList.contains('expanded')) {
+          header.click(); // reveals the child pane on a later iteration
+          allExpanded = false;
+        }
+      }
+      if (allExpanded) return;
+    } catch { /* best-effort presentation only — leave collapsed on any DOM change */ }
+  }
+}

package/src/panels/published-analysis-panel.ts

@@ -0,0 +1,151 @@
+import * as grok from 'datagrok-api/grok';
+import * as ui from 'datagrok-api/ui';
+import * as DG from 'datagrok-api/dg';
+
+import {
+  META_COLUMNS, PUBLISHED_TAGS, PublishedMetadata,
+  isPublished, getPublishedMetadata, buildMailtoUrl,
+} from '../publishing/publish-state';
+import {findHostDataFrameForProtein} from './uniprot-panel';
+import {getGroups} from '../analysis/experiment-setup';
+
+/**
+ * Reviewer-side audit context panel. Opens when a reviewer clicks a protein
+ * row in a published Project. Surfaces the metadata the analyst stamped at
+ * publish time (DE method, thresholds, group names, target, share date, sharer
+ * name) plus PUB-13 mailto button. First-line `isPublished(df)` guard ensures
+ * it does NOT render on the analyst's live working DataFrame.
+ *
+ * Reads metadata column FIRST, tag SECOND per Pitfall 3 — the column survives
+ * the serializer; the tag is a defensive secondary. All user-facing strings
+ * pass the Pitfall 14 biologist-jargon audit. Imports {@link buildMailtoUrl}
+ * from `../publishing/publish-state` rather than `../publishing/share-dialog`
+ * (B-1 fix — avoids the wave-2 → wave-4 dependency cycle).
+ */
+
+/** Human-friendly expansion of the DE method ID for the audit "Method" row.
+ *  CONTEXT.md domain pin: narrate what an expert would assume known. */
+function methodLabel(method: string): string {
+  switch (method) {
+    case 'limma': return 'limma — moderated t-test';
+    case 'deqms': return 'DEqMS — peptide-count-aware moderated t-test';
+    case 't-test': return 'Welch t-test';
+    case 'spectronaut': return 'Spectronaut Candidates (pre-computed DE)';
+    default: return method || '(unknown method)';
+  }
+}
+
+function dateSlice(d: Date | string | number | null | undefined): string {
+  if (d == null) return 'unknown date';
+  try {
+    if (d instanceof Date) {
+      if (Number.isNaN(d.getTime())) return 'unknown date';
+      return d.toISOString().slice(0, 10);
+    }
+    const parsed = new Date(d);
+    if (Number.isNaN(parsed.getTime())) return 'unknown date';
+    return parsed.toISOString().slice(0, 10);
+  } catch {
+    return 'unknown date';
+  }
+}
+
+function fieldRow(label: string, value: string): HTMLDivElement {
+  const labelEl = ui.divText(label);
+  labelEl.style.fontWeight = '600';
+  labelEl.style.fontSize = '12px';
+  labelEl.style.color = '#666';
+  const valueEl = ui.divText(value);
+  valueEl.style.marginBottom = '8px';
+  const row = ui.div([labelEl, valueEl]);
+  row.style.marginBottom = '6px';
+  return row;
+}
+
+function readSharerEmail(df: DG.DataFrame, meta: PublishedMetadata): string | null {
+  if (meta.publishedByEmail != null && meta.publishedByEmail !== '')
+    return meta.publishedByEmail;
+  try {
+    const col = df.col(META_COLUMNS.PUBLISHED_BY_EMAIL);
+    if (col != null) {
+      const v = col.get(0);
+      if (v != null && v !== '') return String(v);
+    }
+  } catch { /* fall through */ }
+  try {
+    const t = df.getTag(PUBLISHED_TAGS.PUBLISHED_BY_EMAIL);
+    if (t) return t;
+  } catch { /* fall through */ }
+  return null;
+}
+
+export function publishedAnalysisPanel(proteinId: string): DG.Widget {
+  const df = findHostDataFrameForProtein(proteinId);
+  if (df == null) return new DG.Widget(ui.div());
+  if (!isPublished(df)) return new DG.Widget(ui.div());
+
+  const meta = getPublishedMetadata(df);
+  if (meta == null)
+    return new DG.Widget(ui.divText('Shared analysis metadata unavailable. Ask the sharer to re-share.'));
+
+  const body = ui.div();
+  body.style.padding = '8px 4px';
+
+  if (meta.supersededBy != null && meta.supersededBy !== '') {
+    const newerLink = ui.link('Newer version available — open it', async () => {
+      try {
+        const newer = await grok.dapi.projects.find(meta.supersededBy!);
+        await newer.open();
+      } catch (e) {
+        grok.shell.warning(`Could not open the newer version: ${(e as Error)?.message ?? e}`);
+      }
+    });
+    const banner = ui.div([newerLink]);
+    banner.style.padding = '8px';
+    banner.style.marginBottom = '10px';
+    banner.style.backgroundColor = '#fff8dc';
+    banner.style.borderRadius = '4px';
+    body.appendChild(banner);
+  }
+
+  body.appendChild(ui.h2('Shared analysis details'));
+
+  const groups = getGroups(df);
+  const comparison = groups != null
+    ? `${groups.group2.name} vs ${groups.group1.name}`
+    : 'unavailable';
+
+  const fcFold = Number.isFinite(meta.fcThreshold) ? Math.pow(2, meta.fcThreshold) : NaN;
+  const fcLabel = Number.isFinite(meta.fcThreshold)
+    ? `log2(${meta.fcThreshold}) (${Number.isFinite(fcFold) ? fcFold.toFixed(2) : 'NaN'}-fold)`
+    : '(unknown)';
+  const pLabel = Number.isFinite(meta.pThreshold)
+    ? `${meta.pThreshold} (FDR-adjusted)`
+    : '(unknown)';
+
+  body.appendChild(fieldRow('Target', meta.target || '(unknown)'));
+  body.appendChild(fieldRow('Shared', dateSlice(meta.publishedAt)));
+  body.appendChild(fieldRow('Shared by', meta.publishedBy || '(unknown)'));
+  body.appendChild(fieldRow('Method', methodLabel(meta.deMethod)));
+  body.appendChild(fieldRow('Comparison', comparison));
+  body.appendChild(fieldRow('Fold-change cutoff', fcLabel));
+  body.appendChild(fieldRow('p-value cutoff', pLabel));
+
+  const sharerEmail = readSharerEmail(df, meta);
+  if (sharerEmail != null) {
+    const projectName = df.name || 'shared analysis';
+    const mailtoUrl = buildMailtoUrl({
+      sharerEmail,
+      sharerName: meta.publishedBy || 'colleague',
+      projectName,
+      publishedDateStr: dateSlice(meta.publishedAt),
+    });
+    const mailLink = ui.link('Request re-run with different parameters', mailtoUrl);
+    (mailLink as HTMLAnchorElement).href = mailtoUrl;
+    const mailRow = ui.div([mailLink]);
+    mailRow.style.marginTop = '12px';
+    body.appendChild(mailRow);
+  }
+
+  return new DG.Widget(body);
+}

package/src/panels/uniprot-panel.ts

@@ -0,0 +1,349 @@
+import * as grok from 'datagrok-api/grok';
+import * as ui from 'datagrok-api/ui';
+import * as DG from 'datagrok-api/dg';
+import {fetchUniProtEntry} from '../analysis/subcellular-location';
+import {getGroups, GroupAssignment} from '../analysis/experiment-setup';
+import {findColumn} from '../utils/column-detection';
+import {SEMTYPE, DIRECTION_COLORS_BASE} from '../utils/proteomics-types';
+
+
+/** UniProt REST API response types */
+interface UniProtEntry {
+  accession?: string;
+  proteinDescription?: {
+    recommendedName?: { fullName?: { value?: string } };
+    submissionNames?: Array<{ fullName?: { value?: string } }>;
+  };
+  genes?: Array<{ geneName?: { value?: string } }>;
+  organism?: { scientificName?: string; commonName?: string };
+  comments?: Array<{
+    commentType?: string;
+    texts?: Array<{ value?: string }>;
+  }>;
+  uniProtKBCrossReferences?: Array<{
+    database?: string;
+    id?: string;
+    properties?: Array<{ key?: string; value?: string }>;
+  }>;
+}
+
+interface GoTerms {
+  mf: string[];
+  bp: string[];
+  cc: string[];
+}
+
+
+/**
+ * Parse a UniProt accession from a raw protein ID value.
+ * Handles:
+ *   - Bare accessions: "P04637"
+ *   - UniProt format prefixes: "sp|P04637|P53_HUMAN" or "tr|Q67890|..."
+ *   - Semicolon-delimited protein groups: "P12345;Q67890" (uses first)
+ */
+export function parseAccession(raw: string): string | null {
+  if (!raw || !raw.trim())
+    return null;
+
+  // Take first entry if semicolon-delimited
+  const first = raw.split(';')[0].trim();
+  if (!first)
+    return null;
+
+  // Handle sp|ACC|NAME or tr|ACC|NAME format
+  const pipeMatch = first.match(/^(?:sp|tr)\|([A-Za-z0-9_-]+)\|/);
+  if (pipeMatch)
+    return pipeMatch[1];
+
+  // Handle CPTAC/UPS format: P00167ups|CYB5_HUMAN_UPS — extract accession before "ups" suffix
+  const upsMatch = first.match(/^([A-Za-z0-9]+?)ups\|/i);
+  if (upsMatch)
+    return upsMatch[1];
+
+  // Handle generic ACC|NAME format (single pipe, no sp/tr prefix)
+  if (first.includes('|'))
+    return first.split('|')[0].trim();
+
+  // Bare accession -- strip trailing "ups" suffix (CPTAC spike-in format) then return
+  const bareMatch = first.match(/^([A-Za-z0-9_-]+)$/);
+  if (bareMatch) {
+    const acc = bareMatch[1];
+    return acc.replace(/ups$/i, '');
+  }
+
+  return null;
+}
+
+
+/** Fetch protein data from UniProt. Delegates to the shared subcellular-location
+ * module's cached fetcher so re-clicking a protein doesn't re-hit the network
+ * (closes the folded cache-uniprot todo); the shared fetcher keeps the same
+ * fetchProxy / warn+null discipline this panel relied on. */
+async function fetchUniProtData(accession: string): Promise<UniProtEntry | null> {
+  return (await fetchUniProtEntry(accession)) as UniProtEntry | null;
+}
+
+
+/** Extract and group GO terms by aspect (F/P/C). */
+function extractGoTerms(entry: UniProtEntry): GoTerms {
+  const mf: string[] = [];
+  const bp: string[] = [];
+  const cc: string[] = [];
+
+  for (const xref of entry.uniProtKBCrossReferences ?? []) {
+    if (xref.database !== 'GO') continue;
+    const term = xref.properties?.find((p) => p.key === 'GoTerm')?.value ?? '';
+    if (term.startsWith('F:')) mf.push(term.substring(2));
+    else if (term.startsWith('P:')) bp.push(term.substring(2));
+    else if (term.startsWith('C:')) cc.push(term.substring(2));
+  }
+  return {mf, bp, cc};
+}
+
+
+/** Get protein name, falling back to submission name if no recommended name. */
+function getProteinName(entry: UniProtEntry): string {
+  return entry.proteinDescription?.recommendedName?.fullName?.value ??
+    entry.proteinDescription?.submissionNames?.[0]?.fullName?.value ??
+    'Unknown';
+}
+
+
+/**
+ * R3 / D-11 — locate the host DataFrame for a clicked protein in the UniProt panel.
+ * Walks grok.shell.tables for tables whose `getGroups()` is set AND whose primary
+ * protein-id column resolves the queried accession in some row. Prefers the
+ * table behind the current table view when multiple match.
+ */
+export function findHostDataFrameForProtein(accession: string): DG.DataFrame | null {
+  if (!accession) return null;
+  const candidates: DG.DataFrame[] = [];
+  for (const df of grok.shell.tables) {
+    if (!getGroups(df)) continue;
+    const idCol = findColumn(df, SEMTYPE.PROTEIN_ID,
+      ['primary protein id', 'protein id', 'uniprot', 'accession']);
+    if (!idCol) continue;
+    for (let i = 0; i < df.rowCount; i++) {
+      const raw = idCol.get(i) as string | null;
+      if (raw && parseAccession(raw) === accession) {
+        candidates.push(df);
+        break;
+      }
+    }
+  }
+  if (candidates.length === 0) return null;
+  const activeDf = grok.shell.tv?.dataFrame ?? null;
+  if (activeDf && candidates.includes(activeDf)) return activeDf;
+  return candidates[0];
+}
+
+/**
+ * R3 / D-11 — compact SVG bar chart (one bar per experimental group, mean ± SD
+ * whiskers, magenta/cyan per D-04). Returns null when the protein has no row
+ * in the host DataFrame; the caller renders the empty-state message instead.
+ * Returns the empty-state element when the row exists but every group has zero
+ * non-null observations.
+ *
+ * Source: 14-RESEARCH.md §"Pattern 6 — Inline SVG bar chart in a panel".
+ */
+export function renderPerGroupBars(df: DG.DataFrame, accession: string): HTMLElement | null {
+  const groups = getGroups(df);
+  if (!groups) return null;
+
+  const idCol = findColumn(df, SEMTYPE.PROTEIN_ID,
+    ['primary protein id', 'protein id', 'uniprot', 'accession']);
+  if (!idCol) return null;
+
+  let rowIdx = -1;
+  for (let i = 0; i < df.rowCount; i++) {
+    const raw = idCol.get(i) as string | null;
+    if (raw && parseAccession(raw) === accession) { rowIdx = i; break; }
+  }
+  if (rowIdx < 0) return null;
+
+  const stats = [groups.group1, groups.group2].map((g) => {
+    const vals = g.columns
+      .map((n) => df.col(n))
+      .filter((c): c is DG.Column => c != null)
+      .map((c) => (c.isNone(rowIdx) ? NaN : c.get(rowIdx) as number))
+      .filter((v) => typeof v === 'number' && !isNaN(v) && v !== DG.FLOAT_NULL);
+    const n = vals.length;
+    if (n === 0) return {name: g.name, mean: NaN, sd: NaN, n: 0};
+    const mean = vals.reduce((s, v) => s + v, 0) / n;
+    const variance = n > 1 ? vals.reduce((s, v) => s + (v - mean) ** 2, 0) / (n - 1) : 0;
+    return {name: g.name, mean, sd: Math.sqrt(variance), n};
+  });
+  if (stats.every((s) => s.n === 0))
+    return ui.divText('No per-group quantities available for this protein');
+
+  // SVG layout — locked spacing per 14-UI-SPEC §"Spacing Scale > Per-group bar-chart".
+  const W = 200, H = 120, BAR_W = 24, GAP = 8, PAD = 24;
+  const maxVal = Math.max(
+    ...stats.map((s) => (isNaN(s.mean) ? 0 : s.mean + (isNaN(s.sd) ? 0 : s.sd))),
+  );
+  const safeMax = maxVal > 0 ? maxVal : 1;
+  const scale = (v: number) => H - PAD - (v / safeMax) * (H - 2 * PAD);
+  // D-04 LOCKED palette: group1=magenta, group2=cyan — derived from the shared
+  // DIRECTION_COLORS_BASE (ARGB) so the panel can't drift from the volcano.
+  // #RRGGBB (uppercase) matches the SVG fill the panel has always emitted.
+  const hexRgb = (argb: number) => '#' + (argb & 0xFFFFFF).toString(16).padStart(6, '0').toUpperCase();
+  const COLORS = [
+    hexRgb(DIRECTION_COLORS_BASE.enrichedG1),
+    hexRgb(DIRECTION_COLORS_BASE.enrichedG2),
+  ];
+  const svgNs = 'http://www.w3.org/2000/svg';
+  const svg = document.createElementNS(svgNs, 'svg');
+  svg.setAttribute('width', String(W));
+  svg.setAttribute('height', String(H));
+
+  stats.forEach((s, i) => {
+    const x = PAD + i * (BAR_W + GAP * 2);
+    if (s.n === 0) return;
+    const y = scale(s.mean);
+    const rect = document.createElementNS(svgNs, 'rect');
+    rect.setAttribute('x', String(x));
+    rect.setAttribute('y', String(y));
+    rect.setAttribute('width', String(BAR_W));
+    rect.setAttribute('height', String(Math.max(0, H - PAD - y)));
+    rect.setAttribute('fill', COLORS[i] ?? hexRgb(DIRECTION_COLORS_BASE.notSig));
+    svg.appendChild(rect);
+
+    // Mean±SD whiskers only when SD is defined (n > 1).
+    if (s.n > 1 && !isNaN(s.sd)) {
+      const whiskerX = x + BAR_W / 2;
+      const yTop = scale(s.mean + s.sd);
+      const yBot = scale(s.mean - s.sd);
+      const line = document.createElementNS(svgNs, 'line');
+      line.setAttribute('x1', String(whiskerX));
+      line.setAttribute('x2', String(whiskerX));
+      line.setAttribute('y1', String(yTop));
+      line.setAttribute('y2', String(yBot));
+      line.setAttribute('stroke', '#333');
+      line.setAttribute('stroke-width', '1');
+      svg.appendChild(line);
+    }
+
+    const label = document.createElementNS(svgNs, 'text');
+    label.setAttribute('x', String(x + BAR_W / 2));
+    label.setAttribute('y', String(H - 4));
+    label.setAttribute('text-anchor', 'middle');
+    label.setAttribute('font-size', '10');
+    label.textContent = `${s.name} (n=${s.n})`;
+    svg.appendChild(label);
+  });
+
+  const container = ui.divV([svg]);
+  stats.forEach((s) => {
+    if (s.n > 0) {
+      const txt = ui.divText(`${s.name}: mean=${s.mean.toFixed(2)}  SD=${s.sd.toFixed(2)}`);
+      txt.style.fontSize = '0.85em';
+      container.appendChild(txt);
+    }
+  });
+  return container;
+}
+
+
+/** Build the widget DOM for a successfully fetched UniProt entry. */
+export function renderUniProtWidget(entry: UniProtEntry, accession: string): HTMLElement {
+  const container = document.createElement('div');
+
+  // Prominent link to full UniProt entry
+  const link = ui.link(
+    `UniProt: ${accession}`,
+    `https://www.uniprot.org/uniprot/${accession}`,
+    'Open full UniProt entry',
+  );
+  link.style.fontWeight = 'bold';
+  link.style.display = 'block';
+  link.style.marginBottom = '8px';
+  container.appendChild(link);
+
+  // Summary table
+  const proteinName = getProteinName(entry);
+  const gene = entry.genes?.[0]?.geneName?.value ?? 'Unknown';
+  const organism = entry.organism?.scientificName ?? 'Unknown';
+
+  const funcComment = entry.comments?.find((c) => c.commentType === 'FUNCTION');
+  let funcText = funcComment?.texts?.[0]?.value ?? '';
+  if (funcText.length > 200)
+    funcText = funcText.substring(0, 200) + '...';
+
+  const map: Record<string, string> = {
+    'Protein': proteinName,
+    'Gene': gene,
+    'Organism': organism,
+  };
+  if (funcText)
+    map['Function'] = funcText;
+
+  container.appendChild(ui.tableFromMap(map));
+
+  // GO terms grouped by category
+  const go = extractGoTerms(entry);
+  const goCategories: Array<{label: string; terms: string[]}> = [
+    {label: 'Molecular Function', terms: go.mf},
+    {label: 'Biological Process', terms: go.bp},
+    {label: 'Cellular Component', terms: go.cc},
+  ];
+
+  const hasGoTerms = goCategories.some((c) => c.terms.length > 0);
+  if (hasGoTerms) {
+    const goHeader = ui.divText('GO Terms');
+    goHeader.style.fontWeight = 'bold';
+    goHeader.style.marginTop = '8px';
+    goHeader.style.marginBottom = '4px';
+    container.appendChild(goHeader);
+
+    for (const cat of goCategories) {
+      if (cat.terms.length === 0) continue;
+      const label = ui.divText(cat.label);
+      label.style.fontWeight = 'bold';
+      label.style.fontSize = '0.9em';
+      label.style.marginTop = '4px';
+      container.appendChild(label);
+
+      const termText = cat.terms.slice(0, 5).join(', ');
+      const termDiv = ui.divText(termText);
+      termDiv.style.fontSize = '0.85em';
+      termDiv.style.marginLeft = '8px';
+      container.appendChild(termDiv);
+    }
+  }
+
+  // R3 / D-11 — per-group quantities bar chart (Phase 14)
+  // The panel's `accession` parameter is the canonical source; threading it
+  // through findHostDataFrameForProtein avoids depending on whichever optional
+  // field the UniProtData shape happens to expose.
+  const hostDf = findHostDataFrameForProtein(accession);
+  if (hostDf) {
+    const perGroupHeader = ui.divText('Per-Group Quantities');
+    perGroupHeader.style.fontWeight = 'bold';
+    perGroupHeader.style.marginTop = '8px';
+    perGroupHeader.style.marginBottom = '4px';
+    container.appendChild(perGroupHeader);
+    const bars = renderPerGroupBars(hostDf, accession);
+    container.appendChild(bars ?? ui.divText('No per-group quantities available for this protein'));
+  }
+
+  return container;
+}
+
+
+/**
+ * Main panel function. Accepts a raw protein ID string, returns a DG.Widget
+ * with async loading (spinner while fetching).
+ */
+export function uniprotPanel(proteinId: string): DG.Widget {
+  const accession = parseAccession(proteinId);
+
+  if (!accession)
+    return new DG.Widget(ui.divText('No valid UniProt accession found'));
+
+  return new DG.Widget(ui.wait(async () => {
+    const data = await fetchUniProtData(accession);
+    if (!data)
+      return ui.divText(`Unable to fetch UniProt data for ${accession}`);
+    return renderUniProtWidget(data, accession);
+  }));
+}