retinalysis-vascx: An explainable software toolbox for the extraction of retinal vascular biomarkers

Automatic extraction of retinal vascular biomarkers from color fundus images (CFI) is crucial for large-scale studies of the retinal vasculature, and this paper presents VascX, an open-source software toolbox that extracts these biomarkers from artery-vein segmentations to provide explainable and flexible biomarker extraction.

The gist

VascX provides an explainable and flexible biomarker extraction toolbox that utilizes artery-vein and optic disc segmentations and fovea locations for region-aware biomarker extraction.

Methods of Biomarker Computation

VascX operates through a structured pipeline involving four core computation stages applied to artery and vein model segmentations. These stages are:

1. Skeleton: We first hole‑fill the predicted binary vessel map to obtain a clean binary mask; when an optic disc mask is available, the disc region is excluded to prevent spurious centerlines. This yields single-pixel-wide centerlines that preserve network topology.

2. Undirected graph: From the skeleton, we build a NetworkX Graph whose nodes correspond to end/junction points and whose edges follow the chain of centerline pixels between them. This representation supports segment-level filtering and aggregation without yet imposing flow direction.

3. Directed digraph: We orient the undirected graph into a DiGraph by rooting each connected component at the optic disc and directing edges away from the disc. Vessel segments are directed edges carrying geometry and derived properties (length, median diameter, curvature).

4. Resolved vessels: To facilitate the computation of biomarkers on longer, potentially more anatomically relevant vessel trajectories, we run a recursive vessel‑resolution algorithm on the DiGraph. This reduces fragmentation while preserving topology for trajectory-level tortuosity and OD–fovea–aligned measures.

Implemented Biomarkers

VascX computes a comprehensive catalog of morphology, topology, caliber, and spatially localized biomarkers from artery-vein segmentations. Key implemented biomarkers include:

(Mask-based)

(Vascular Density):

The fraction of retinal area occupied by vessels in R, computed on the binary mask B: D = B ∩ R / R.

(Bifurcation Angles):

"For each bifurcation b at position pb, outgoing branch directions are estimated by sampling the branches’ splines at distance δ from the node along each branch at points q1 and q2. The bifurcation angle is defined as the angle between these vectors: θb = arccos(ub ⋅ vb)."

(Caliber):

For each segment i, diameters are sampled along a spline fitted to its skeleton by projecting spline normals to the vessel boundary on B. The per‑segment diameter is the median along its arclength.

(Tortuosity):

VascX provides three complementary measures per segment (or resolved vessel): Distance factor (DF = Larc,i / Lchord,i), Curvature-based measure (Tικ), and Inflection count (TιINF).

Region-Aware Computation and Localization

A core feature of VascX is its ability to compute biomarkers over specific regions defined relative to the fovea and optic disc landmarks. This is achieved by implementing several standard grids:

(DiscCenteredGrid):

disc-anchored rings (inner, center, outer) and hemifields (superior, inferior, nasal, temporal, plus left/right), taking laterality into account. This grid is meant for consistent measurements on disc-centered images.

(CircleGrid):

circle centered along the OD-fovea axis (radius derived from OD–fovea distance and disc size). This grid provides consistent measurements on macula-centered images.

The software detects when a region of interest is out of bounds and returns a null value rather than an invalid measurement.

Reproducibility and Sensitivity Analysis

The paper presents an in-depth evaluation of VascX biomarker robustness via cross-device testretest reproducibility analysis using the Rotterdam Study cohort. The results show that:

(Reproducibility):

"most VascX biomarkers have moderate to excellent agreement (ICC > 0.5), with important differences in the level of robustness of different biomarkers. Whole-image length-weighted tortuosity and CREs stood out as the most reproducible biomarkers. Bifurcation angles, vascular densities, and ETDRS-localized biomarkers were the least reproducible biomarkers, often due to a lack of robustness against segmentation mistakes such as missing vessels or vessel mislabeling."

(Sensitivity):

The analysis of biomarker sensitivity to image perturbations showed that global tortuosity, calibers, CREs, and artery-vein ratios were more robust to perturbation. Conversely, the lower robustness of bifurcation angles and ETDRS-localized biomarkers was consistent with the findings from reproducibility analysis.

Based on the scientific paper retinalysis-vascx: an explainable software toolbox for the extraction of retinal vascular biomarkers from color fundus images, here are specific, high-impact improvements that can be made to existing or future AI systems, along with what these improved systems could achieve.

The core improvement lies in shifting from purely black-box deep learning segmentation to a modular, explainable, and region-aware graph-based biomarker extraction framework.

