# What this repo does This repository contains a Clarus v0.4 cascade boundary discovery dataset modeling heart failure transition. Earlier Clarus datasets focused on detecting cascade states or forecasting collapse trajectories. Version v0.4 extends the framework to a harder task: detecting whether a system lies on the instability boundary itself. The dataset models heart failure deterioration as a coupled physiological system in which cardiac load, declining reserve, delayed intervention, and rising organ coupling combine to push the system toward collapse. The objective is to determine when the system is close enough to collapse that even small perturbations can trigger heart failure transition. # Core quad The core heart failure system is modeled using four coupled variables. cardiac_load physiological_reserve intervention_delay organ_coupling These variables represent interacting components of cardiovascular instability. cardiac_load captures rising hemodynamic burden and stress on cardiac function. physiological_reserve represents remaining adaptive capacity and systemic resilience. intervention_delay captures delays in stabilizing treatment or corrective action. organ_coupling represents how tightly dysfunction is propagating across organ systems. The quad structure models how these factors interact rather than acting independently. # Trajectory layer The trajectory field describes the direction of system motion. drift_gradient Range -1 to +1 Interpretation negative values indicate movement away from instability. positive values indicate movement toward cascade. This variable describes whether the cardiovascular system is stabilizing or drifting toward collapse. # Dynamic forecasting layer The dynamic layer captures how quickly instability is developing. drift_velocity drift_acceleration boundary_distance drift_velocity describes the speed of deterioration. drift_acceleration captures whether that deterioration is accelerating. boundary_distance estimates the system's proximity to the instability boundary. Together these fields describe the system's motion through the stability landscape. # Boundary discovery layer Version v0.4 introduces an explicit boundary discovery layer. Two variables measure how close the system is to instability under perturbation. perturbation_radius collapse_trigger These variables convert the dataset from collapse forecasting into cascade boundary discovery. Models must determine whether the system lies safely inside the stability region or on the edge of the instability manifold. # Boundary variable definitions ## perturbation_radius Minimum normalized perturbation required to push the system across the cascade boundary. Definition perturbation_radius = min ||δx|| such that x(t) + δx → cascade Interpretation small values indicate the system is extremely close to instability. large values indicate strong stability margin. Range 0 to 1 ## collapse_trigger Binary indicator describing the observed response of the system to perturbation. 0 system remains stable 1 system crosses the instability boundary collapse_trigger is included as an observed perturbation response feature. It records whether the simulated perturbation produced cascade in that scenario. Importantly, collapse_trigger is not the prediction target. The prediction task is to determine the underlying boundary-risk state of the system. collapse_trigger therefore acts as an auxiliary signal describing perturbation outcome rather than the classification label itself. Systems close to instability often show collapse_trigger = 1 because very small perturbations can push them into cascade. # Prediction target Target column label_heart_failure_transition The binary label indicates that the heart failure system lies on the instability boundary. A positive label is triggered when either condition holds. boundary_distance < 0.10 or perturbation_radius < 0.08 These thresholds represent complementary indicators of instability. boundary_distance measures how close the system trajectory is to the instability manifold. perturbation_radius measures how small a perturbation is required to trigger cascade. If either indicator crosses its threshold, the system is considered boundary vulnerable. This encodes minimal-perturbation cascade detection. # Binary simplification note This dataset intentionally simplifies heart failure transition into a binary boundary detection task. The objective is not to reproduce full cardiovascular physiology. The objective is to test whether models can identify when a coupled physiological system is close enough to collapse that small shocks produce transition. # Row structure Each dataset row contains scenario_id cardiac_load physiological_reserve intervention_delay organ_coupling drift_gradient drift_velocity drift_acceleration boundary_distance perturbation_radius collapse_trigger label_heart_failure_transition Normalization rules state variables range from 0 to 1 drift_gradient ranges from -1 to +1 drift_velocity ranges from 0 to 1 drift_acceleration ranges from -1 to +1 boundary_distance ranges from 0 to 1 perturbation_radius ranges from 0 to 1 collapse_trigger is binary # Files data/train.csv labeled training examples data/tester.csv unlabeled evaluation examples scorer.py binary boundary detection evaluation script README.md dataset documentation # Evaluation The scorer reports accuracy precision recall_boundary_detection false_safe_rate f1 confusion_matrix Primary metric recall_boundary_detection Secondary diagnostic metric false_safe_rate Boundary detection tasks prioritize recall because missing a boundary case means incorrectly labeling a near-collapse heart failure system as safe. # License MIT # Structural Note This repository is part of the Clarus dataset version ladder. v0.1 cascade state detection datasets v0.2 cascade plus trajectory detection datasets v0.3 cascade plus trajectory plus dynamic forecasting datasets v0.4 cascade plus trajectory plus dynamics plus boundary discovery datasets Earlier versions remain unchanged to preserve benchmark continuity. # Production Deployment This dataset is designed as a research and benchmarking artifact. Potential uses include instability detection benchmarking AI safety stress testing clinical deterioration modeling experiments cascade detection research early warning system prototypes The dataset is not intended for clinical decision making. # Enterprise & Research Collaboration For dataset expansion, custom coherence scorers, or deployment architecture: team@clarusinvariant.com Instability is detectable. Governance determines whether it propagates.