# Catalytic Triad Plugin Reference

For a step-by-step workflow, see
{doc}`../how_to/analysis_triad_quickstart`.

## Configuration Reference

Top-level plugin key in `comparison.yaml`:

```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:

```text
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

```python
{
    "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

```python
{
    "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:

```bash
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