@datagrok/proteomics 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,52 @@
-# monomerDB changelog
-
-## 0.0.1 (2025-10-28)
+# Proteomics changelog
+
+## 1.2.0
+
+- **Shared enrichment charts now survive reopen** — a published/shared analysis's enrichment
+  dot and bar charts no longer lose their value column (the "Column negLog10FDR does not
+  exist" error) when the project is reopened, and the Up/Down term tables no longer leak
+  into the project as extra tables. The charts are now self-contained on the enrichment
+  frame and split by direction via a per-viewer filter.
+- **Volcano opens automatically on Candidates import** — importing a Spectronaut Candidates
+  file now lands you on the volcano immediately, matching the Report → Differential
+  Expression path (Candidates arrive with the result already computed, so the pipeline's DE
+  step is skipped).
+- **Personas & capabilities documentation** — a reference describing what the proteomics
+  analyst vs. the biology scientist can do and how that boundary is enforced.
+
+## 0.2.0
+
+- **Organism-aware subcellular-location coloring** — the volcano's "color by subcellular
+  location" now fetches UniProt annotations for the experiment's organism (persisted as a
+  `proteomics.organism` tag from the Enrichment dialog), so non-human data is no longer
+  mis-colored by human entries. The taxonomy filter applies only to the reviewed-by-gene
+  fallback; accession lookups stay unfiltered, and all 9 supported organisms are covered.
+- **Internal consistency** — significance thresholds, the direction palette, and column-name
+  constants are now single-sourced instead of duplicated across files; the differential-
+  expression FDR cutoff is wired through to the BH correction.
+- **README** — illustrated with the main analysis view, an authored pipeline diagram, and an
+  enrichment→volcano cross-link walkthrough.
+
+## 0.1.0
+
+Initial release — mass spectrometry-based proteomics analysis, carrying a study from
+search-engine output to biological interpretation inside Datagrok.
+
+- **Import** — MaxQuant (`proteinGroups.txt`), Spectronaut Report (PG-level, including
+  streaming aggregation of long-form precursor exports), Spectronaut Candidates
+  (pre-computed differential expression), FragPipe (`combined_protein.tsv`), and a generic
+  CSV/TSV column-mapping importer. Contaminant/decoy filtering, log2 transformation, and
+  semantic-type tagging are applied on import.
+- **Pipeline** — experiment annotation (group assignment), normalization
+  (median / quantile / VSN), missing-value imputation (kNN / MinProb / mean / median /
+  zero), and differential expression cascading DEqMS → limma → client-side Welch's t-test.
+- **Visualization** — volcano, clustered expression heatmap, sample-level PCA, group-mean
+  correlation, QC dashboard (MA / CV / missingness / intensity trend), and an SPC dashboard
+  with Nelson-rule instrument monitoring.
+- **Biological interpretation** — g:Profiler over-representation analysis (GO, KEGG,
+  Reactome, WikiPathways across 9 organisms) with dot/bar charts cross-linked to the
+  volcano, plus a UniProt context panel for per-protein metadata.
+- **Sharing** — publish read-only, access-verified, versioned review snapshots
+  (table + volcano + enrichment) to a reviewer group.
+- R scripts (limma, DEqMS, VSN) run server-side with client-side fallbacks throughout, so
+  the package is fully functional without a configured R environment.

package/CLAUDE.md

