ClarusC64/clinical-five-node-shock-cascade-boundary-v0.5

What this repo does

This repository provides a Clarus v0.5 cascade recovery geometry dataset modeling shock cascade transition with a five-node clinical structure.

Earlier Clarus datasets focused on state detection and boundary discovery.

Version v0.5 adds a recovery geometry layer that asks a stricter question:

Can the system still return to stability?

The task is binary classification over shock-linked deterioration states using:

• a five-node clinical cascade • trajectory dynamics • boundary discovery signals • recovery geometry variables

Models must determine whether the shock cascade remains recoverable or has crossed into irreversible deterioration.

Core five-node cascade

The core five-node structure for this dataset is:

• hemodynamicpressure • physiologicalbuffer • interventiondelay • organcoupling • perfusion_instability

Operational interpretation:

hemodynamic_pressure Represents circulatory burden such as hypotensive stress, vasoplegia, preload loss, or escalating shock pressure.

physiological_buffer Represents physiological reserve available to absorb hemodynamic insult.

intervention_delay Captures delay before fluids, vasopressors, transfusion, source control, or other stabilizing interventions.

organ_coupling Represents propagation of dysfunction across interacting organ systems.

perfusion_instability Represents tissue hypoperfusion, microcirculatory failure, and worsening shock propagation.

Terminology note

Earlier Clarus variants may use related circulatory naming such as perfusion_pressure.

In v0.5 this node is expressed as perfusion_instability.

The rename shifts emphasis from raw pressure level toward broader instability of perfusion dynamics while preserving the same normalized 0 to 1 scale.

Trajectory layer

The dataset includes a trajectory signal:

drift_gradient

Range:

−1 to +1

Interpretation:

negative values indicate motion toward recovery positive values indicate motion toward deterioration

This lets the model infer directional movement rather than assess a static snapshot alone.

Dynamic forecasting layer

Three dynamic variables describe system motion:

• driftvelocity • driftacceleration • boundary_distance

These variables allow models to reason about how quickly the system is moving and how near it lies to the cascade boundary.

Boundary discovery layer

The dataset retains the boundary discovery layer introduced in v0.4.

Variables:

• perturbationradius • collapsetrigger

Interpretation:

perturbation_radius Measures how much disturbance the system can absorb before crossing into collapse.

collapse_trigger Binary indicator that the instability boundary has been crossed.

Recovery geometry layer

v0.5 introduces a recovery geometry layer that determines whether recovery remains possible.

Variables:

• recoverydistance • recoverygradient • return_feasibility

These variables transform the task from collapse detection into recovery reasoning.

Models must determine not only whether a system is unstable, but whether a path back to stability still exists.

Recovery variable definitions

recovery_distance

Distance from the current system state to the nearest stable basin.

Definition:

recovery_distance = min ||x - x_stable||

Range:

0 to 1

Interpretation:

small values indicate proximity to a recoverable region large values indicate deep cascade penetration

recovery_gradient

Direction of motion relative to the nearest recovery basin.

Range:

−1 to +1

Interpretation:

negative values indicate motion toward recovery positive values indicate motion deeper into collapse

return_feasibility

Binary indicator representing whether recovery remains possible.

Values:

0 system has crossed an irreversible cascade boundary

1 system still lies within a recoverable region

Prediction target

Target column:

label_shock_cascade

A positive label indicates irreversible shock cascade transition.

Collapse threshold

The cascade boundary threshold used for labeling is:

collapse_threshold = 0.05

Label logic

Positive labels trigger when either condition holds:

boundary_distance < 0.05

or

return_feasibility = 0

This encodes irreversible cascade detection.

Binary simplification note

The underlying system dynamics are continuous and multi-dimensional.

For benchmark clarity, the dataset compresses this structure into a binary classification task:

recoverable state versus irreversible deterioration

The recovery geometry variables preserve the deeper system structure.

Row structure

Each dataset row contains:

scenario_id

hemodynamicpressure physiologicalbuffer interventiondelay organcoupling perfusion_instability

driftgradient driftvelocity driftacceleration boundarydistance

perturbationradius collapsetrigger

recoverydistance recoverygradient return_feasibility

labelshockcascade

Variable ranges

State variables

0 to 1

drift_gradient

−1 to +1

drift_velocity

0 to 1

drift_acceleration

−1 to +1

boundary_distance

0 to 1

perturbation_radius

0 to 1

collapse_trigger

0 or 1

recovery_distance

0 to 1

recovery_gradient

−1 to +1

return_feasibility

0 or 1

Files

data/train.csv Labeled training examples.

data/tester.csv Unlabeled test scenarios.

scorer.py Evaluation script for binary classification.

cli.py Optional command-line wrapper for running the scorer.

README.md Dataset documentation.

Evaluation

The scorer reports the following metrics:

accuracy precision recallirreversibledetection falserecoveryrate f1 confusion_matrix

Primary metric

recallirreversibledetection

This metric prioritizes detection of irreversible deterioration.

Secondary diagnostic metric

falserecoveryrate

This measures how often irreversible states are incorrectly treated as recoverable.

Version progression

Clarus datasets evolve through successive capability layers.

v0.1 Cascade state detection datasets

v0.2 Cascade + trajectory datasets

v0.3 Cascade + trajectory + dynamic forecasting datasets

v0.4 Cascade + trajectory + dynamics + boundary discovery datasets

v0.5 Cascade + trajectory + dynamics + boundary discovery + recovery geometry datasets

Earlier versions remain unchanged to preserve benchmark continuity.

License

MIT

Structural Note

Clarus v0.5 marks the transition from instability mapping to recovery geometry.

Earlier datasets asked whether systems were approaching collapse.

v0.5 asks a more operational question:

Is recovery still structurally possible?

This makes the dataset class closer to real-world decision support systems.

Production Deployment

Recovery geometry datasets are suitable for applications where distinguishing recoverable shock states from irreversible cascade is critical.

Possible domains include:

shock escalation monitoring critical care surveillance perfusion rescue pathway modeling intervention timing simulation

Enterprise & Research Collaboration

For dataset expansion, custom coherence scorers, or deployment architecture:

team@clarusinvariant.com

Instability is detectable. Governance determines whether it propagates.