SSprc

SSprc is a web-based research prototype for comparing MRI-based prostate cancer risk calculators. A user enters the patient values they know once, and the application returns six calculator estimates side by side with assumptions, provenance, supported-input context, and validation status.

This repository contains application code and validation/reverse-engineering scripts only. Protected TUM patient data and patient-level derived outputs must stay outside git.

Current State

• packages/core: shared patient input, calculator metadata, result, and adapter contracts.
• packages/calculators: six implemented calculator adapters.
• apps/api: Fastify API with password-protected calculator endpoints.
• apps/web: connected React/Vite web interface with login, input form, result cards, summary views, source dossiers, and design/theme toggles.
• analysis/validation: TUM complete-case validation workflow and aggregate figures/tables.
• analysis/reverse_engineering: MSP-RC emulator and BCN2-RC recovery/validation workflows.
• docker/ and docker-compose.yml: deployment containers for API and web.

Calculator Adapters

Calculator	Current method	Notes
TUM-RC	Exact local formula implementation	Translated/adapted from Oksana Chernova's TUM-RC R implementation; not refitted in this thesis.
SPCC	Exact local formula implementation	Implemented from the JavaScript function in the original online calculator; validated against the PCaRC reference workbook; PI-RADS 3-5 scope.
PCRC-MRI	Exact local formula implementation	Extracted from public client-side calculator code and validated against the reference workflow.
ERSPC34-RC	Structured HTTP adapter	Calls the official SWOP endpoint and applies supported-range checks.
MSP-RC	High-fidelity black-box emulator	Fitted on synthetic official-website outputs; website validation matches the workbook exactly, while emulator integer-display deviations are rare and no more than 1 percentage point. Do not describe as exact formula recovery.
BCN2-RC	High-fidelity recovered local approximation	Uses published log-ORs plus website-derived intercept/volume correction; OCR harness retained for validation/regeneration.

Unknown Inputs

Age, PSA, and PI-RADS are required. Prostate volume, DRE, prior biopsy, race/ethnicity, and family history may be unknown.

Each calculator handles unknown values explicitly:

• TUM-RC uses fitted reduced models where supported.
• Some external calculators apply documented calculator-specific assumptions.
• Some calculators return no estimate when a required value is missing or outside scope.

Where the submitted PCaRC workflow documented fixed imputation values, SSprc follows them for replication, such as no family history and Caucasian race/ethnicity. Other missing inputs are handled as calculator-specific assumptions or no-estimate states and are shown explicitly to the user. Avoid describing defaults as "conservative" unless that has been verified for the specific calculator.

Development

Install dependencies:

npm install

Run checks:

npm test
npm run typecheck
npm run build

Run locally:

APP_PASSWORD=change-me npm run dev:api
npm run dev:web

Open http://localhost:5173/login and use the configured password.

API

GET /health is public.

GET /api/calculators/metadata and POST /api/calculate require the x-ssprc-password header when APP_PASSWORD is set.

Example calculation body:

{
  "patient": {
    "age": 68,
    "psa": 7,
    "pirads": 4,
    "volume": 40,
    "dre": "abnormal",
    "priorNegativeBiopsy": "no",
    "race": "White",
    "familyHistory": "no"
  }
}

Validation Commands

Core TUM-RC / SPCC validation:

npm run validate:tum-spcc

ERSPC34-RC endpoint validation:

npm run validate:erspc34

MSP-RC workflows:

npm run validate:msp
npm run fit:msp-emulator
npm run compare:msp-emulator-sizes

BCN2-RC workflows:

npm run validate:bcn2
npm run recover:bcn2-formula
npm run validate:bcn2-formula
npm run plot:bcn2-recovery

Clinical characteristics table:

npm run clinical:characteristics

This creates a descriptive complete-case table only. Do not call it an exact reproduction of the submitted paper's Table 1, and do not add p-values unless Donna explicitly asks.

Data Protection

Do not commit:

• protected TUM datasets,
• reference workbooks containing patient-level data,
• row-level prediction CSVs,
• residual CSVs,
• synthetic website-output datasets,
• screenshots or exports that expose patient-level rows.

Aggregate plots and summaries should still be reviewed before being copied into thesis repositories.

Deployment

The current deployment target is:

https://ssprc.melihy.net/login

The deployed site is password-gated. Deployment is handled through GitHub Actions and Docker; do not put server credentials, Cloudflare tokens, or deployment secrets into commits, documentation, prompts, or thesis text.