@@ -0,0 +1,178 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Purpose
+
+Datagrok extension for mass-spectrometry proteomics analysis. Imports search-engine output
+(MaxQuant, Spectronaut, FragPipe, generic CSV/TSV), runs the analysis pipeline
+(annotate groups -> normalize -> impute -> differential expression -> enrichment),
+and adds the matching viewers (volcano, heatmap, PCA, QC dashboard, enrichment charts).
+Exposed in the platform under the top-menu **Proteomics**.
+
+Auth / credentials: none. The package only calls public REST APIs (UniProt, g:Profiler).
+R scripts (`scripts/limma_de.R`, `scripts/deqms_de.R`, `scripts/vsn_normalize.R`) run server-side
+via `grok.functions.call(...)` and need a configured Datagrok R compute environment; every
+R path has a client-side TypeScript fallback.
+
+## Architecture
+
+Functional pipeline. Each step mutates a shared `DG.DataFrame` in-place and records its
+completion as a `proteomics.*` tag on the DataFrame. Downstream functions read those tags
+as preconditions. There is no separate state store.
+
+- **`src/package.ts`** — entry point. `PackageFunctions` class with `@grok.decorators.func`
+  / `init` / `panel` methods. Each handler validates that a table is open, checks any
+  required `proteomics.*` precondition tag, then delegates to `analysis/` or `viewers/`.
+  The **Proteomics** menu is built two ways (see "Menu architecture" below).
+- **`src/menu.ts`** — builds the full **Proteomics** ribbon menu (Import + Annotate /
+  Analyze / Visualize / Share) on a table view's `ribbonMenu`, with the `isEnabled` grey-out:
+  sample-level items disable themselves on a Spectronaut Candidates table (no per-sample
+  intensities). The `buildProteomicsTopMenu` autostart in `package.ts` calls
+  `buildProteomicsRibbonMenu` once per Proteomics table view.
+
+### Menu architecture (read before touching the menu — non-obvious, verified live)
+
+The **Proteomics** menu lives in two independent hosts. A decorator `top-menu` populates
+`grok.shell.topMenu` (the **left-bar main menu**) ONLY; it does NOT populate a table view's
+ribbon. So:
+
+- **Left-bar main menu** = decorator `top-menu` strings on the `importX` handlers in
+  `package.ts`, e.g. `Proteomics | Import | Spectronaut Candidates...`. This is the
+  always-available entry point — reachable with **no table open** (the ribbon shows no
+  package menu on the Home/start view). Declaration order = menu order (Candidates first,
+  then Report). Only Import is here, because import is the only thing you do without a table.
+- **Ribbon (table view)** = built programmatically in `menu.ts` onto `view.ribbonMenu`, and
+  only when a Proteomics table (`proteomics.source` tag) is active. It builds the WHOLE menu
+  including its own Import group — the decorator Import does not reach the ribbon, and a
+  view's own `ribbonMenu` 'Proteomics' group is what the ribbon shows. Built once per view;
+  do NOT rebuild on view activation (`isEnabled` re-evaluates on open — rebuilding the menu
+  duplicates it, which was a real bug).
+
+To add a menu item: if it's an importer, add a decorator `top-menu` handler in `package.ts`
+(left-bar menu) AND an `imp.item(...)` line in `menu.ts` (ribbon). Otherwise add the handler
+in `package.ts` and an item in the right group in `menu.ts` (pass `sampleOnly` as the
+`isEnabled` option if it needs per-sample data). Don't give the analysis groups decorator
+`top-menu` strings — they'd show in the left-bar menu with no table context and can't grey
+out.
+- **`src/analysis/`** — pure computation that mutates the DataFrame and sets a completion
+  tag. One file per step: `experiment-setup.ts` (groups + `getGroups`/`setGroups`),
+  `normalization.ts`, `imputation.ts`, `differential-expression.ts`, `pca.ts`, `enrichment.ts`.
+  `log2-scale.ts` is the exception — a post-import corrective (Analyze | Set Log2 Scale...) that
+  rebuilds the `log2(...)` columns from the pristine originals and *clears* the downstream completion
+  tags (base data changed → pipeline must re-run).
+- **`src/parsers/`** — vendor file -> filtered, log2-transformed, semantic-typed DataFrame.
+  `maxquant-parser.ts`, `spectronaut-parser.ts` (PG report — per-sample quant),
+  `spectronaut-candidates-parser.ts` (Candidates report — pre-computed DE; emits the
+  canonical `log2FC` / `p-value` / `adj.p-value` / `significant` shape and sets
+  `proteomics.de_complete`, so the pipeline skips Annotate/Normalize/Impute/DE),
+  `fragpipe-parser.ts`, `generic-parser.ts`, plus `shared-utils.ts` (log2 transform,
+  log2-status detection, delimiter detection, primary-id column extraction). Parsers return
+  unnamed DataFrames; the import handler in `package.ts` sets `df.name` from the filename.
+- **`src/viewers/`** — `DG.Viewer` factories that read an already-analysed DataFrame.
+  `volcano.ts`, `heatmap.ts`, `pca-plot.ts`, `qc-dashboard.ts` (+ `qc-computations.ts` for
+  MA / CV / missingness math), `enrichment-viewers.ts`.
+- **`src/panels/uniprot-panel.ts`** — context-panel widget that fetches per-protein metadata
+  on cell click. Registered via `@grok.decorators.panel` with a `semType` filter.
+- **`src/utils/proteomics-types.ts`** — `SEMTYPE` constants. **Single source of truth** for
+  every `Proteomics-*` semantic type string. Use these; never inline the strings.
+- **`src/utils/column-detection.ts`** — `findColumn(df, semType, nameHints)` and
+  `findProteomicsColumns(df)`. **Use these instead of `df.col('Gene names')`** so the
+  package keeps working on tables from new vendors that haven't been semantically tagged.
+- **`detectors.js`** (package root, plain JS — not under `src/`) — semantic-type detectors
+  loaded by the platform before the webpack bundle. Mirrors the `SEMTYPE` constants. If you
+  add a new semantic type, add a detector here too.
+
+### Pipeline shape (read before editing)
+
+```
+parse* (parsers/)
+  -> grok.shell.addTableView(df)
+  -> showAnnotationDialog (analysis/experiment-setup)  sets proteomics.groups
+  -> showNormalizationDialog (analysis/normalization)  sets proteomics.normalized
+  -> showImputationDialog    (analysis/imputation)     sets proteomics.imputed
+  -> showDEDialog            (analysis/differential-expression) sets proteomics.de_complete (+ proteomics.de_method)
+  -> createVolcanoPlot / createExpressionHeatmap / showEnrichmentDialog
+```
+
+Workflow state is **only** on the DataFrame as tags (see "Tags" below). Group assignments
+are JSON-encoded in `proteomics.groups` — always go through `getGroups(df)` / `setGroups(df, g)`
+in `analysis/experiment-setup.ts`; do not parse the tag yourself.
+
+PCA is the one viewer that produces a **new** sample-level DataFrame (rows = samples, not
+proteins). It must open in its own table view — never add the PCA viewer to the protein
+table view. See the `showPcaPlot` handler in `package.ts` for the pattern.
+
+### Function-naming convention (load-bearing)
+
+The package splits the common shapes by prefix. Match the prefix when adding new code:
+
+| Prefix | Shape | Side effect |
+|---|---|---|
+| `showX(df)` | opens a `ui.dialog(...)` | mutates `df` on OK |
+| `openX(df)` | creates a table view / dashboard | adds to the shell |
+| `createX(df, opts?)` | returns a `DG.Viewer` | none — pure factory |
+| `parseXText(text)` | returns a `DG.DataFrame` | none — caller adds to shell + sets name |
+
+Menu paths that open a dialog end with `...`; immediate-action items do not.
+
+## Glossary
+
+| Concept | Code | Meaning |
+|---|---|---|
+| Intensity column | `DG.Column` with `semType = SEMTYPE.INTENSITY` | One sample's per-protein abundance. Raw or log2-transformed; analysis steps operate on the `log2(...)` variants. |
+| Group assignment | `GroupAssignment` interface (`analysis/experiment-setup.ts`); JSON in `proteomics.groups` tag | Maps two named groups (e.g. Control / Treatment) to the intensity columns belonging to each. Required input for normalization, imputation, DE, PCA, enrichment. |
+| DE result | `log2FC`, `p-value`, `adj.p-value`, `significant` columns added by `runDifferentialExpression` / R scripts | Per-protein output of differential expression. Volcano/heatmap require these — they check `proteomics.de_complete`. |
+| Fallback chain | `try { R } catch { client-side }` in `analysis/` | DE runs DEqMS -> limma -> client t-test; VSN -> quantile. R is optional; the package must still function without it. |
+| Cross-DF link (enrichment) | `enrichDf.onCurrentRowChanged` subscription in `viewers/enrichment-viewers.ts` | Selecting a GO/KEGG term row in the enrichment DataFrame highlights the linked proteins in the protein DataFrame's volcano/heatmap. |
+
+### DataFrame tags
+
+All workflow state lives in tags prefixed `proteomics.`. Checking and setting these tags is
+how the pipeline coordinates between steps — there is no other state store.
+
+| Tag | Value | Set by |
+|---|---|---|
+| `proteomics.source` | `'maxquant'` / `'spectronaut'` / `'spectronaut-candidates'` / `'fragpipe'` / `'generic'` | parsers |
+| `proteomics.groups` | JSON `GroupAssignment` | `setGroups()` after Annotate Experiment |
+| `proteomics.organism` | g:Profiler code (e.g. `rnorvegicus`) | `setOrganism()` — auto-detected at import from the data's organism column (`detectOrganismCode`), confirmable in Annotate Experiment, and persisted on Enrichment OK; read by enrichment + subcellular-location gene fallback |
+| `proteomics.normalized` | `'true'` | any normalization method |
+| `proteomics.preNormalized` | `'true'` | Spectronaut parser (input was already normalized) |
+| `proteomics.imputed` | `'true'` | any imputation method |
+| `proteomics.de_complete` | `'true'` | DE pipeline completion, or Spectronaut Candidates parser (already-computed DE) |
+| `proteomics.de_method` | `'limma'` / `'deqms'` / `'t-test'` / `'spectronaut'` | DE on completion (which method actually ran) |
+| `proteomics.enrichment` | `'true'` | enrichment DataFrame marker |
+
+## Conventions specific to this package
+
+- **Look up columns via `findColumn` / `findProteomicsColumns`**, never by raw name. Imports
+  from new vendors may not be semantically typed yet, so the helper falls back to name
+  hints. Hard-coded `df.col('Gene names')` will silently miss valid columns.
+- **Use `SEMTYPE.*` from `src/utils/proteomics-types.ts`** for every `Proteomics-*` string.
+  These are the single source of truth and are mirrored in `detectors.js`.
+- **Set the matching `proteomics.*` tag** when finishing an analysis step. Downstream
+  viewers gate on it. If you add a new step, pick a tag name now and document it here.
+- **Always provide a client-side fallback for R script calls.** The DE pipeline cascades
+  DEqMS -> limma -> client-side Welch's t-test; normalization cascades VSN -> quantile.
+  Never assume the platform R environment is configured.
+- **Idempotency on re-run.** DE is guarded by checking `proteomics.de_complete` in the
+  menu handler. Normalization/imputation are not currently guarded — if you add a step that
+  adds columns, follow the `ensureFreshFloat` pattern in `viewers/qc-computations.ts`
+  (remove the column if it exists, then add it) so re-running doesn't produce duplicates.
+- **PCA opens in a separate table view.** Its sample-level DataFrame has a different row
+  count from the protein DataFrame, so `createPcaPlot` returns `{viewer, pcaDf}` and the
+  caller does `grok.shell.addTableView(pcaDf)` before docking the viewer. Do not add a PCA
+  viewer to the protein table view.
+- **Heatmap clones the DataFrame for filter isolation.** `createExpressionHeatmap` uses
+  `df.clone(filter)` so its top-N sort/filter doesn't leak into the volcano sharing the
+  same source DataFrame.
+- **Adding a new semantic type:** update `SEMTYPE` in `src/utils/proteomics-types.ts` **and**
+  add a detector in `detectors.js`. The README's "Semantic Type Detection" table is part of
+  the public contract.
+- **Adding a new parser, analysis step, or viewer:** the file layout for each is documented
+  in `.planning/codebase/STRUCTURE.md` under "Where to Add New Code". Follow that contract
+  (new file under the matching directory, register handler in `src/package.ts`, add
+  precondition tag check, add test under `src/tests/`).
+- **Deeper context:** `.planning/codebase/{ARCHITECTURE,STRUCTURE,CONVENTIONS,CONCERNS,
+  INTEGRATIONS,TESTING,STACK}.md` are kept up to date and go well beyond this file. Read
+  them when a task is non-trivial; do not duplicate their content here.

