neurotcs 1.39.2

Citation-locked, fail-closed longitudinal medical AI audit framework (NeuroTCS / temporalmetric).

NeuroTCS

Citation-locked, fail-closed longitudinal medical AI audit framework.

NeuroTCS audits the temporal coherence of longitudinal medical AI predictions against internationally endorsed published clinical guidelines. It answers the question regulators, hospitals, and trialists ask first: does this AI model's visit-to-visit prediction trajectory obey the clinical biology it claims to predict?

The framework is anchored on Dr. Marufjon Salokhiddinov's ASNR 2026 presentation (Austin, May 2026) and the temporalmetric v1.7 FINAL technical specification.

Hallmark result — four-cohort triangulation lock

Five locked audit invariants reproduce byte-exactly across N=5 cold reruns, numpy 2.0.2↔2.4.4, pyreadr 0.5.0↔0.5.6, on Linux and Windows. Max pairwise ΔcTCS = 0.009206 (ADNI vs MIRIAD), all 6 pairwise comparisons ≤ 0.01 world-class threshold.

Cohort	n_scored / n_total	Transitions	Flagged	cTCS	audit_id
OASIS-3 (Aim 2 external replication)	1,377	7,248	30 (0.41%)	0.994191	92df5429...
ADNI-2/3/4 (Aim 1, canonical R-format)	2,958 / 3,762	12,006	65 (0.54%)	0.994575	7a973f7b...
NACC UDS v73 (added v1.8)	39,361 / 56,529	158,423	1,217 (0.77%)	0.991502	58329c65...
MIRIAD longitudinal (Aim 3 A)	69	454	7 (1.54%)	0.985369	abda26cb...
MIRIAD test-retest (Aim 3 B)	69 (pairs)	69	0 (0.00%)	1.000000	4de7f711...

Each cohort also locks an audit_id_v2 (C6 collision-resistant variant). See tests/audit_core/test_real_*.py for full locked-invariant constants, and docs/datasheet/ad_neurotcs_datasheet.md Section A for full audit_ids and methodology.

The cTCS metric generalises across institution, decade, recruitment criteria, AND staging instrument. Three of the four cohorts use CDR-anchored staging; MIRIAD uses MMSE-anchored staging. The 4-cohort agreement at ≤0.01 ΔcTCS is the strongest cross-cohort evidence to date that the framework measures what it claims to measure.

What's in this repo

NeuroTCS is the umbrella for seven engineering pieces plus five v1.7.0 methodological modules. Pieces 1–4 + 6 are production-shipped; Pieces 5 and 7 are roadmap items planned for v1.9.x (importing them raises a helpful ImportError pointing to the roadmap).

Piece	Subpackage	Status	Description
1	neurotcs.input_contract.v1_0	✅ shipped	Categorical input contract (8-step validation, fail-closed)
2	neurotcs.input_contract.v1_1	✅ shipped	Continuous-biomarker contract with UCUM unit enforcement
3	neurotcs.rulepack	✅ shipped	3 production AD rule packs (NIA-AA 2018, AA 2024, AA 2024 TRAC)
4	neurotcs.audit_core	✅ shipped	cTCS / pTCS / uTCS engine + cluster bootstrap + BCa + Huber
5	neurotcs.output_schema	🗺️ roadmap v1.9.x	FHIR Observation emitter (importing raises ImportError)
6a	neurotcs.input_contract.v1_1.adapters	✅ shipped	OASIS-3, ADNI (canonical R-format), NACC, MIRIAD trajectory loaders
6b	neurotcs.reference_adapters	✅ shipped	Reference submission-builders for vendor onboarding (ADNI categorical + volumetric)
7	neurotcs.validation_harness	🗺️ roadmap v1.9.x	Synthetic-trajectory self-tests (importing raises ImportError)

Plus five methodological modules (all shipped in v1.7.0+, all with tests):

• neurotcs.sample_size — external-validation precision per Riley 2024
• neurotcs.fairness — FUTURE-AI Fairness + Robustness panels per Lekadir 2025 BMJ
• neurotcs.silent_deployment — Kwong 2022 silent-trial methodology
• neurotcs.scanner_factorial — Scanner × vendor × interval factorial robustness
• neurotcs.threshold_derivation — Larson 2025 empirical operational thresholds

Rule packs shipped

NeuroTCS v1.x is scope-narrowed to Alzheimer's disease in preparation for FDA Q-Submission (target Q1 2027). The 3 AD rule packs encode the dominant diagnostic and trajectory frameworks. See docs/SCOPE.md for the scope-decision rationale; non-AD packs that previously shipped in v1.7.x (PD/Hoehn-Yahr, MS/McDonald, oncology RECIST + iRECIST, stroke mRS, lung-nodule Fleischner) have been extracted to seed future per-disease repositories post-FDA-clearance.

