glio-sign

The only npm/JavaScript-native mutational-signature engine. Glioma-specialised, governed, multi-modal. Every other tool in the field (SigProfiler, MuSiCal, sigminer, deconstructSigs, MutationalPatterns, sigfit, PASA, ...) is Python or R; GLIO-SIGN installs with npm install and runs in Node, a browser, or a serverless function with zero Python required for its core, and an optional real Python numeric sidecar for heavy de-novo work.

Research use only (RUO). Not for diagnostic or therapeutic use. GLIO-SIGN emits governed, abstaining research objects; it never names or recommends a clinical action.

Why it exists

Mutational-signature analysis is dominated by excellent Python/R tools, but none ships for the JavaScript ecosystem, none carries a governance/abstention discipline, and none unifies the glioma-specific process modalities (RNA-SBS, CSF-MRD monitoring, mechanism anchors, therapy contraindication) that glioma research and tumour boards actually need. GLIO-SIGN does all three.

On the shared, benchmarkable tasks it is competitive with the state of the art (pinned-Docker, reproducible — see docs/BENCHMARK.md):

• De-novo: matches SigProfilerExtractor (0.9995 vs 0.9997) at ~17x the speed.
• Assignment: beats MuSiCal 30/30 cohorts on glioma panels (sign-test p = 1.9e-9).
• Honest limitation: MuSiCal's minimum-volume NMF still wins de-novo separation of highly collinear signatures — a certified open gap, stated plainly, not hidden.

Full landscape and per-tool verdicts: docs/COMPETITIVE.md.

Install

npm install glio-sign
# or: pnpm add glio-sign   # or: yarn add glio-sign

Self-contained: one ESM + one CJS bundle, self-contained TypeScript types, zero runtime dependencies. Node >= 20.

Quick start (pure TypeScript, no Python)

import {
  GLIOMA_FAMILIES,       // clock | TMZ | MMR | polymerase | ROS | other | ...
  familyOf,              // COSMIC signature name -> glioma process family
  MODULE_ID,             // "glio-sign"
  MODULE_VERSION,
} from 'glio-sign';

familyOf('SBS11');       // -> "TMZ"  (temozolomide)
familyOf('SBS6');        // -> "MMR"  (mismatch-repair deficiency)
GLIOMA_FAMILIES;         // the fixed family taxonomy

Governed report (abstains rather than fabricates)

import { buildSignatureReport } from 'glio-sign';

// buildSignatureReport(inputs, deps) returns a SignatureReport that has passed the
// 4-layer guardEmission (prohibited-language + hard-stops + gates + final-invariant),
// carries provenance dataClass on every artifact, and ABSTAINS below the detectability
// floor instead of guessing. See docs and types for the input/dep contract.

Numeric sidecar (optional, high fidelity)

Heavy de-novo extraction and the full Poisson/KL numeric kernels run in an optional Python FastAPI sidecar; the TS core and the sidecar agree to 1e-6. The typed client:

import { GlioSignClient } from 'glio-sign';

const client = new GlioSignClient({ baseUrl: 'http://localhost:8000' });
// client.refit(...), client.extract(...), etc. — each returns a provenance-wrapped envelope.

Boot the sidecar (needs the Python package / Docker image):

npx glio-mmb-sign serve --port 8000
npx glio-mmb-sign doctor        # environment + readiness check
npx glio-mmb-sign routes        # list the governed endpoints

What is inside

| Layer | What | |---|---| | Catalogs | SBS-96, RNA-SBS-192, ID-83, CN-48, SV-32, DBS-78, mtDNA (COSMIC v3.6) | | Core | opportunity correction, Poisson-KL refit, de-novo NMF/mvNMF, presence test, over-identification, negative-control calibration | | Glioma modules | mechanism anchors (C1), common-vs-rare (C2), radiotherapy imprint (F1), lineage-conditional prognosis (F2), therapy contraindication (F3), CSF/TISF MRD monitor (D1), clustered/kataegis (A3), single-cell (B1) | | Governance | 4-layer guardEmission, abstention, dataClass provenance, hash-chained audit |

Deployment

npm is one of several supported form factors — see docs/DEPLOYMENT.md for the npm library, the PyPI wheel (to rival pip install musical directly), the Docker image, the REST/OpenAPI service, and the GitHub Action, with a per-use-case guide.

License

Proprietary, research use only. See LICENSE. Bundled reference dictionaries carry their own upstream licenses; gated datasets are not redistributed.