Catalytic Triad Plugin Reference

For a step-by-step workflow, see Catalytic Triad Analysis: Quick Start.

Configuration Reference

Top-level plugin key in comparison.yaml:

plugins:
  catalytic_triad:
    name: "LipA_catalytic_triad"
    description: "Ser-His-Asp catalytic triad"
    threshold: 3.5
    pairs:
      - label: "Asp133-His156"
        selection_a: "midpoint(protein and resid 133 and name OD1 OD2)"
        selection_b: "protein and resid 156 and name ND1"
      - label: "His156-Ser77"
        selection_a: "protein and resid 156 and name NE2"
        selection_b: "protein and resid 77 and name OG"

`CatalyticTriadSettings` fields

Field	Type	Default	Description
`name`	`str`	required	Triad identifier saved in output files
`description`	`str`	`""`	Human-readable triad description
`threshold`	`float`	`3.5`	Contact cutoff in angstroms for each pair
`pairs`	`list[TriadPair]`	required	Pair definitions used to compute distances and contacts

`TriadPair` fields

Field	Type	Default	Description
`label`	`str`	required	Pair label used in tables and JSON
`selection_a`	`str`	required	First MDAnalysis selection
`selection_b`	`str`	required	Second MDAnalysis selection

Selection syntax

Syntax	Description	Example
Standard	MDAnalysis atom selection	`protein and resid 77 and name OG`
`midpoint()`	Geometric midpoint of selected atoms	`midpoint(protein and resid 133 and name OD1 OD2)`
`com()`	Center of mass of selected atoms	`com(protein and resid 133 and name OD1 OD2)`

Important

Use chain-aware selections. Residue IDs restart per chain in PolyzyMD systems, so bare resid X selections can match non-protein atoms. Prefer protein and resid X for catalytic residues.

Output Files

Triad outputs are written under each condition plus a comparison result:

comparison_workspace/
├── analysis/
│   └── <condition>/
│       └── catalytic_triad/
│           ├── run_1/
│           │   └── triad_LipA_catalytic_triad_eq100ns.json
│           ├── run_2/
│           │   └── triad_LipA_catalytic_triad_eq100ns.json
│           ├── run_3/
│           │   └── triad_LipA_catalytic_triad_eq100ns.json
│           └── aggregated/
│               └── triad_LipA_catalytic_triad_reps1-3_eq100ns.json
└── comparison/
    └── catalytic_triad/
        └── result.json

Per-replicate JSON structure

{
    "analysis_type": "catalytic_triad",
    "triad_name": "LipA_catalytic_triad",
    "triad_description": "Ser-His-Asp catalytic triad...",
    "threshold": 3.5,
    "simultaneous_contact_fraction": 0.741,
    "n_frames_simultaneous": 1482,
    "sim_contact_sem": 0.082,
    "sim_contact_correlation_time": 8542.5,
    "sim_contact_n_independent": 12,
    "pair_results": [
        {
            "pair_label": "Asp133-His156",
            "mean_distance": 2.91,
            "std_distance": 0.45,
            "fraction_below_threshold": 0.932
        },
        {
            "pair_label": "His156-Ser77",
            "mean_distance": 4.07,
            "std_distance": 1.10,
            "fraction_below_threshold": 0.551
        }
    ],
    "n_frames_used": 2000,
    "n_frames_total": 3000
}

Aggregated JSON structure

{
    "analysis_type": "catalytic_triad_aggregated",
    "n_replicates": 3,
    "replicates": [1, 2, 3],
    "overall_simultaneous_contact": 0.499,
    "sem_simultaneous_contact": 0.273,
    "per_replicate_simultaneous": [0.741, 0.512, 0.245],
    "pair_results": [
        {
            "pair_label": "Asp133-His156",
            "overall_mean": 3.09,
            "overall_sem": 0.21,
            "per_replicate_means": [2.91, 3.05, 3.31]
        },
        {
            "pair_label": "His156-Ser77",
            "overall_mean": 4.03,
            "overall_sem": 1.07,
            "per_replicate_means": [3.12, 4.00, 4.97]
        }
    ]
}

Plot Types

Catalytic triad plots are generated by polyzymd compare plot-all.

Plot output	Description
`simultaneous_contact_comparison.png`	Condition-level comparison of simultaneous contact (%)
`triad_pair_distances_<condition>.png`	Per-pair mean distances and uncertainty for one condition
`triad_pair_contacts_<condition>.png`	Per-pair fraction below threshold for one condition
`triad_pair_kde_<condition>.png`	KDE of pair distance distributions for one condition
`triad_2d_kde_<condition>.png`	2D KDE for two pair distances to inspect coupled geometry
`triad_summary_<condition>.png`	Combined summary panel for one condition

Use top-level plot_settings in comparison.yaml to tune sizes, styles, and output resolution for triad plots.

Common CLI Options

Option	Default	Description
`-f, --file`	`comparison.yaml`	Path to comparison config
`--eq-time`	from YAML defaults	Equilibration time to skip
`--recompute`	off	Ignore cached results and recompute
`--format`	`table`	Output format: `table` or `json`
`-q, --quiet`	off	Suppress INFO logging
`--debug`	off	Enable DEBUG logging

Use either plugin name:

polyzymd compare run triad -f comparison.yaml --eq-time 100ns
polyzymd compare run catalytic_triad -f comparison.yaml --eq-time 100ns

Troubleshooting

“No catalytic_triad section found”

Cause: plugins.catalytic_triad is missing from comparison.yaml

Fix: Add a complete catalytic_triad block with name, threshold, and at least one pair in pairs

“Selection … returned 0 atoms”

Cause: Residue ID or atom name does not match the loaded topology

Fix:

Verify residue numbering in the topology used for analysis
Verify atom names (OD1/OD2, ND1/NE2, OG)
Use chain-aware selections like protein and resid ...

Very high distances (> 10 Å)

Cause: Usually incorrect selections or mismatched residue numbering

Fix: Validate selections in VMD or PyMOL and confirm the exact residues

Very low simultaneous contact (< 10%)

Cause: Could be a genuine disrupted triad or a too-strict threshold

Fix:

Inspect pair-level fractions to identify the limiting pair
Re-check selections
If scientifically justified, test a slightly larger threshold (for example 4.0 Å)

“Low statistical reliability” warning

Cause: Long autocorrelation time relative to trajectory length

Fix: Informational warning only. Prefer more replicates and/or longer simulations for tighter uncertainty

“Skipping replicate N: trajectory data not found”

Cause: Replicate output is missing or path mapping is incorrect

Fix: Analysis continues with available data. Verify simulation completion and project paths if this is unexpected