Tagged MRI
Tagged MRI is the CardiacNexus route for tagged-image myocardial deformation features. It is kept separate from cine-derived SAX/LAX strain because the backend, input preparation, timeseries, and QC expectations differ.
- Modality
- Tagged MRI
- UKB source
- Data Field 20211
- Pipeline step
- Tagged-image H5 preparation, tagged prediction pipeline, global and slice-level strain extraction, derivative/timing analysis
- Outputs
- strain_tagged.csv, timeseries/strain_tagged.npz, tagged strain plots and GIF outputs
- Maturity
- Source-audited high-risk modality page
Current pipeline role
The current source expects three tagged MRI files per subject: tag_1.nii.gz, tag_2.nii.gz, and tag_3.nii.gz, corresponding to basal, mid-ventricular, and apical slices. Each slice is converted to a 20-frame, 256 by 256 H5 input for the tagged prediction pipeline. Shorter series are padded, longer series are truncated to the first 20 frames.
The resulting basal, mid, apical, and global circumferential/radial strain curves are written to timeseries/strain_tagged.npz. The CSV contains selected slice/global strain extrema, global strain-rate rows, time-to-peak rows, and optional RR-indexed timing rows when ECG rest data are available.
Current outputs
| Output family | Current rows | Source path | Notes |
|---|---|---|---|
| Slice/global tagged strain | basal, mid, apical, and global circumferential/radial strain rows | src/feature_extraction/Tagged_20211/eval_strain_tagged.py | percent units; method-specific sign convention retained |
| Global tagged strain rate | peak systolic and early diastolic circumferential/radial strain-rate rows | eval_strain_tagged.py; analyze_time_series_derivative | conditional on derivative peak detection |
| Tagged timing | time-to-peak circumferential/radial strain rows and optional RR-indexed timing rows | eval_strain_tagged.py; ECG processor | timing index requires usable ECG rest data |
| Timeseries and plots | timeseries/strain_tagged.npz, gcs_tagged.png, grs_tagged.png, gcsr_tagged.png, grsr_tagged.png | eval_strain_tagged.py | plot generation depends on successful strain extraction |
High-risk method area
Tagged MRI outputs are deformation-sensitive. Backend changes need regression checks and a fallback strategy before replacement. Do not merge tagged rows with cine SAX/LAX strain without explicit method labels.
QC and interpretation caveats
Tagged MRI rows require all three tagged slices, successful H5 preparation, successful prediction-pipeline execution, and stable derivative peak detection. Padding or truncation to 20 frames is part of the current contract and should be documented whenever timing metrics are compared across cohorts.
The current source removes the temporary tagged H5 workspace after extraction. Failures before cleanup, prediction-pipeline dependency problems, missing ECG rest data, or extreme derivative behavior can change which rows are present for a subject.
Source audit
- Current input names, H5 preparation rules, backend invocation, CSV output families, NPZ keys, ECG-dependent timing rows, and plot paths were checked against
eval_strain_tagged.py. docs/data/output_column_inventory.ymlrecords thestrain_taggedartifact contract, and the ventricular mechanics page documents the current tagged rows.- Textbook context boundary: broad clinical textbook context is not surfaced here because tagged method papers and source implementation are sufficient for draft rollout.
- Displayed figure provenance is recorded in
docs/data/figure_provenance.yml; permission and exact reuse wording remain pending for public release.