ClarusC64/clinical-quad-surgical-stress-buffer-lag-coupling-postop-collapse-v0.8

What this repo does

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

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

• —inflammatory postoperative stress
• —hemodynamic collapse
• —septic deterioration
• —multiorgan instability

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:

• —surgical_stress
• —physiologic_buffer
• —recovery_lag
• —system_coupling

Operational definitions:

surgical_stress

Acute operative burden and inflammatory load imposed by surgery and its complications.

physiologic_buffer

Remaining adaptive reserve available to tolerate blood loss, inflammation, infection, and metabolic demand.

recovery_lag

Delay in returning toward expected postoperative stabilization.

system_coupling

Degree to which deterioration in one postoperative subsystem is propagating into broader multisystem instability.

Clinical variable mapping

These mappings are illustrative rather than prescriptive.

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

Why the second boundary matters

Most instability detectors estimate only one quantity:

distance to the nearest collapse boundary.

This is insufficient for real postoperative deterioration.

A patient may appear to be deepening within one recovery complication 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 postoperative transition 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 postoperative state into another more dangerous basin.

Prediction target

The prediction target is:

• —label_postop_collapse

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

surgicalstress physiologicbuffer recoverylag 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

deltasurgicalstress deltaphysiologicbuffer deltarecoverylag deltasystemcoupling

Outcome fields

trajectoryshift minimalinterventionpath stabilizationsuccess labelpostopcollapse in train only

tester.csv excludes:

stabilizationsuccess labelpostop_collapse

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:

• —surgical ward deterioration monitoring
• —enhanced recovery pathway oversight
• —ICU escalation support
• —digital twin modeling of postoperative instability
• —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:

• —perioperative analytics teams
• —surgical outcomes research groups
• —critical care 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