Command Line Guide

Command Line Guide

The flexgeo2 command computes Melodia differential-geometry descriptors from a PDB file, writes CSV tables and plots, and prints a short summary of the results.

flexgeo2 path/to/structure.pdb [options]

Basic input and output

flexgeo2 path/to/structure.pdb

Options:

• pdb_file: input PDB file
• --output-dir PATH: directory for CSV and plot outputs, default results
• --overwrite: replace the outputs of an earlier run in --output-dir
• --distance-matrices: also write the distances to the reference as one models x residues matrix per chain (needs a reference)

Examples:

flexgeo2 path/to/structure.pdb --output-dir results
flexgeo2 path/to/structure.pdb --output-dir results --overwrite

FleXgeo2 refuses to write into an output folder that already contains files, so the results of different runs never mix. --overwrite removes the files of the earlier run first and keeps any other files in the folder.

See Understanding Outputs for what each file contains.

What the command prints

After a run, flexgeo2 prints what it analysed, the headline result of each analysis, and where the results are:

FleXgeo2 analysed pdb2lj5.pdb: 301 models, 1 chain (A), 76 residues.

Most flexible residues (dmax): A LEU71 (2.308), A GLY75 (1.934), A GLY76 (1.934)
Furthest from input model 1 (mean distance): A LEU71 (1.634), A LEU67 (1.116), A GLY10 (0.764)

Results: results/ (9 files); start with README.md

Mistakes in the input (a missing file, an unknown chain or model, a residue range that is not in the structure) are reported as a one-line flexgeo2: error: ... before Melodia runs, and the command exits with status 1.

Chain filtering and workers

Use --chain to keep specific chains. The option can be repeated.

flexgeo2 path/to/ensemble.pdb --chain A
flexgeo2 path/to/ensemble.pdb --chain A --chain B

Use --n-jobs to set the worker count passed to Melodia for multi-model files.

flexgeo2 path/to/ensemble.pdb --chain A --n-jobs 4

Plot controls

FleXgeo2 overlays individual model traces on the curvature and torsion panels of overview.png by default, up to the configured limit.

flexgeo2 path/to/ensemble.pdb --max-models-in-plot 20

Use --plot-format to choose the file format of every figure: png (default), pdf or svg. PDF and SVG are vector formats for publication; their text stays editable in Illustrator or Inkscape.

flexgeo2 path/to/ensemble.pdb --plot-format pdf

To hide individual model overlays and show only the ensemble mean and standard deviation band:

flexgeo2 path/to/ensemble.pdb --hide-model-traces

Plotting chosen residues

Use --plot-residues to plot curvature against torsion for chosen residues, one point per model. Each residue gets its own PNG in residue_plots/. Points are coloured by cluster when --cluster-residues is also given, the reference is marked with a star when a reference is given, and the title shows the residue's dmax.

flexgeo2 path/to/ensemble.pdb --plot-residues 45
flexgeo2 path/to/ensemble.pdb --cluster-residues --plot-residues 45,A:50-52

A selection is a residue number (45) or range (45-50), optionally with a chain (A:45, A:45-50). Separate several with commas or repeat the option. Without a chain, a selection applies to every analysed chain that has the residue. Residues that are not in the structure are reported before Melodia runs.

dmax tuning

dmax is computed from outlier-trimmed curvature and torsion extrema. The default trimming threshold is 0.01, meaning sparse extreme bins with less than 1% of a residue's observations are ignored.

flexgeo2 path/to/ensemble.pdb --dmax-outlier-fraction 0.02

The value must be greater than or equal to 0 and less than 1.

Reference-state comparison

Use --reference-model to compare every model in the input ensemble to one model from the same input PDB. Models are identified by their PDB MODEL number.

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

Use --reference-pdb to compare against a state from another PDB file.

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

--reference-model and --reference-pdb are mutually exclusive. --reference-pdb-model requires --reference-pdb; if it is omitted, FleXgeo2 uses the first model in the reference PDB.

Per-residue clustering

Use HDBSCAN to cluster conformations independently for each residue in (curvature, torsion) space.

flexgeo2 path/to/ensemble.pdb --cluster-residues

Tune HDBSCAN with:

flexgeo2 path/to/ensemble.pdb \
  --cluster-residues \
  --cluster-min-size 8 \
  --cluster-min-samples 4

Residue-range clustering

Use one combined geometric signature across a residue window.

flexgeo2 path/to/ensemble.pdb --cluster-residue-range 45-54

Repeat the option to analyze multiple windows.

flexgeo2 path/to/ensemble.pdb \
  --chain A \
  --cluster-residue-range 45-54 \
  --cluster-residue-range 90-99

Option reference

Option	Purpose	Default
pdb_file	Input PDB file	Required
--output-dir	Directory for CSV and plot outputs	results
--overwrite	Replace an earlier run's outputs in --output-dir	False
--chain	Chain ID to keep; can be repeated	All chains
--n-jobs	Workers passed to Melodia	1
--max-models-in-plot	Maximum individual model traces in overview.png	12
--hide-model-traces	Hide individual model traces	False
--plot-format	Figure format: png, pdf or svg	png
--dmax-outlier-fraction	Sparse extreme-bin cutoff for dmax	0.01
--reference-model	Input model (PDB MODEL number) to use as reference state	None
--reference-pdb	External PDB to use as reference state	None
--reference-pdb-model	Model from external reference PDB	First model
--cluster-residues	Run per-residue HDBSCAN clustering	False
--cluster-min-size	HDBSCAN min_cluster_size: smallest cluster, in models	5% of the models, at least 5
--cluster-min-samples	HDBSCAN min_samples: larger values label more models as noise	5 (or --cluster-min-size if smaller)
--cluster-residue-range	Residue window for range clustering; can be repeated	None
--distance-matrices	Also write distance matrices (needs a reference)	False
--plot-residues	Plot curvature vs torsion for chosen residues; can be repeated	None

--output-verbose from the April 2026 preview was removed: per-model tables are now written by default, distance matrices need --distance-matrices, and per-residue cluster plots are replaced by clusters/clusters.png (all residues) and --plot-residues (chosen residues). See the changelog.