KinetiQC is a CPU-first research framework for measuring when shortened, sparsely sampled, noisy, blurred, or motion-corrupted dynamic PET acquisitions stop preserving quantitative conclusions—and whether compact temporal models can recover them.
Dynamic PET estimates depend on the acquisition protocol as well as the underlying biology. KinetiQC asks:
How far can a dynamic brain PET acquisition be degraded or shortened before its quantitative biological conclusions become unreliable?
The project evaluates this question at several levels: model-free kinetics, known intervention effects, reference-tissue modeling when scientifically available, regional kinetic covariance/connectivity, dynamic radiomics, and downstream recovery after temporal signal reconstruction.
- A lazy, PET-BIDS/NIfTI-compatible data model that preserves actual unequal frame starts and durations.
- Reproducible, on-the-fly acquisition perturbations without storing dozens of duplicate 4-D images.
- Duration-aware TAC integration, temporal windows, slopes, moments, PCA/NMF signatures, and ground-truth comparisons.
- A small 3,297-parameter masked temporal convolutional network with subject-disjoint evaluation and strong interpolation/PCA baselines.
- Explicit raw, normalized, global-residual, and derivative regional PET covariance/connectivity analyses.
- A transparent first-order and 3-D GLCM dynamic-radiomics catalog with fixed clean-baseline discretization.
- A resumable three-subject final benchmark using subject-level statistics, paired comparisons, bootstrap confidence intervals, a machine-readable reliability frontier, and an automated report.
- A Streamlit explorer that consumes cached CSV/NPZ products and never launches expensive experiments interactively.
The primary benchmark is the simulated NRM2018 PET Grand Challenge dynamic brain PET dataset, using the public PET-BIDS conversion OpenNeuro ds001705. It provides baseline and pharmacological-displacement conditions, six supplied changed-region masks, and documented binding changes.
The files—not remembered metadata—are authoritative. In the inspected snapshot:
- PET sidecars contain 23 entries in
FrameTimesStartandFrameDuration, ending at 5,400 seconds. - PET values report
kBq/mL. - supplied masks contain labels 1–6 although the TSV declares 101–106; KinetiQC records the explicit ROI-number reconciliation;
- PET and masks have a
[0.5, -0.5, -0.5]mm affine-origin difference, handled by warned nearest-neighbor resampling; - no validated cerebellar/reference-region mask or kinetic parameter maps were found in this OpenNeuro distribution.
Accordingly, the final SRTM estimate is marked unavailable rather than inferred from an unsupported reference ROI. The original NITRC distribution can also be discovered when supplied as Analyze .img/.hdr with recognized .anc timing.
Raw imaging data are ignored by Git. See data/README.md and docs/PROVENANCE.md.
For frame-average activity Cᵢ, start sᵢ, duration Δᵢ, and midpoint tᵢ = sᵢ + Δᵢ/2, KinetiQC uses
AUC = Σ Cᵢ Δᵢ
time-normalized AUC = AUC / Σ Δᵢ
Window statistics use the exact temporal overlap between each PET frame and the requested physical-time window. Slopes use duration-weighted regression against actual mid-times. Temporal center of mass, variance, and entropy use nonnegative activity mass max(Cᵢ,0)Δᵢ. Rebinning computes duration- or count-weighted means so integrated activity is preserved when scientifically appropriate.
Agreement outputs include MAE, RMSE, Pearson and Spearman association, bias, percent error, Lin concordance, and ICC(A,1). The final analysis first summarizes each endpoint within each subject; its percentile bootstrap resamples the three subjects, never millions of voxels or ROIs as independent observations. Matched method comparisons are descriptive paired subject differences with bootstrap intervals and no excessive hypothesis-test catalog.
The YAML scenario system supports:
- complete-frame truncation at requested physical acquisition endpoints;
- every-Nth retention, duration-weighted adjacent-frame merging, fixed temporal gaps, and seeded random masking;
- approximate pseudo-Poisson count degradation at several retained-count fractions;
- millimetre-specified Gaussian blur;
- isolated, drifting, and random rigid frame motion with every transform recorded.
Pseudo-count degradation is explicitly a signal/count stress approximation, not sinogram, attenuation, scatter, reconstruction, or scanner-physics simulation. The final bounded matrix avoids a factorial explosion: clean; 60/45/30 minutes; every-second/every-third sampling; 50%/25% counts; 4 mm blur; isolated 1 mm motion; and 2 mm drift.
Model-free TAC endpoints include AUC, normalized AUC, early/middle/late uptake, early-to-late ratio, peak/time-to-peak, wash-in and late slopes, temporal centroid/variance, coefficient of variation, entropy, and duration-weighted PCA/NMF signatures. TACs are extracted for global support, the supplied changed regions, a deterministic unaffected comparison sample, optional atlas regions, and an explicit reference mask when available.
SRTM basis-function fitting is implemented for a validated reference TAC:
Cₜ(t) = R₁ Cᵣ(t) + (k₂ - R₁k₂a) [Cᵣ(t) * exp(-k₂a t)]
BPₙd = k₂/k₂a - 1
The final real-data SRTM row is intentionally unavailable because no supported reference ROI was found. Synthetic unit tests recover controlled SRTM parameters.
TinyMaskedTCN is a three-block residual 1-D convolutional network with 16 hidden channels, dilations 1/2/4, and 3,297 trainable parameters. Inputs include observed values, binary observation mask, physical mid-times, frame durations, missing fraction, and count-loss indicator. Its loss is duration weighted.
Three rotating folds keep training, validation/early stopping, and test subjects disjoint. Baselines include zero fill, linear interpolation, PCHIP, training-subject population mean, and PCA. On 40%-masked held-out ROI TACs, final subject-level median absolute AUC errors were:
| Method | AUC error | Normalized TAC RMSE |
|---|---|---|
| PCA | 1.13% | 0.221 |
| Linear interpolation | 1.17% | 0.126 |
| Fixed-mask timing TCN | 1.38% | 0.122 |
| Variable-mask timing TCN | 2.57% | 0.131 |
| Uncorrected zero fill | 37.84% | 0.656 |
The lower TCN signal RMSE did not imply better AUC recovery than interpolation/PCA. This is a central result: reconstruction quality must be judged by downstream quantitative recovery, not smooth appearance alone.
The connectivity module estimates temporal/metabolic or kinetic covariance from regional dynamic PET TACs. It does not claim neuronal, functional, directional, or causal connectivity.
The reproducible parcellation is the 48-region Harvard–Oxford cortical 25% maximum-probability atlas. Both resources are described in MNI coordinates, but the nearest-neighbour template overlay is not asserted to be validated subject-specific registration. The official atlas can be obtained through Nilearn; an existing official FSL/Nilearn cache can be read offline with XML label provenance.
Explicit preprocessing choices are raw TACs, regional z-scores, global normalization, global-component removal, and derivatives using actual midpoint differences. Estimators include Pearson, Spearman, Ledoit–Wolf shrinkage covariance, and regularized partial correlation. Reliability includes edge-vector correlation/rank stability, normalized Frobenius distance, top-edge overlap, and node-metric stability.
The default implementation is a small transparent NumPy/SciPy catalog rather than a mandatory PyRadiomics dependency. Per-frame features include mean/median, variance/standard deviation, percentiles, entropy, skewness, excess kurtosis, coefficient of variation, and four symmetric 13-direction 3-D GLCM features: contrast, homogeneity, joint energy, and correlation.
For each subject/ROI, 32 intensity bins are anchored to pooled clean-baseline 1st/99th percentiles and reused across both conditions and every perturbation. Feature trajectories receive duration-aware AUC/mean, early-to-late ratio, slope, temporal variability, peak/time-to-peak, and PCA/NMF representations. GLRLM/GLSZM are omitted to bound computation and interpretive breadth.
ROI TAC reconstruction is evaluated only for mean-uptake temporal summaries. It cannot restore voxel distributions or spatial textures, and the project does not claim otherwise.
The final benchmark used OpenNeuro subjects 000101–000103 with both baseline and displaced sessions. Values below are means of subject-level summaries with 95% percentile subject-bootstrap intervals where shown. These are descriptive three-subject pilot observations, not clinical protocol recommendations.
| Endpoint | 60 min | 45 min | 30 min | Every 3rd frame | 50% counts | 2 mm drift |
|---|---|---|---|---|---|---|
| Normalized-AUC relative error | 21.49% | 34.50% | 48.14% | 2.68% | 0.013% | 0.98% |
| Intervention-effect MAE (pp) | 1.20 | 1.78 | 2.42 | 1.82 | 0.016 | 0.62 |
| Raw-Pearson matrix correlation | 0.998 | 0.996 | 0.987 | 0.988 | 1.000 | 0.999 |
| Median radiomic normalized error | 16.23% | 27.91% | 40.26% | 10.42% | 0.37% | 3.06% |
Normalized-AUC error CIs were 19.86–23.08% at 60 minutes, 29.61–40.19% at 45 minutes, and 39.43–59.72% at 30 minutes. Under the explicit project thresholds, truncated model-free and radiomic catalogs failed at 60/45/30 minutes, while the raw Pearson regional matrix remained above its configured matrix-similarity threshold. High matrix stability may partly reflect shared global tracer kinetics and must not be overinterpreted.
The low ROI-level pseudo-count errors reflect averaging over large masks under the chosen signal-domain approximation; they do not show that true low-count PET reconstruction is harmless.
See the automatically generated final benchmark report, machine-readable results, and reliability frontier. The report is regenerated from CSVs so numeric prose does not silently drift from current outputs.
 |
 |
 |
 |
 |
 |
