Chemometrics Workbench
An open-source, local-first chemometrics workbench: a Python backend and a React interface
shipped as one double-clickable desktop application, aimed at research and academic users of
closed tools such as Unscrambler, SIMCA and OPUS. Your data never leaves your machine.
Status: v1.1.0, methods breadth. Download it from the releases page.
The application runs: import a dataset — CSV, XLSX, JCAMP-DX, Bruker OPUS, MATLAB .mat,
Galactic SPC, Thermo OMNIC SPA or ASD FieldSpec — build a preprocessing pipeline on a canvas,
split it (stratified if you like), fit PCA, PLS, PCR, PLS-DA, SIMCA, LDA or kNN,
cross-validate, and read the result: scores, loadings, VIP, coefficients on the raw axis,
contributions, confusion and acceptance tables. Outliers are flagged by leverage, studentised
residual and robust distance and excluded only when you say so; variables are selected by VIP,
iPLS or CARS as a step in the pipeline. Every run is kept and two can be compared step by step;
a fitted model exports as a self-describing artifact, a plain JSON model, or a Python
snippet that needs only NumPy; and a run exports as a standalone HTML report. Everything stands on the numerical foundation Phase 0 laid — the algorithm
kernels, their specifications, and the evidence that their numbers are right.
Exit criteria are demonstrated rather than asserted. docs/phase-2/exit-run.md
is a run of the whole calibration workflow over HTTP against an independent PLS on the
experiment's own folds (uv run python -m tests.exit_run).
docs/phase-5/exit-run.md cleans an open multi-class dataset,
selects its variables, compares PLS-DA, SIMCA, LDA and kNN against independent references
under one stratified cross-validation, and imports a file of each new format against its
source (uv run python -m tests.exit_run_phase5).
Phase 6 is in progress, towards v1.2.0: grouped splits for replicate measurements, a final
model fitted on every sample, nested validation of variable selection, permutation tests,
bootstrap intervals, class-wise outlier diagnostics and SVM.
Running it
A packaged application for Windows, Apple Silicon macOS and Linux is attached to each
release. It is unsigned, and
docs/how-to-open.md says how to get past the first-launch warning. From a
checkout:
./run.sh
It syncs the environment, builds the frontend bundle if there is not one, and starts the
server, then opens the workbench in the default browser at the URL it also prints —
http://127.0.0.1:<port>/?token=<token>. Close the terminal, or press Ctrl+C, to stop it. The port is
ephemeral so two copies never fight over a number, and the token is a real check: every /api
request carries it, so a bare 127.0.0.1 address without the token gets a 401.
./run.sh --build rebuilds the bundle first, which is what you want after changing anything
under frontend/src.
Working on the interface is two processes instead, so Vite can serve its own:
WORKBENCH_DEV=1 WORKBENCH_PORT=8765 WORKBENCH_TOKEN=dev uv run python -m chemometrics_workbench.server
cd frontend && pnpm dev # http://localhost:5173
The port is pinned because the Vite proxy has to be told a target in advance, and the token
because a fresh one on every restart is tedious to paste. WORKBENCH_DEV=1 lets the server
accept requests whose Origin is the Vite dev server's; without it every request from
localhost:5173 is refused, which is what a packaged application does.
The parity report
docs/parity-report.md — every quantity this project computes,
next to an independent implementation's value for the same thing, with a claim tier, a
tolerance that has a stated reason, and a citation.
It is regenerated in CI on every push, and a change that moves a scientific number fails the
build — the parity suite is the gate, and the tolerances it compares against are frozen in a
test of their own, so weakening one cannot pass quietly. The report also lists what could
not be compared and why, because a report that shows only its coverage overstates it.
No competing open-source chemometrics project publishes one, and PROPOSAL.md §10.4 is the
argument for why this one does: it is the artifact that turns "an open-source tool" into "a
tool I can put in a paper".
Documents
| |
|---|
PROPOSAL.md | The specification for the whole project: scope, architecture, phases, open questions |
docs/algorithms/ | Normative algorithm specifications — PCA, PLS, metrics and validation, smoothing and baselines |
docs/decisions/ | Decisions taken with evidence, numbered and dated, with the script that reproduces the numbers |
docs/parity-report.md | The parity report |
CONTRIBUTING.md | How to set up, verify and land a change |
docs/adding-a-step.md | How to add an algorithm, walked through end to end on a real step |
Working on it
uv sync
CHEMOMETRICS_DOWNLOAD_DATASETS=1 uv run pytest # once, to populate the dataset cache
uv run ruff check
uv run ruff format --check
uv run mypy
uv run pytest
Only the Tecator dataset is committed. Corn and gasoline are downloaded on first use into
~/.cache/chemometrics-workbench/datasets and verified against a pinned SHA-256; the licence
finding for each is recorded beside its loader. Publishing a result obtained with the
Tecator dataset obliges you to name the instrument and the company, Tecator — a condition of
use, not a courtesy.
scikit-learn and chemotools are development dependencies and must stay that way: they are
the reference implementations the parity fixtures are generated against, and a kernel built on
one of them would be a wrapper around the thing this project claims parity with.
Licence
MIT. See LICENSE.
