Outputs and data model
CardiacNexus outputs are designed for subject-level tabular analysis and time-resolved inspection of curves, segmentations, landmarks, and QC plots. The documentation treats output names as downstream-facing contracts.
- Modality
- All modalities
- Pipeline step
- Feature extraction, aggregation, registry validation, and documentation validation
- Outputs
- CSV, NPZ, QC artifacts, landmarks, visualizations, source registries
- Maturity
- Source-audited data model page
Output families
| Output family | Purpose | Examples |
|---|---|---|
| Aggregate CSV files | Subject-level phenotype tables keyed by eid | ventricular_volume.csv, atrial_volume.csv, aortic_flow.csv, native_T1.csv |
| Per-subject feature rows | Modality-specific extracted values before aggregation | feature folders such as ventricle, atrium, aortic_flow, strain_sax |
| NPZ time series | Curves and frame indices across cardiac phases | ventricle.npz, atrium.npz, aorta.npz, strain_sax.npz, strain_tagged.npz |
| QC images and plots | Manual/scripted inspection of masks, landmarks, curves, and tracking | segmentation overlays, time-series plots, aortic mesh views |
| Landmark and mesh artifacts | Geometry anchors used in selected measurements | valve landmarks, AV plane plots, aortic mesh outputs |
| Segmentation files | Intermediate masks used for feature extraction | seg_sa.nii.gz, seg_la_4ch.nii.gz, seg_aortic_flow.nii.gz, seg_shmolli_t1map.nii.gz |
Contract rules
Every tabular output should have a stable primary key, normally eid. Units are carried in column names where useful, such as [mL], [mL/m^2], [g], [g/m^2], [cm], [mm], [%], or [1/s]. Legacy spellings and labels are preserved unless there is an explicit schema migration.
Column names are contracts
The exact output column strings documented on phenotype pages should not be changed silently. Even obvious typos, such as legacy Maxium labels, are compatibility issues rather than cosmetic text.
Missingness and conditional rows
Not every documented row is present for every subject. Common reasons include segmentation QC failure, absent BSA, absent ECG rest data, invalid pressure data, failed derivative peak detection, impossible timing relationships, or backend-specific tracking failures. Phenotype pages should state whether a row is current, conditional current, planned, or literature-only context.
Registry layer
docs/data/output_column_inventory.yml records artifact-level contracts. docs/data/phenotype_dictionary.yml links documented features to exact output rows and related pages. docs/data/reference_sources.yml and docs/data/reference_range_sources.yml record source and reference-range context for the documentation layer. These registries support validators but do not replace source-code audit.
Source audit
- Output families and conditional-row behavior were checked against current feature pages, output inventory, and phenotype dictionary.
- Registry roles were checked against
docs/data/**and the current generic phenotype validator. - Textbook context boundary: broad clinical textbook context is not surfaced here because this page documents output contracts rather than clinical disease interpretation.