tool for generating assemblies.yaml

[tdudgeon]

Create a tool that can generate the assemblies.yaml file. Some information might still need to be provided by the user, but the process can at least be simplified.

[tdudgeon]

An initial tool has been created (see src/xchemalign/generate_assemblies.py on the auto_assemblies branch.

[tdudgeon]

generate_assemblies.py — Summary

Purpose

Produces a draft assemblies.yaml by inspecting crystallographic PDB files directly, so users
don't have to write the file by hand. The output is always a first draft requiring human review
before running the collator.

---

CLI Options

Option	Default	Description
-d / --dir	.	Working directory containing config.yaml
--chains-per-assembly N	1	How many protein chains form one biological assembly (monomer=1, dimer=2, etc.)
--assembly-name NAME	derived	Override the auto-generated name (monomer, dimer, …)
--scan	off	Enable scan mode (see below)
--length-tolerance Å	5.0	Cell length tolerance for clustering (scan mode only)
--angle-tolerance °	2.0	Cell angle tolerance for clustering (scan mode only)
-o / --output FILE	upload-current/assemblies.yaml	Custom output path
--dry-run	off	Print YAML to stdout, write nothing
--force	off	Overwrite an existing assemblies.yaml
--log-level	0	0=INFO, 1=WARN, 2=ERROR

---

Two Operating Modes

Mode 1: ref_datasets (default)

Reads the ref_datasets list from config.yaml. Each named entry becomes one crystalform.
The PDB is located by searching input directories. Crystal form naming: uses the space group
string (e.g. P43212) when all refs have unique space groups; falls back to the dataset name
as the crystalform key when multiple refs share a space group.

Mode 2: --scan

Reads only the CRYST1 line from every PDB in all input directories (fast — no full structure
parse), then clusters by space group + unit cell similarity using greedy nearest-neighbour
matching within the specified tolerances. Crystal form names use the space group string when
unique, or P43212_1, P43212_2, etc. when a space group appears in multiple clusters.

---

Current Representative Selection Strategy

In ref_datasets mode there is no selection — the user has already nominated the
representatives.

In scan mode the representative is whichever structure ends up as the seed or the upgraded
seed during greedy clustering, using this priority (applied one structure at a time as entries
are encountered in filesystem order):

1. In ref_datasets — if the incoming structure's dataset name is in ref_datasets, it
   takes over as representative unless the current rep is also in ref_datasets.
2. manual input over model_building — a manual-input structure displaces a
   model-building one if neither is a preferred name.
3. First encountered — whichever structure seeds the cluster (alphabetical within each
   input directory, directories in config order).

---

Possible Alternative Strategies for Reference Selection

Ordered roughly from simplest to most involved:

1. Highest resolution

Parse the REMARK 2 RESOLUTION line from each PDB. Best resolution is the most common
criterion used by depositors in PDB. Cheap to extract (single-line read, no gemmi needed).

2. Lowest R-free

Parse REMARK 3 FREE R VALUE : from the PDB header. R-free is the most informative single
quality indicator. Slightly more complex to parse reliably (line format varies), but still
header-only.

3. Closest to cluster centroid

Within scan mode, prefer the structure whose unit cell parameters are closest to the mean of
all members. More robust than first-encountered when input directories are added in arbitrary
order.

4. Most complete / fewest missing residues

Count residues listed in REMARK 465 MISSING RESIDUES or compare sequence length to polymer
length. A complete structure is a better alignment reference.

5. Prefer apo (no ligand) structures

Check HETATM records or entity names to identify ligand-free structures. An unliganded
reference avoids any ligand-induced conformational bias in the alignment origin.

6. Prefer deposited PDB structures

Structures with a 4-character PDB accession code (e.g. 6LD2) have passed external curation
and are often higher quality than in-house refinements.

---

Recommendation

The most practical improvement with the least implementation cost is resolution — it is a
single-line read, universally present in well-refined PDB files, and is the criterion most
crystallographers would apply by hand.

[tdudgeon]

The other aspect to clear up is how to manage which PDB files are analysed. Currently all files in the model_building dir are read, but I have a local copy that only has the files needed by XCA. If run at Diamond a large number of irrelevant files might also be read. To address this we have these options:

1: read which structures to process from soakDB in the same way that collator does

2: run this on the data generated by collator, which would mean that only the relevant files are read. This will require a small change to the validation of the assemblies.yaml as this is currently done by collator, even though the file is not needed until aligner is run. This would mean that collator only needs config.yaml, aligner needs that plus assemblies.yaml. This probably quite a small change, and so probably the better approach.