Understanding Outputs

Understanding Outputs

FleXgeo2 writes one folder per run, organised with one subfolder per analysis. Folders for optional analyses are only created when that analysis runs.

Every output folder explains itself: start with its README.md, which lists what ran, the key results, and a description of every file and column written in that run.

Layout

results/
├── README.md                    # start here: what ran, key results, guide to every file
├── run.json                     # parameters, package versions, input checksums
├── overview.png                 # per-residue results along the sequence
├── geometry/
│   ├── descriptors.csv          # per model and residue: curvature, torsion, ...
│   ├── residues.csv             # per residue: mean, SD, range and dmax
│   └── models.csv               # per model: deviation from the ensemble mean
├── reference/                   # with --reference-model or --reference-pdb
│   ├── distances.csv            # per model and residue: distance to the reference
│   ├── residues.csv             # per residue: distance statistics
│   └── heatmap.png
├── clusters/                    # with --cluster-residues
│   ├── assignments.csv          # per model and residue: cluster label, probability
│   ├── residues.csv             # per residue: number of clusters, noise fraction
│   └── clusters.png             # cluster of every model at every residue
└── range_clusters/              # with --cluster-residue-range
    ├── assignments.csv          # per model and range: cluster label, PCA coordinates
    ├── ranges.csv               # per range: number of clusters, noise fraction
    └── <chain>_<start-end>.png

Some files are written only when they apply:

• geometry/models_by_chain.csv: the per-model summary computed separately for each chain, when the input has more than one chain
• reference/matrices/<chain>.csv: distances to the reference as a models x residues matrix, one file per chain, with --distance-matrices
• residue_plots/<chain>_<residue number>_<name>.png: curvature vs torsion of each residue chosen with --plot-residues
• overview_<chain>.png, reference/heatmap_<chain>.png and clusters/clusters_<chain>.png: with more than 4 chains, these figures are written one per chain instead of one for all chains, which would be too tall to read

In file names, <chain> is the chain ID. When two chain IDs differ only by case (e.g. A and a in a large assembly), the one that is not upper case gets a _lower suffix (overview_a_lower.png, reference/matrices/a_lower.csv), because macOS and Windows treat overview_A.png and overview_a.png as the same file.

README.md and run.json

README.md is written for people: the input, the analyses and their settings, the most flexible residues, the residues furthest from the reference, which residues split into clusters, the range clustering results, and a guide to the files.

run.json is written for reproducibility: the FleXgeo2 version, the time of the run, the input and reference files with their SHA-256 checksums, every parameter, the Python, platform and package versions, and the list of files written.

Tables

All tables are in long ("tidy") format with a chain column, so a single chain can be selected by filtering that column. Tables with one row per model and residue start with the same columns, chain, model, order, name, residue_label, so they can be joined on them.

• model is the PDB MODEL number of the conformation.
• order is the residue number from the PDB file (author numbering).
• residue_label is the residue name and number, e.g. ALA45.

geometry/descriptors.csv holds the Melodia descriptors for every model and residue: curvature and torsion of the C-alpha spline (1/Å), arc_length (Å), writhing, and the phi and psi backbone dihedrals (degrees).

geometry/residues.csv summarises each residue over the ensemble: mean, standard deviation, minimum and maximum of curvature and torsion, the number of models, and dmax.

geometry/models.csv summarises each model: its mean curvature and torsion and its mean absolute deviation from the ensemble mean, which flags conformations that differ from the rest.

reference/distances.csv gives, for every model and residue, the curvature and torsion of the model and of the reference, and the Euclidean distance between them. reference/residues.csv summarises those distances per residue. See Reference-State Comparison.

clusters/assignments.csv gives the HDBSCAN cluster of every model at every residue (-1 is noise) and its membership probability. clusters/residues.csv gives, per residue, the number of clusters and the fraction of models labelled as noise.

range_clusters/assignments.csv gives the cluster of every model for each residue range, with the PCA coordinates used for plotting. range_clusters/ranges.csv summarises each range. See Clustering Conformations.

Plots

Figures are PNG by default; with --plot-format pdf or --plot-format svg every figure is written in that format instead (e.g. overview.pdf), and the output folder's README.md uses the same names.

overview.png shows every per-residue result along the sequence, one panel each: curvature and torsion (ensemble mean +/- standard deviation, with individual model traces), dmax, and, when those analyses ran, the number of clusters per residue and the mean distance to the reference. Panels share the residue axis, so a residue can be read across all of them.

reference/heatmap.png shows the distance to the reference for every residue (x) and model (y), laid out like clusters/clusters.png and aligned with overview.png by residue. Bright rows mark models that differ from the reference at many residues; bright columns mark residues that differ in many models. The colour scale starts at 0 and ends at the 99th percentile of each chain's distances, so a few very large distances do not turn the rest of the map black; larger distances share the top colour, marked by the arrow on the colour bar. The exact values are in reference/distances.csv.

clusters/clusters.png shows the cluster of every model (rows) at every residue (columns), with the number of clusters per residue above. Light grey is noise. Labels are assigned independently at each residue, so cluster 0 at one residue is unrelated to cluster 0 at another.

Clusters 0-17 have their own colour, the same in every figure. Residues with more clusters than that are rare; clusters 18 and above share dark grey and one "Other clusters (18+)" legend entry. Their exact labels are in clusters/assignments.csv.

residue_plots/<chain>_<residue number>_<name>.png shows one chosen residue in (curvature, torsion) space, one point per model: coloured by cluster when per-residue clustering ran, with the reference marked by a star when one was given, and the residue's dmax in the title. File names start with the zero-padded residue number, so they sort in sequence order.

range_clusters/<chain>_<start-end>.png shows the models of one residue range on the first two principal components of the range's geometry, coloured by cluster.

Rerunning into the same folder

FleXgeo2 does not write into an output folder that already contains files, so the results of different runs never mix. To replace an earlier run, add --overwrite (OutputConfig(overwrite=True) in Python): the files of the earlier run are removed first, and any other files in the folder are kept.

Upgrading from the April 2026 preview

The April 2026 preview (tagged v2.0.0, since withdrawn) wrote a different layout (e.g. geometry_descriptors.csv, plots/ensemble_overview.png, chains/<chain>/...) and had an --output-verbose option. The changelog maps every old file to its new location.