MED3pa — standalone application

A desktop application for MED3pa (Predictive Performance Precision Analysis): uncertainty estimation, problematic-profile discovery, and declaration-rate driven deployment of a classification model.

This repository is an extraction of the MED3pa module from MEDomicsLab. Everything unrelated to MED3pa — the Learning / MEDml flow editor, MEDimage, MEDprofiles, Evaluation, Exploratory, Extraction, MEDfl, Superset, the notebook editor and the terminal — has been removed. What remains is the MED3pa module plus the minimum platform it needs to run.

---

Architecture

Four layers, same as MEDomicsLab but with one module in each:

Electron main (main/)          window, MongoDB lifecycle, Go server lifecycle, python env
        │  ipc
Renderer (renderer/)           Next.js UI — the MED3pa pages + a thin app shell
        │  HTTP :54388
Go server (go_server/)         request dispatcher; spawns python scripts, streams progress
        │  stdin/stdout JSON
Python (pythonCode/)           MED3pa analysis, model application, external-model import
        │
MongoDB :54117                 datasets, models (GridFS), sessions, deployments, patients

Nothing talks to MED3pa directly from the UI: the renderer posts a JSON config to the Go server, which runs the matching python script and pipes progress back.

Layout

Path	What it is
renderer/components/med3pa/	The MED3pa UI — Overview, Configuration, Analysis Workspace, Deployment, Patient Lookup, Session History
renderer/components/shell/	App chrome: workspace gate, header, Data & Models panel
renderer/components/workspace/	MEDDataObject model, data/workspace contexts, the dataset & model picker
renderer/components/mongoDB/	MongoDB access from the renderer
pythonCode/modules/med3pa/	run_med3pa_analysis.py, apply_med3pa_model.py, confidence metrics, MPC strategies, safe expression evaluator
pythonCode/modules/models/	import_external_model.py — wraps ONNX / pickle / joblib models as .medmodel
pythonCode/med_libs/	Go↔python protocol, MongoDB helpers, model loading
go_server/blueprints/	med3pa (analysis, apply, progress) and models (import) routes

---

Getting started

1. Prerequisites

• Node.js 18+
• Go 1.21+
• Python 3.9–3.12
• MongoDB — the app starts and stops mongod itself against a config it writes into your workspace at .medomics/mongod.conf (port 54117). It must be on your PATH, or installed through the app's installer helper.

2. Installing MED3pa

MED3pa is on PyPI and pinned in pythonEnv/requirements.txt. Note it is currently a pre-release, so the exact == pin is what makes pip accept it without --pre:

pip install -r pythonEnv/requirements.txt

Or build a conda environment in one step (python 3.12, OpenSSL pinned, requirements installed and verified):

bash pythonEnv/create_conda_env.sh med3pa_app 3.12

If you are developing against a local checkout of the MED3pa library, replace the MED3pa== line in pythonEnv/requirements.txt with an editable install pointing at your clone:

pip install -e ../packages/MED3pa

Python 3.12 is required, not merely supported: MED3pa uses typing.Self (3.11+) and PEP 604 X | Y unions, and pins checkpointer behind a python_version >= "3.12" marker.

Note that the library's built-in-metric-by-name path is known to raise a TypeError; the app resolves metrics through modules/med3pa/confidence_metrics.py rather than passing a bare name, so this only matters if you call MED3pa directly.

3. Install and run

npm install

npm run dev

nextron builds the renderer and launches Electron. On first launch you are asked to pick a workspace folder — this is where DATA/ lives and where MongoDB stores its files.

4. Building the Go server

The dev script on Linux builds it for you. Elsewhere:

cd go_server && go build main.go

For a packaged build, utilScripts/pack_GO.bat (Windows) or utilScripts/pack_GO.sh copies the binary into go_executables/, which electron-builder ships as an extra resource.

---

Using the app

1. Data & Models (header button) — import CSV datasets into the workspace, and import a base model (.onnx, .pkl, .pickle, .joblib) declaring its feature columns and target.
2. Configuration — pick the base model (or a column of predicted probabilities), the dataset, the target column, and the IPC/APC/MPC settings; run the analysis.
3. Analysis Workspace — MDR curves, the APC tree, problematic profiles, per-metric bars.
4. Deployment — freeze a session at a declaration rate into a deployed model, then apply it to new patients in batch or one at a time.
5. Patient Lookup / Session History — browse what has been scanned and what has been run.

---

What was changed during extraction

Beyond deleting the other modules, three things were rewritten rather than copied:

• components/workspace/workspaceFilePicker.jsx replaces MEDomicsLab's components/learning/input.jsx. MED3pa used two of that 835-line component's ~30 cases (data-input, models-input), both thin filters over the workspace data context — so the entire Learning module was a dependency for a select box.
• components/shell/appShell.jsx replaces the flexlayout tab manager, layoutContext, layoutManager and iconSidebar (~2,800 lines). With one module there is nothing to arrange; MED3pa already carries its own internal navigation.
• utilities/pathUtils.js replaces utilities/fileManagementUtils.js, of which only the path-separator helper was reachable.

The Go route learning/import_external_model/ was renamed to models/import_external_model/, and the terminal subsystem was removed from the Electron main process (dropping the node-pty native dependency).

---

Installing on macOS

The macOS build is ad-hoc signed but not notarized, because notarization requires a paid Apple Developer ID certificate. macOS will refuse to open it on the first attempt.

To allow it once:

1. Open the .dmg and drag MED3pa to Applications
2. Launch it — macOS blocks it and says the developer cannot be verified
3. Go to System Settings → Privacy & Security, scroll down, and click Open Anyway
4. Launch again and confirm

The old right-click → Open shortcut was removed in macOS 15 (Sequoia); the Settings route above is the current one. This is only needed on first launch.

If instead you see "MED3pa is damaged and can't be opened", that is a different problem: the app reached you without a valid signature. Strip the download quarantine flag and relaunch:

xattr -cr /Applications/MED3pa.app

The build is compiled on an Apple Silicon runner, so it targets arm64. Intel Macs are not currently covered.

---

Releasing

Releases are built by .github/workflows/release.yml, triggered by pushing a tag that starts with v. The tag minus its leading v becomes the version in package.json, so the tag is the single source of truth:

git tag v0.1.0-alpha.1 && git push MED3paApp v0.1.0-alpha.1

That one tag builds all three platforms in parallel — Windows, Linux and macOS — and collects them into a single draft pre-release: .exe, .deb, .dmg, plus a zip of the python environment files. Nothing is public until you review it and press Publish.

A GitHub release is keyed on its tag, so all platforms must build from the same tag. Using a separate tag per platform produces a separate release each time.

---

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

---

License

GPL-3.0, the same license as the MEDomicsLab project this was extracted from.