Hydrogen Bonds Plugin Reference

For task-oriented setup examples, see How-To: Analyze Hydrogen Bonds Across Conditions.

Settings

Top-level plugin key and CLI name: hydrogen_bonds.

Field	Type	Default	Description
groups	dict[str, str]	{protein: "chainid A", polymer: "chainid C"}	Named MDAnalysis selections used by summaries
summaries	list or mapping	protein_polymer between protein and polymer	Named H-bond summaries to compute
distance_cutoff	float	3.0	Donor-acceptor cutoff in Å
angle_cutoff	float	150.0	D-H…A angle cutoff in degrees
update_selections	bool	true	Re-evaluate selections on each frame
top_n_pairs	int	15	Top residue pairs shown in output and plots
allow_empty_groups	bool	true	Warn and skip summaries with empty groups instead of raising
allow_overlapping_composition	bool	false	Permit overlapping composition partitions
composition	mapping or null	null	Optional donor/acceptor partition analysis
timestep_ps	float | null	null	Optional uniform frame spacing for time-axis plots

Each summary defines exactly one of between: [group_a, group_b] or within: group_name. Mapping-form summaries use the mapping key as the summary name.

Hydrogen detection uses MDAnalysis HydrogenBondAnalysis with hydrogens selected as (<group union>) and element H; topologies need explicit hydrogens and reliable element metadata.

Comparison mode

hydrogen_bonds overrides result loading to validate settings-sensitive cache files, then uses the framework’s default-style scalar comparison. It extracts one MetricValue per configured summary named mean_hbonds_<summary> and runs FDR-corrected pairwise tests and ANOVA per summary. higher_is_better is unset because more or fewer H-bonds can be desirable depending on the system.

Output files

Per-replicate cache files are named hbonds_eq*.json under analysis/<condition>/hydrogen_bonds/run_<replicate>/. Aggregated results are written under analysis/<condition>/hydrogen_bonds/aggregated/, and cross-condition statistics are written to comparison/hydrogen_bonds/result.json.

Plot outputs

Plot output	Description
hbond_summary_comparison.png	Faceted mean H-bonds/frame bars for each summary
hbond_timeseries_<summary>.png	Mean H-bonds/frame over time for one summary
hbond_top_pairs_<summary>.png	Highest-occupancy residue-pair bars for one summary
hbond_composition_absolute.png	Stacked composition by donor/acceptor partition, when composition is enabled
hbond_composition_fraction.png	Fractional composition by donor/acceptor partition, when composition is enabled

Time-axis plots assume uniformly saved frames. PolyzyMD maps frame index to time as frame_index * timestep_ps; variable-timestep concatenated trajectories are not supported.