Here are the specific improvements:

Shift Segmentation Dependency to Explainable Graph Computation:

Use the VascX pipeline's four computation stages (Skeletonization → Undirected Graph → Directed Digraph → Resolved Vessels) as a standardized, explainable intermediate representation, rather than relying solely on the output of a single end-to-end deep learning model.

Implement Region-Aware Computation:

Integrate explicit spatial metadata—specifically the localization of the fovea and optic disc—into biomarker computation stages (e.g., calculating Vascular Density, CRE, Tortuosity) using defined grids (ETDRSGrid, CircleGrid) to enable localized measurements over anatomically relevant regions.

Enhance Robustness via Cross-Device Reproducibility Scoring:

Develop a post-processing or validation layer that automatically assesses the reliability of extracted biomarkers by calculating Intra-Class Correlation Coefficients (ICC(2,1)) across multiple imaging devices and image quality conditions. This system should flag biomarkers with low robustness (e.g., bifurcation angles in ETDRS regions) for mandatory manual review or require dynamic adjustment of heuristic parameters.

Integrate Sensitivity Analysis into Model Training/Validation:

Implement a perturbation pipeline that systematically applies domain-relevant artifacts (blur, illumination changes, noise) to input images and measures the resulting change in biomarker values (MAE and ICC(2,1)). This allows the AI system to be trained or validated not just on accurate segmentation, but on the stability of the derived biomarkers against expected real-world image degradation.

Introduce Heuristic Parameter Optimization:

Develop a mechanism that systematically sweeps or optimizes heuristic parameters (e.g., spline smoothing parameters for tortuosity, radii for CRE circles) to find the configuration that maximizes biomarker reproducibility across different datasets or devices, moving beyond simple sensible defaults.

The resulting improved AI system (a VascX-Enhanced Oculomics Platform) can achieve the following:

Standardized and Reproducible Biomarker Cataloging: The system will provide a comprehensive catalog of morphology, topology, caliber, and spatially localized biomarkers derived from any input CFI image. Unlike current systems that output single metrics without context, this system will produce a full set of measurements (e.g., Density across the ETDRS grid; CRE centered on the OD) for every relevant region.

Explainable Decision-Making: Because the computation flows through discrete stages (skeleton to directed graph), researchers can trace exactly how a final biomarker value was derived—identifying whether it was influenced by segmentation errors, graph topology choices, or specific geometric calculations like bifurcation angles. This dramatically increases trust in AI-derived results.

Clinical and Epidemiological Scalability: By incorporating region-aware measurements (e.g., OD–fovea axis alignment), the system will produce harmonized data suitable for large-scale population studies and longitudinal biobanks, ensuring that measurements from different clinics or devices are comparable without requiring extensive manual normalization.

Reliable Risk Prediction: By explicitly quantifying the robustness of different biomarkers across various imaging conditions (via ICC scoring) and image perturbations, the system can provide researchers with a confidence score for any given biomarker measurement, allowing for more reliable association studies linking specific retinal features to systemic outcomes like hypertension or stroke risk.

Automatic extraction of retinal vascular biomarkers from color fundus images (CFI) is crucial for large-scale studies of the retinal vasculature. We present VascX, an open-source Python toolbox that extracts biomarkers from CFI artery-vein segmentations. VascX starts from vessel segmentation masks, extracts their skeletons, builds undirected and directed vessel graphs, and resolves vessel segments into longer vessels. A comprehensive set of biomarkers is derived, including vascular density, central retinal equivalents (CREs), and tortuosity. Spatially localized biomarkers may be calculated over grids placed relative to the fovea and optic disc. VascX is released via GitHub and PyPI with comprehensive documentation and examples. Our test-retest reproducibility analysis on repeat imaging of the same eye by different devices shows that most VascX biomarkers have moderate to excellent agreement (ICC > 0.5), with important differences in the level of robustness of different biomarkers. Our analyses of biomarker sensitivity to image perturbations and heuristic parameter values support these differences and further characterize VascX biomarkers. Ultimately, VascX provides an explainable and easily modifiable feature-extraction toolbox that complements segmentation to produce reliable retinal vascular biomarkers. Our graph-based biomarker computation stages support reproducible, region-aware measurements suited for large-scale clinical and epidemiological research. By enabling easy extraction of existing biomarkers and rapid experimentation with new ones, VascX supports oculomics research. Its robustness and computational efficiency facilitate scalable deployment in large databases, while open-source distribution lowers barriers to adoption for ophthalmic researchers and clinicians.