ClarusC64/clinical-quad-cardiac-load-reserve-lag-coupling-heart-failure-transition-v0.4

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.

cardiacload physiologicalreserve interventiondelay organcoupling

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.

driftvelocity driftacceleration 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.

perturbationradius collapsetrigger

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

labelheartfailure_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

cardiacload physiologicalreserve interventiondelay organcoupling

driftgradient driftvelocity driftacceleration boundarydistance

perturbationradius collapsetrigger

labelheartfailure_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 recallboundarydetection falsesaferate f1 confusion_matrix

Primary metric

recallboundarydetection

Secondary diagnostic metric

falsesaferate

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.