Pack	Disease	Anchor publication	PMID	Transitions
ad/niaaa_2018@1.3.0	Alzheimer's	Jack 2018 NIA-AA Framework	29653606	4 + 2 inadmissible
ad/aa_2024@2.1.0	Alzheimer's	Jack 2024 AA Revised Criteria	38934362	28 + 17 inadmissible (Table 7 integrated staging, 17 states)
ad/aa_2024_trac@1.1.0	Alzheimer's (anti-Aβ)	La Joie 2025 TRAC framework	41298245	6 + 3 inadmissible (5 require treatment_status)

Each rule pack is:

• Citation-locked — every transition requires citation_pmid or citation_doi AND guideline_section (exact section/table/figure pointer).
• Version-stamped — canonical JSON SHA-256 hash computed at load time.
• Fail-closed — Pydantic v2 strict mode rejects unknown fields, missing citations, inconsistent state spaces.

Schema v1.3.0 adds backward-compatible support for context-conditional admissibility (the TRAC pack uses this to encode that A+ → A− amyloid clearance is admissible only under anti-Aβ therapy) and attribution_type (clinical_inference vs guideline_quote, per ERRATA E-2026-003).

Authority model

NeuroTCS rule packs do NOT require disease-specialist co-authorship to be authoritative. They require provenance to internationally endorsed published guidelines. The schema makes this explicit:

• clinical_source_authority — names the peer-reviewed publication + endorsing professional society where clinical authority resides.
• transcribed_by — names the board-certified physician who attests the YAML faithfully encodes the cited guideline.
• guideline_section per transition — exact pointer so any reviewer can verify the transcription.
• reviewers — additive specialist sign-off (non-blocking).

This mirrors how FHIR / SNOMED / LOINC terminology encodings work. Authority lives in the cited publication, not in a co-author's signature.

See docs/transcription_audit/ for side-by-side YAML ↔ source-paragraph audits.

Quick start

git clone https://github.com/DrMaruf1991/NeuroTCS.git
cd NeuroTCS
pip install -e .

# Framework-only tests (no cohort data required) — expect 1437 passed, 13 skipped (v1.33.1)
python -m pytest tests/ -q \
    --ignore=tests/audit_core/test_real_adni_audit.py \
    --ignore=tests/audit_core/test_real_oasis3_audit.py \
    --ignore=tests/audit_core/test_real_nacc_audit.py \
    --ignore=tests/audit_core/test_real_miriad_audit.py \
    --ignore=tests/audit_core/test_real_miriad_fairness_audit.py \
    --ignore=tests/audit_core/test_four_cohort_triangulation.py

# Full suite with cohort data (set env vars first; expect 1437+cohort tests passed, cohort-version-dependent)
export NEUROTCS_OASIS3_CDR=/path/to/OASIS3_UDSb4_cdr.csv
export NEUROTCS_ADNI_DXSUM_RDA=/path/to/ADNIMERGE2/data/DXSUM.rda
export NEUROTCS_NACC_CSV=/path/to/investigator_nacc73_slim.csv
export NEUROTCS_MIRIAD_DIR=/path/to/MIRIAD_directory
python -m pytest tests/ -q

The test count is environment-dependent: 1437 passed / 13 skipped without cohort env vars (cohort tests skip; current as of v1.33.1). With all four cohort env vars pointing at valid files, the cohort tests additionally execute and pass; the exact pass count is cohort-version-dependent. Both outcomes are correct behavior.

Rule pack only

from neurotcs import load_rulepack

pack = load_rulepack("ad/niaaa_2018")
ok, rule = pack.rulepack.is_admissible("CN", "AD", delta_t_days=200)
print(ok)  # False — CN->AD requires >=365 days (Jack 2018)

Full audit pipeline (canonical pattern)

from neurotcs import audit, load_rulepack
from neurotcs.input_contract.v1_1.adapters.adapter_adni_canonical import (
    load_adni_trajectories,
)

pack = load_rulepack("ad/niaaa_2018")
trajectories, report = load_adni_trajectories(
    dxsum_rda_path="/path/to/ADNIMERGE2/data/DXSUM.rda",
    hash_ids=False, skip_invalid=True,
)
result = audit(trajectories, pack, bootstrap_B=10_000, seed=42, ci_method="bca")

print(f"cTCS:        {result.ctcs.ci.point:.6f}")   # 0.994575 (v1.20.0 locked)
print(f"audit_id:    {result.audit_id}")            # 7a973f7b... (v1.20.0 locked)
print(f"audit_id_v2: {result.audit_id_v2}")         # dda642ff... (v1.20.0 locked)
result.to_json("report.json")

