ClarusC64/clinical-quad-ventilation-stress-buffer-lag-coupling-ventilator-deterioration-v0.8

What this repo does

This repository provides a Clarus v0.8 clinical quad dataset for detecting and reasoning about ventilator deterioration regime transitions.

The dataset models situations where a patient state is no longer contained within a single ventilatory support basin but is shifting between competing regimes such as:

• —high-pressure ventilatory stress
• —hypoxemic ventilator failure
• —hypercapnic ventilator mismatch
• —multisystem ventilator-associated collapse

This is the conceptual upgrade introduced in Clarus v0.8.

Earlier ladder versions detect instability, forecast deterioration, estimate collapse boundaries, model recovery geometry, and reason about intervention.

v0.8 introduces regime transition geometry.

The system now measures not only distance to the nearest failure boundary but also distance to the nearest competing regime boundary.

This allows models to detect:

• —regime switching
• —competing failure modes
• —unstable regime identity
• —transition-aware intervention reasoning

Core quad

The four core variables in this dataset are:

• —ventilation_stress
• —respiratory_buffer
• —response_lag
• —system_coupling

Operational definitions:

ventilation_stress

Mechanical and physiologic burden imposed by the ventilatory strategy, airway pressures, and gas-exchange demand.

respiratory_buffer

Remaining pulmonary and physiologic reserve available to tolerate further ventilatory insult.

response_lag

Delay in ventilator adjustment, synchrony correction, or escalation after deterioration begins.

system_coupling

Degree to which ventilatory deterioration is propagating into hemodynamic or multisystem instability.

Clinical variable mapping

These mappings are illustrative rather than prescriptive.

The dataset encodes structural system state, not a single ventilator protocol.

Why the second boundary matters

Most instability detectors estimate only one quantity:

distance to the nearest collapse boundary.

This is insufficient for real ventilator deterioration.

A patient may appear to be worsening inside one ventilatory regime while the deeper reality is that they are crossing into a different failure basin.

v0.8 introduces:

secondary_boundary_distance

The model now measures:

distance to the current regime boundary distance to the competing regime boundary

This enables detection of regime competition.

When the two distances converge, regime identity becomes unstable.

The derived signal

boundary_competition_ratio

secondaryboundarydistance / boundary_distance

acts as a marker of this instability.

Values approaching 1 indicate a system positioned between regimes.

Structural Note

This dataset is part of the Clarus ladder.

The ladder reconstructs instability geometry step by step:

v0.1 cascade detection v0.2 trajectory awareness v0.3 cascade forecasting v0.4 boundary discovery v0.5 recovery geometry v0.6 intervention reasoning v0.7 uncertainty-aware intervention v0.8 regime transition geometry

Each rung increases resolution of the system state space.

v0.8 is the first rung where competition between instability basins is explicitly modeled.

That upgrade transforms Clarus from a collapse detector into a phase-transition instrument for complex systems.

Example regime competition row

A typical v0.8 ventilator deterioration scenario looks like this.

Interpretation:

The patient is close to the current regime boundary while a competing regime boundary is also nearby.

The system is transitioning from one unstable ventilatory state into another more dangerous support failure basin.

Prediction target

The prediction target is:

• —label_ventilator_deterioration

Default label rule:

• —label = 1 if stabilization_success = 1 and trajectory_shift < -0.10

Relaxed variant:

• —label = 1 if stabilization_success = 1

This preserves consistency with v0.6 and v0.7 while extending the geometry into v0.8 regime transition reasoning.

Row structure

Each dataset row contains layered signals.

Core state

ventilationstress respiratorybuffer responselag systemcoupling

Trajectory signals

driftgradient driftvelocity drift_acceleration

Boundary geometry

boundarydistance secondaryboundarydistance boundarycompetition_ratio

Uncertainty layer

boundaryuncertainty trajectoryuncertainty regime_confidence

Regime transition layer

regimetransitionscore transitiondirection regimeseparationmargin transitionuncertainty transition_velocity

Perturbation and collapse markers

perturbationradius collapsetrigger

Recovery geometry

recoverydistance recoverygradient return_feasibility

Intervention vector

deltaventilationstress deltarespiratorybuffer deltaresponselag deltasystemcoupling

Outcome fields

trajectoryshift minimalinterventionpath stabilizationsuccess labelventilatordeterioration in train only

tester.csv excludes:

stabilizationsuccess labelventilator_deterioration

Files

data/train.csv

Training rows including outcome labels.

data/tester.csv

Evaluation rows with labels removed.

scorer.py

Reference v0.8 evaluation script.

Returns:

Classification metrics

accuracy precision recall f1 confusion matrix

Regime transition diagnostics

recallregimetransitiondetection falsestableregimerate transitiondirectionaccuracy highuncertaintytransitionmissrate transitiondetectionaccuracy falsetransitionrate missedtransitionrate boundarycompetitionerror misidentifiedprimaryregime_rate

Additional information

support counts threshold transparency dynamic label column discovery

benchmark_spec.json

Machine-readable benchmark contract describing task type, target label, withheld fields, metric definitions, thresholds, and prediction-file requirements.

Evaluation

Primary metrics

recallregimetransition_detection

falsestableregime_rate

Transition diagnostics

transitiondirectionaccuracy highuncertaintytransitionmissrate missedtransitionrate boundarycompetitionerror misidentifiedprimaryregime_rate

Additional reference diagnostics

transitiondetectionaccuracy falsetransitionrate

The goal of evaluation is not only to test whether a model predicts the correct label.

It tests whether the model correctly detects regime transitions and their geometry.

Note on transition_velocity

transition_velocity represents the rate at which the system moves toward the competing basin.

The variable is included in the dataset because it can help models reason about escalation speed.

The reference scorer does not yet evaluate this field directly.

Future versions may introduce velocity-aware diagnostics.

Production deployment

This dataset class functions best as a transition-aware monitoring layer rather than a standalone classifier.

Typical deployments include:

• —ventilator performance deterioration monitoring
• —ICU escalation support
• —digital twin modeling of ventilatory support failure
• —ventilator setting optimization review
• —AI model auditing for competing failure-mode recognition

The value lies in representing where the patient sits between competing basins.

Enterprise and research collaboration

This dataset class is suitable for collaboration with:

• —respiratory analytics teams
• —critical care research groups
• —ventilator strategy teams
• —clinical AI safety researchers
• —digital twin developers
• —early-warning and escalation platforms

The framework provides explicit representation of:

• —which regime a patient is leaving
• —which regime is emerging
• —how uncertain the transition is
• —whether stabilization remains structurally feasible

License

MIT