Python 3.8+ is supported. A clean environment is recommended.
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev,ml,app]"Core dependencies include NumPy, pandas, SciPy, nibabel, Nilearn, scikit-learn, Matplotlib, Plotly, and PyYAML. PyTorch is isolated in the ml extra; Streamlit is in app; SimpleITK/PyRadiomics remain optional in radiomics.
Review the current official download listing before transferring images:
python scripts/download_nrm2018.py --dry-run
python scripts/download_nrm2018.py --subjects 000101 000102 000103 --include-images --max-gb 15
python scripts/prepare_dataset.py data/raw/openneuro/ds001705Run individual stages:
kinetiqc quantify data/raw/openneuro/ds001705 --subjects 000101 000102 000103 \
--output-root outputs/quantification-real --voxel-sample 160 --no-figures
kinetiqc stress data/raw/openneuro/ds001705 --config configs/stress_nrm2018.yaml
python scripts/train_temporal_model.py outputs/quantification-real \
--config configs/temporal_ml.yaml --output-root outputs/temporal-ml
kinetiqc connectivity data/raw/openneuro/ds001705 --config configs/final_connectivity.yaml
kinetiqc radiomics data/raw/openneuro/ds001705 --config configs/final_radiomics.yamlRun/resume the bounded final experiment and regenerate the narrative:
kinetiqc benchmark --config configs/final_benchmark.yaml
python scripts/generate_final_report.py --config configs/final_benchmark.yamlCompleted stages and per-scenario artifacts are reused unless --force is passed. For a fast data-free verification:
python -m pytest -q
kinetiqc smoke --output-dir outputs/cache/smokeConvenience targets are also provided in Makefile.
python -m pip install -e ".[app]"
streamlit run app/app.pyThe explorer has tabs for overview findings, one-frame-at-a-time PET/TAC viewing, measured reliability controls, kinetic/ground-truth outputs, connectivity matrices and differences, and radiomic trajectories/rankings. It reads the existing compact outputs. If raw PET is absent, only the optional slice viewer is disabled.
KinetiQC/
├── app/ # cached-output Streamlit explorer
├── configs/ # deterministic pipeline/benchmark YAML
├── data/ # ignored raw data; tracked documentation/manifests
├── docs/ # provenance and reproducibility notes
├── outputs/final-benchmark/ # compact final report, tables, and figures
├── scripts/ # download, processing, training, evaluation, reports
├── src/kinetiqc/ # IO, kinetics, stress, ML, connectivity, radiomics
├── tests/ # synthetic, data-independent unit/integration tests
├── CITATION.cff
├── LICENSE
└── pyproject.toml
The design target is 8 GB RAM, no GPU, and less than 100 GB free storage. ROI extraction materializes one frame at a time; uncompressed .nii files are memory mapped where possible. Subjects and sessions are processed sequentially. Repeated analyses use compact ROI TACs, feature tables, 48×48 matrices, and small checkpoints. No degraded 4-D NIfTI is written by default.
The final temporal models trained on CPU. Image-domain radiomics is the slowest component because each retained frame computes 3-D texture, but its per-scenario feature tables make the run resumable.
- The final benchmark has three simulated subjects; confidence intervals are coarse and learned-model conclusions are preliminary.
- NRM2018 is an important controlled benchmark but does not establish clinical generalization.
- The inspected distribution lacks a validated reference mask and kinetic maps, so real SRTM/parameter-map validation is unavailable.
- Atlas overlay is transparent MNI template-to-template alignment, not validated subject-specific registration.
- Count degradation is an approximate signal-domain experiment, not end-to-end PET reconstruction physics.
- Regional correlation can be driven by global tracer kinetics, temporal autocorrelation, and preprocessing.
- Baseline/displaced scans are not same-biology test–retest data.
- ROI TAC correction cannot recover spatial texture.
- Reliability thresholds are configurable research criteria, not universal clinical standards.
- Validate reference-tissue estimates against the original release or a study-validated cerebellar mask.
- Expand subject-disjoint evaluation and uncertainty estimation beyond the three-subject pilot.
- Add reconstruction-physics-informed count experiments and measured scanner motion.
- Validate atlas alignment or use subject-specific anatomy where available.
- Compare endpoint-aware training losses against signal-reconstruction losses.
- Prospectively test the reliability frontier on independent tracers and scanners.
KinetiQC is released under the MIT License. Cite the software using CITATION.cff. Dataset users should also cite and follow the terms of the exact NRM2018/OpenNeuro distribution used. The inspected metadata present a license discrepancy between the OpenNeuro conversion and the original NITRC page; this repository does not resolve that discrepancy, so verify reuse terms before redistributing data.
The reference-tissue implementation follows the established simplified reference tissue model/basis-function literature. The project’s dataset links and relevant method references are collected in docs/PROVENANCE.md.