Worked examples for all four cohorts: see tests/audit_core/test_real_*.py (each test reproduces a locked invariant) and examples/ (runnable demos).

CLI

neurotcs-audit audit \
  --predictions predictions.csv \
  --rulepack ad/niaaa_2018 \
  --output report.json \
  --bootstrap 10000 --seed 42 \
  --patient-col RID --date-col EXAMDATE --state-col DIAGNOSIS \
  --state-label-map Dementia=AD

Reviewer verification

For third-party reviewers (FDA technical staff, pharma diligence, academic peer reviewers, hospital AI governance):

• v2 canonical protocol: docs/reviewer_package/reviewer_verification_prompt.md — 8-step manual reproduction (~90 min). Produces signed YAML attestation.
• Cursor IDE prompt: docs/reviewer_package/cursor_verification_prompt.md — AI-guided execution (~30 min).
• Colab notebook: docs/reviewer_package/NeuroTCS_v1.8.0_Reviewer_Verification.ipynb — browser-only zero-install preview (~10 min, synthetic-data demo).

All three surfaces produce the same YAML attestation schema and reference the same locked invariants. The Colab path can only achieve FRAMEWORK_INSTALL_VERIFIED (DUA-controlled data cannot be uploaded to third-party cloud); local paths can achieve FULL_REPRODUCED.

Specification

The canonical spec is docs/spec/temporalmetric_v1.7_FINAL.md. Read this to understand:

• §A.2 — Coherence Temporal Consistency Score (cTCS) definition
• §A.3 — Probabilistic TCS with matrix exponential M(Δτ) = exp(Q · Δτ / 365)
• §A.4 — Unified TCS (weighted ensemble)
• §A.5 — Cluster bootstrap (B = 10,000) + Huber M-estimation (c = 1.345)
• §B.1 — Aims 1–6 validation plan
• §B.2 — Required datasets (ADNI, OASIS-3, NACC, MIRIAD; ALZ-NET planned)
• §B.6 — Rule pack registry and engineering discipline
• §C — Library architecture

Roadmap to v0.2 / v1.0 / Q-Sub

• v1.8.0 (May 2026) — Four-cohort triangulation lock + ADNI canonical source. ✅ shipped.
• v1.8.1 (May 2026) — Documentation, test hygiene, CI matrix, reference-adapter reorganization, citation backfill. ✅ shipped.
• v1.9.0 (May 2026) — AD-only scope contraction: non-AD rule packs (PD, MS, oncology, stroke, lung nodule) extracted to seed future per-disease repositories post-FDA-clearance. ✅ shipped.
• v1.9.x (Q3 2026) — Piece 5 (FHIR output) + Piece 7 (validation harness) + cohort-specific transition priors.
• W22 (~Sept 2026) — Nature Medicine submission with AD validation across ADNI + OASIS-3 + NACC + MIRIAD.
• Oct 2026 — ASFNR Newport Beach workshop demo.
• Q1 2027 — FDA Q-Submission with v1.0.0 release.

Citation

@software{salokhiddinov2026neurotcs,
  author    = {Salokhiddinov, Marufjon},
  title     = {NeuroTCS: Citation-locked, fail-closed longitudinal medical AI audit framework},
  version   = {1.20.0},
  year      = {2026},
  url       = {https://github.com/DrMaruf1991/NeuroTCS},
  note      = {temporalmetric v1.7 FINAL specification, 3 AD production rule packs, four-cohort triangulation lock; v1.9.0+ AD-only scope}
}

See CITATION.cff for GitHub's citation widget.

Known limitations (honestly disclosed)

NeuroTCS publicly documents what is NOT yet covered so reviewers can assess fitness for purpose. The complete, current gap disclosure — spanning methodological, validation, fairness, and regulatory-status gaps — is maintained as a single source of truth in docs/datasheet/ad_neurotcs_datasheet.md Section F — Honest gaps acknowledged.

To avoid drift, the README does not duplicate the list here; Section F is authoritative (enforced by tests/docs/test_gap_disclosure_single_source.py). These gaps do not invalidate the reproducibility evidence — they define the scope within which it is interpretable.

License

Apache 2.0 — see LICENSE. The cited published guidelines remain © their respective publishers; this package transcribes them into machine-readable form for academic / regulatory audit purposes under fair-use interpretation. NeuroTCS does NOT redistribute the publications themselves.

Contact

Dr. Marufjon Salokhiddinov, MD PhD ESOR-BRACCO-ESNR Neuroimaging Fellow Kimyo International University in Tashkent (KIUT), Uzbekistan

Issues and contributions via GitHub.