Reference State Comparison

Reference-State Comparison

FleXgeo2 can compare every model in an ensemble to a reference state. The distance is the Euclidean distance between each model and the reference in each residue's (curvature, torsion) space.

Large distances mark residues whose local backbone geometry differs strongly from the selected reference.

Reference model from the input ensemble

Use --reference-model when the reference state is already present in the input PDB. Models are identified by their PDB MODEL number.

flexgeo2 path/to/ensemble.pdb --reference-model 1

Python equivalent:

from flexgeo2 import AnalysisConfig, FlexGeo2App, ReferenceConfig

result = FlexGeo2App().run(
    AnalysisConfig(
        pdb_file="path/to/ensemble.pdb",
        reference=ReferenceConfig(model_id="1"),
    )
)

External reference PDB

Use --reference-pdb when the reference state is stored in another PDB file.

flexgeo2 path/to/ensemble.pdb \
  --reference-pdb path/to/reference_state.pdb \
  --reference-pdb-model 1

Python equivalent:

from flexgeo2 import AnalysisConfig, FlexGeo2App, ReferenceConfig

result = FlexGeo2App().run(
    AnalysisConfig(
        pdb_file="path/to/ensemble.pdb",
        reference=ReferenceConfig(
            pdb_file="path/to/reference_state.pdb",
            pdb_model_id="1",
        ),
    )
)

If pdb_model_id is omitted, FleXgeo2 uses the first model found in the reference PDB.

In-memory results

When reference comparison is enabled, result.distance_result contains:

• long_df: distance values for each model, chain, and residue
• summary_df: residue-level distance summaries
• reference_label: human-readable reference state label

Example:

distance_result = result.distance_result
assert distance_result is not None

distance_result.summary_df.sort_values(
    "distance_mean",
    ascending=False,
).head(10)

Output files

Reference comparison writes reference/:

• reference/distances.csv: for every model and residue, the curvature and torsion of the model and of the reference, and the distance between them
• reference/residues.csv: per residue, the mean, standard deviation, minimum and maximum distance
• reference/heatmap.png: the distance for every model and residue

With --distance-matrices (OutputConfig(distance_matrices=True) in Python), FleXgeo2 also writes reference/matrices/<chain>.csv: the distances as a models x residues matrix, one file per chain.

The mean distance per residue is also plotted in overview.png, aligned with curvature, torsion and dmax.

How to read the heatmap

The distance heatmap places residues on the x axis, in sequence order, and models on the y axis, first model at the top: the same layout as the cluster map, and the same residue axis as overview.png. Brighter cells show larger distance to the reference state in (curvature, torsion) space. A bright column marks a residue that differs from the reference in many models; a bright row marks a model that differs from the reference at many residues.

The colour scale runs from 0 to the 99th percentile of each chain's distances. Torsion can spike where curvature is near zero, and without the cap a handful of such cells would set the scale and leave the rest of the map black. Distances above the cap share the top colour; the arrow at the top of the colour bar shows that the scale is capped. Read exact values from reference/distances.csv.

For a runnable version of this workflow, see notebooks/03_reference_comparison.ipynb.