benthos

Installation

pip install benthos

Requires Python 3.10+. Dependencies: NumPy, SciPy, Pandas.

Quick Start

import benthos

# Load a dataset
data = benthos.datasets.load("mona")

# Fit Weibull model
result = benthos.weibull.fit(data["dwell_time"])
print(f"Commitment Shape (k): {result.k:.3f}")
print(f"Regime: {result.regime}")
print(f"Fit Quality (R²): {result.r_squared:.3f}")

Data Schema

Every Benthos dataset follows the dwell-time schema. The minimum required columns are id, dwell_time, and censored.

# Required columns for the dwell-time schema:
#   id           — unique identifier for the commitment
#   dwell_time   — time active (numeric, positive)
#   censored     — 1 if unresolved at end of observation, 0 otherwise
#
# Optional:
#   initial_status  — status at observation start
#   group_id        — for grouped/nested commitment structures

import pandas as pd
import benthos

df = pd.DataFrame({
    "id": ["c001", "c002", "c003"],
    "dwell_time": [2.3, 5.1, 0.8],
    "censored": [0, 1, 0],
})

result = benthos.weibull.fit(df["dwell_time"], censored=df["censored"])

Commitment Shape (k)

The Weibull shape parameter k describes how predictable the timing of commitment resolution is. Values below 1.0 indicate heavy-tailed waiting times (Composting regime); values near 1.0 indicate memoryless dynamics (Steady State); values above 1.0 indicate increasing hazard as commitments age (Building or Crystallizing).

See Commitment Shape Regimes for the full regime classification.

The Verification Paradox

Observing a commitment changes its dynamics. The Watch Rate (γ_obs) controls how frequently commitments are checked. Higher Watch Rate compresses the apparent dwell-time distribution, making networks look worse (more violations detected) while making them work better (violations resolved faster). This is the Verification Paradox, first demonstrated in Paper 1 using the MONA dataset.

Lindblad Parameters

The GKSL (Lindblad) master equation governs commitment evolution through four channels: observation, decay, pressure, and noise. The benthos.lindblad module extracts all four parameters from survival data. See The Four Channels for details.

Regime Classification

import benthos

# Classify a single k value
regime = benthos.classify.regime(k=0.667)
print(regime.name)           # "Composting"
print(regime.description)    # "Amorphous, spreading..."

# Full Lindblad parameter extraction
params = benthos.lindblad.fit(data["dwell_time"])
print(f"Watch Rate (γ_obs):  {params.gamma_obs:.3f}")
print(f"Drift Rate (γ_dec):  {params.gamma_dec:.3f}")
print(f"Pressure Rate (γ_prs): {params.gamma_prs:.3f}")

Reproducing Paper 1 (MONA analysis)

The full MONA analysis from The Verification Paradox can be reproduced with the benthos package and the MONA dataset from the data catalog. See the GitHub repository (opens in new tab) for the reproduction notebook.

Bring Your Own Dataset

Any dataset with a dwell-time column (time from commitment start to resolution) and a censored indicator can be analyzed with benthos. See the Data Schema section for the required format.