package/README.md

@@ -1,3 +1,195 @@
-# Proteomics
-Proteomics is a Datagrok Package for handling and processing proteins.
-The package is under GPL-3 due to some of its dependencies (like antpack 0.3.8.6) are under such licence
+# Proteomics
+
+Mass spectrometry-based proteomics data analysis [package](https://datagrok.ai/help/develop/#packages)
+for the [Datagrok](https://datagrok.ai) platform.
+
+It takes a study from raw search-engine output to a result a biologist can act on —
+*which proteins changed, what pathways they implicate, and what each protein is* — and lets
+you share that result as a read-only snapshot a collaborator can explore without touching
+the raw data or writing a line of code. It covers **label-free quantitative proteomics**
+from both **DDA** (MaxQuant, FragPipe) and **DIA** (Spectronaut) workflows.
+
+Open it from the **Proteomics** top menu.
+
+![The Proteomics analysis view: an interactive volcano plot of differential expression (top), a clustered expression heatmap of the top proteins (bottom), and the UniProt context panel for the selected protein — showing its name, gene, organism, function, GO terms and per-group abundance — all on one screen](images/hero.png)
+
+*One screen from statistics to biology: the interactive volcano, the clustered expression heatmap, and in-place UniProt annotation for the selected protein.*
+
+## Where it fits
+
+The package picks up **where the search engine leaves off** and carries the study all the
+way to biological interpretation. It does not replace MaxQuant, FragPipe, DIA-NN or
+Spectronaut, and it does not touch raw instrument files (`.raw`, `.mzML`, `.d`) — you
+bring in the protein/quant table they produce. From there it stands in for the four-to-six
+disconnected desktop tools and hand-exported files that normally sit between that table
+and a finished figure: import, QC, statistics, interpretation, and sharing happen in one
+place, and the result stays reproducible instead of scattered across scripts and
+spreadsheets.
+
+## What you can achieve
+
+### If you generate the data — the proteomics scientist
+
+- **Stand behind your quantification.** Normalization removes between-sample technical
+  bias and principled missing-value handling deals with the dropout that is intrinsic to
+  MS, so downstream fold-changes reflect biology rather than loading or detection
+  artifacts.
+- **Make a defensible significance call.** Statistics built for the small-sample,
+  high-dimensional reality of proteomics (limma / DEqMS) give you a ranked, FDR-controlled
+  list of changed proteins you can justify to a reviewer — not an ad-hoc cutoff.
+- **Catch problems before they become false discoveries.** Per-run QC and longitudinal
+  process control surface a mislabeled channel, a weak replicate, or instrument drift
+  across a batch *before* it drives a result.
+- **Hand off something reproducible.** Publish the finished analysis as a versioned,
+  read-only snapshot — the collaborator sees exactly what you saw, and a later re-analysis
+  supersedes rather than overwrites it.
+
+### If you interpret the data — the biology scientist
+
+- **See what changed.** An interactive volcano shows which proteins go up or down between
+  your conditions and how strongly — sorted, labeled, and clickable, not a static figure.
+- **Understand what it means.** Enrichment collapses a list of hundreds of changed
+  proteins into the handful of biological processes, pathways, and complexes that are
+  actually over-represented (GO, KEGG, Reactome, WikiPathways) — and selecting a pathway
+  highlights its proteins back on the volcano, so statistics and biology stay connected.
+- **Know what each hit is.** Click any protein to pull its name, gene, function, and
+  subcellular location from UniProt, in place — no separate database lookups.
+- **Explore it yourself.** Open the shared snapshot and filter, select, and cross-link
+  interactively. You don't need the raw files, the analysis environment, or another round
+  trip through the analyst to ask your own follow-up questions.
+
+## Supported inputs
+
+| Format | File | Notes |
+|--------|------|-------|
+| **MaxQuant** | `proteinGroups.txt` | DDA. LFQ / Razor / iBAQ intensities; contaminant & reverse-hit filtering |
+| **Spectronaut — Report** | PG-level export | DIA. Pivots long-form precursor exports to a protein × sample matrix; streams multi-GB files; q-value filtering |
+| **Spectronaut — Candidates** | pre-computed DE export | DIA. Already-computed fold-change / FDR per protein; skips straight to visualization |
+| **FragPipe** | `combined_protein.tsv` | DDA. MaxLFQ / Intensity / Razor; Philosopher contaminant filtering |
+| **Generic matrix** | any CSV/TSV | Column-mapping dialog; auto-detects delimiter and log2 status |
+
+> DIA-NN is **not** currently supported as a direct importer — bring DIA-NN output in via
+> the **Generic matrix** path, or as a Spectronaut-style matrix.
+
+## Workflow
+
+The pipeline runs as a sequence of steps from the **Proteomics** menu. Each step records
+its completion on the table, and downstream steps read those as preconditions, so the
+menu greys out actions that don't yet apply (and items that need per-sample intensities
+are disabled on the pre-computed Spectronaut Candidates table).
+
+![Proteomics analysis pipeline: Import, Annotate Experiment, Normalize, Impute and Differential Expression, each setting a proteomics.* tag that gates the next step, then branching to Visualize, Enrich and Share](images/pipeline.svg)
+
+### Import
+`Spectronaut Candidates...` · `Spectronaut Report...` · `MaxQuant...` · `FragPipe...` ·
+`Generic Matrix...` — also available from the left-bar main menu with no table open.
+
+### Annotate
+- **Annotate Experiment** — assign intensity columns to two named groups
+  (e.g. Control vs. Treatment); required input for normalization, imputation, DE, PCA and
+  enrichment.
+
+### Analyze
+- **Normalize** — median centering, quantile normalization, or VSN (variance-stabilizing;
+  R, with a quantile fallback).
+- **Impute Missing Values** — k-nearest-neighbor, MinProb (Perseus-style downshifted
+  draw), mean, median, or zero.
+- **Differential Expression** — DEqMS (peptide-count-weighted variance) → limma
+  (empirical-Bayes moderated t-test) → client-side Welch's t-test, cascading down on
+  availability. Adds `log2FC`, `p-value`, `adj.p-value` and a `significant` flag.
+- **Enrichment Analysis** — over-representation against GO (BP/MF/CC), KEGG, Reactome and
+  WikiPathways through g:Profiler, for 9 model organisms (human, mouse, rat, yeast,
+  *E. coli*, zebrafish, fly, *Arabidopsis*, *C. elegans*), with optional smart GO pruning.
+- **Compute SPC Status** — score the active run against an instrument-QC baseline.
+
+### Visualize
+- **Volcano Plot** — log2FC vs. -log10(p), with significance threshold lines; switch the
+  significance metric, color by significance or UniProt subcellular location, and label
+  the top-N proteins independently of selection.
+- **Heatmap** — clustered expression heatmap of the top differential proteins.
+- **PCA** — sample-level principal-component scatter (opens in its own view).
+- **Group-Mean Correlation** — group1 vs. group2 mean per protein, with Pearson/Spearman.
+- **QC Dashboard** — MA plot, coefficient-of-variation, missingness matrix and an
+  intensity trend.
+- **SPC Dashboard** — longitudinal control charts over instrument metrics
+  (median intensity, missingness, replicate correlation, protein count) with Nelson-rule
+  flagging and a Pareto of tripped rules.
+- **Enrichment Charts** — dot plot and bar chart of the top terms, split Up/Down by
+  direction; selecting a term highlights its proteins back in the volcano.
+
+Selecting a term in the enrichment results highlights that pathway's member proteins back
+on the volcano — a pathway you find in the biology view is immediately located in the
+statistics view, so the two never drift apart:
+
+![Enrichment results grid with the KEGG Cell Cycle term (KEGG:04110) selected](images/enrichment-term-selected.png)
+
+![The volcano plot after selecting the term — the Cell Cycle pathway's member proteins appear as highlighted points and selected rows](images/enrichment-crosslink.png)
+
+*Selecting the KEGG Cell Cycle term (top) highlights its 25 member proteins on the volcano (bottom).*
+
+### Share
+- **Share Analysis for Review** — publish a trimmed, read-only snapshot (table + volcano +
+  enrichment charts) to a reviewer group. The source table is never mutated; reviewer
+  access is verified (and rolled back on an over-permissive grant); the snapshot is
+  optionally re-opened and shape-checked to confirm it survives a reload; re-publishing
+  supersedes the prior version. A **Shared Analysis** context panel surfaces the
+  publication's audit trail.
+
+## Protein annotation
+
+Clicking a protein-ID cell opens the **UniProt** info panel, which fetches the protein
+name, gene, organism, functional description, GO terms (MF / BP / CC) and KEGG / Reactome /
+InterPro cross-references from the UniProt REST API and caches them in App Data.
+
+## Semantic type detection
+
+Columns are auto-detected and tagged so the package keeps working on tables from vendors
+it hasn't seen — detectors match on column-name hints and validate sample values.
+
+| Semantic type | Detects |
+|---------------|---------|
+| `Proteomics-ProteinId` | Protein IDs, Majority Protein IDs, UniProt, Accession (validated against the UniProt accession pattern) |
+| `Proteomics-GeneSymbol` | Gene Names, Gene Symbol, Gene |
+| `Proteomics-Log2FC` | columns naming "log2" with "fc"/"fold" |
+| `Proteomics-PValue` | p-value, adj.p, FDR, q-value (range 0–1) |
+| `Proteomics-Intensity` | Intensity, LFQ / Reporter / Razor / MaxLFQ Intensity, iBAQ |
+| `Proteomics-SubcellularLocation` | UniProt subcellular-location strings |
+| `Proteomics-DisplayName`, `Proteomics-SourceId` | gene-label resolver fields |
+| `Proteomics-NumeratorMean`, `Proteomics-DenominatorMean` | per-group means in Spectronaut Candidates exports |
+
+## Integrations & requirements
+
+- **No credentials required.** The package calls only public REST APIs — UniProt (protein
+  annotation) and g:Profiler (enrichment).
+- **R is optional.** `limma_de.R`, `deqms_de.R` and `vsn_normalize.R` run server-side and
+  require a configured Datagrok R compute environment; every R path has a client-side
+  TypeScript fallback, so the package is fully functional without R.
+
+## Demo data
+
+Example datasets ship in `files/demo/` (see its `README.md`):
+
+- `proteinGroups.txt` — small MaxQuant example
+- `cptac-spike-in.txt` — CPTAC UPS spike-in reference with known concentrations
+- `fragpipe-smoke-test.tsv` — FragPipe `combined_protein.tsv` example
+- `spectronaut-hye-candidates.tsv` — Spectronaut Candidates (pre-computed DE)
+- `spectronaut-hye-precursor.tsv` / `spectronaut-hye-mix.tsv` — Spectronaut long-form reports
+
+## Development
+
+```bash
+cd packages/Proteomics
+
+npm run build              # grok api && grok check --soft && webpack
+grok publish local         # build + publish to your configured server
+grok link && npm install   # link local datagrok-api / @datagrok-libraries
+grok test --host localhost # run the package tests
+```
+
+## See also
+
+- [Personas & capabilities](docs/personas-and-capabilities.md) — who (analyst vs biology
+  scientist) can do what, and how the boundary is enforced.
+- **TODO:** Datagrok Proteomics documentation — the help page at
+  `https://datagrok.ai/help/domains/bio/proteomics` does not exist yet and still needs to
+  be written.

package/detectors.js

@@ -1,9 +1,152 @@
-/**
- * The class contains semantic type detectors.
- * Detectors are functions tagged with `DG.FUNC_TYPES.SEM_TYPE_DETECTOR`.
- * See also: https://datagrok.ai/help/develop/how-to/define-semantic-type-detectors
- * The class name is comprised of <PackageName> and the `PackageDetectors` suffix.
- * Follow this naming convention to ensure that your detectors are properly loaded.
- */
-class MonomerDBPackageDetectors extends DG.Package {
-}
+class ProteomicsPackageDetectors extends DG.Package {
+  //meta.role: semTypeDetector
+  //input: column col
+  //output: string semType
+  detectProteinId(col) {
+    if (col.type !== DG.TYPE.STRING)
+      return null;
+    const name = col.name.toLowerCase();
+    if (name === 'protein ids' || name === 'protein id' || name === 'majority protein ids' ||
+      name === 'primary protein id' || name === 'leading protein' || name === 'leading razor protein' ||
+      name === 'uniprot' || name === 'accession') {
+      const sample = col.toList().slice(0, 20).filter((v) => v != null);
+      const uniprotPattern = /^(?:[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9](?:[A-Z][A-Z0-9]{2}[0-9]){1,2})$/;
+      if (sample.some((v) => uniprotPattern.test(v.split(';')[0]))) {
+        col.semType = 'Proteomics-ProteinId';
+        return col.semType;
+      }
+    }
+    return null;
+  }
+
+  //meta.role: semTypeDetector
+  //input: column col
+  //output: string semType
+  detectGeneSymbol(col) {
+    if (col.type !== DG.TYPE.STRING)
+      return null;
+    const name = col.name.toLowerCase();
+    if (name === 'gene names' || name === 'gene name' || name === 'gene symbol' || name === 'gene') {
+      col.semType = 'Proteomics-GeneSymbol';
+      return col.semType;
+    }
+    return null;
+  }
+
+  //meta.role: semTypeDetector
+  //input: column col
+  //output: string semType
+  detectSubcellularLocation(col) {
+    if (col.type !== DG.TYPE.STRING)
+      return null;
+    const name = col.name.toLowerCase();
+    if (name === 'subcellular location' || name === 'subcellular location [cc]' ||
+      name === 'subcellular' || name.includes('subcellular location') || name.includes('subcellular')) {
+      col.semType = 'Proteomics-SubcellularLocation';
+      return col.semType;
+    }
+    return null;
+  }
+
+  //meta.role: semTypeDetector
+  //input: column col
+  //output: string semType
+  detectLog2FC(col) {
+    if (col.type !== DG.TYPE.FLOAT && col.type !== DG.TYPE.INT)
+      return null;
+    const name = col.name.toLowerCase();
+    if (name.includes('log2') && (name.includes('fc') || name.includes('fold'))) {
+      col.semType = 'Proteomics-Log2FC';
+      return col.semType;
+    }
+    return null;
+  }
+
+  //meta.role: semTypeDetector
+  //input: column col
+  //output: string semType
+  detectPValue(col) {
+    if (col.type !== DG.TYPE.FLOAT && col.type !== DG.TYPE.INT)
+      return null;
+    const name = col.name.toLowerCase();
+    if ((name.includes('p-value') || name.includes('pvalue') || name.includes('p.value') ||
+      name.includes('adj.p') || name.includes('fdr') || name.includes('q-value') || name.includes('qvalue')) &&
+      col.min >= 0 && col.max <= 1) {
+      col.semType = 'Proteomics-PValue';
+      return col.semType;
+    }
+    return null;
+  }
+
+  //meta.role: semTypeDetector
+  //input: column col
+  //output: string semType
+  detectIntensity(col) {
+    if (col.type !== DG.TYPE.FLOAT && col.type !== DG.TYPE.INT)
+      return null;
+    const name = col.name.toLowerCase();
+    const isRawIntensity = name.startsWith('intensity') || name.startsWith('lfq intensity') ||
+      name.startsWith('reporter intensity') || name.startsWith('ibaq') ||
+      name.endsWith(' maxlfq intensity') || name.endsWith(' razor intensity') ||
+      name.endsWith(' intensity');
+    const isLog2Intensity = (name.startsWith('log2(') || name.startsWith('log2 ')) &&
+      (name.includes('intensity') || name.includes('ibaq'));
+    if (isRawIntensity || isLog2Intensity) {
+      col.semType = 'Proteomics-Intensity';
+      return col.semType;
+    }
+    return null;
+  }
+
+  //meta.role: semTypeDetector
+  //input: column col
+  //output: string semType
+  detectDisplayName(col) {
+    if (col.type !== DG.TYPE.STRING)
+      return null;
+    if (col.name.toLowerCase() === 'display name') {
+      col.semType = 'Proteomics-DisplayName';
+      return col.semType;
+    }
+    return null;
+  }
+
+  //meta.role: semTypeDetector
+  //input: column col
+  //output: string semType
+  detectSourceId(col) {
+    if (col.type !== DG.TYPE.STRING)
+      return null;
+    if (col.name.toLowerCase() === 'source id') {
+      col.semType = 'Proteomics-SourceId';
+      return col.semType;
+    }
+    return null;
+  }
+
+  //meta.role: semTypeDetector
+  //input: column col
+  //output: string semType
+  detectNumeratorMean(col) {
+    if (col.type !== DG.TYPE.FLOAT && col.type !== DG.TYPE.INT)
+      return null;
+    if (col.name.toLowerCase() === 'numerator mean') {
+      col.semType = 'Proteomics-NumeratorMean';
+      return col.semType;
+    }
+    return null;
+  }
+
+  //meta.role: semTypeDetector
+  //input: column col
+  //output: string semType
+  detectDenominatorMean(col) {
+    if (col.type !== DG.TYPE.FLOAT && col.type !== DG.TYPE.INT)
+      return null;
+    if (col.name.toLowerCase() === 'denominator mean') {
+      col.semType = 'Proteomics-DenominatorMean';
+      return col.semType;
+    }
+    return null;
+  }
+}