Skip to content

Add finite-replica confidence floor and within-source block reference for multi-replica edge confidence - #112

Merged
NDoering99 merged 9 commits into
wolberlab:masterfrom
MarvinTaterra:master
Jul 27, 2026
Merged

Add finite-replica confidence floor and within-source block reference for multi-replica edge confidence#112
NDoering99 merged 9 commits into
wolberlab:masterfrom
MarvinTaterra:master

Conversation

@MarvinTaterra

Copy link
Copy Markdown
Collaborator

Summary

MDPath already reports a per-edge multi-replica confidence (-confidence). Two things
were missing to make that number interpretable:

  1. It has a hard floor that depends on how many replicas you ran. With R
    non-negative replica values the coefficient of variation is bounded, so
    confidence = 1/(1+CV) cannot fall below c_min = 1/(1+CV_max). Without that bound
    a "0.6" from 3 replicas and a "0.6" from 20 replicas look the same but aren't.
  2. There was no baseline. A high confidence may simply be what finite sampling
    produces on its own, with no genuine replica-to-replica agreement behind it.

This PR adds both, plus the visualization and tests to go with them. Everything is
opt-in: without the new flags, behaviour is identical to current master.

What's new

Finite-replica floor (mdpath/src/confidence.py)
edge_confidence.csv gains c_min (the attainable lower bound), c_norm (the score
rescaled from [c_min, 1] onto [0, 1]) and ddof.

Within-source block reference (mdpath/src/null_model.py, new)
Each source trajectory is cut into contiguous, non-overlapping blocks of length L;
random groups of R blocks are resampled to estimate how reproducible an edge looks
from within-trajectory sampling alone. Observed replicas are subsampled to the same
(L, R) so the comparison is matched. The headline output is

rho = cv_obs / cv_null

i.e. does the between-replica dispersion exceed the within-source reference?

Null-aware visualization (mdpath/src/path_confidence_viz.py)
The existing ChimeraX viewer's hover gains the reference metrics; colouring, tube
widths, spline geometry and structure embedding are unchanged. An opt-in second viewer
(-experimental-c-corr) colours by the experimental corrected score.

Terminology (deliberate)

  • confidence / c_norm are dispersion-based stability scores, not probabilities,
    significance levels, or effect sizes. An edge with consistently negligible MI can
    score highly.
  • The block analysis is a within-source sampling-stability reference, not an
    external "no-coupling" null — the blocks are real trajectory windows and still contain
    genuine dynamics. It is named as such throughout.
  • c_corr_experimental (quadrature CV subtraction) is an unvalidated heuristic. It is
    opt-in, labelled experimental in the CLI/metadata/legend, and finite only when
    corr_status == "above_reference"; undefined and at-or-below-reference edges stay NaN
    so they are never rendered as perfect confidence. rho is the recommended output.

New CLI flags

Flag Default Meaning
-null {none,block} none Run the block reference (implies -confidence).
-null-block-sweep 25,50,100,250 Block lengths (ns); infeasible ones dropped with a warning.
-null-block-ns 100 Primary block length for the per-edge table.
-null-sources all Which replicas supply reference blocks.
-null-draws 100 Resampling draws.
-null-seed 0 Seed.
-ddof {0,1} 0 Delta-DoF for std/CV and the floor.
-null-outdir null_analysis Output directory.
-experimental-c-corr off Opt-in experimental c_corr viewer.
mdpath -top system.pdb -traj rep1.dcd rep2.dcd rep3.dcd rep4.dcd \
       -confidence -null block -null-block-sweep 25,50,100,250 -null-block-ns 100

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants