Canonicalisation¶

from pandora.canonicalisation import canonicalise_structure
from pandora.parsing import mmcif_to_structure
from pandora.schemas.canonicalisation import canonicalisationPolicy

structure, _, _ = mmcif_to_structure("datasets/dev/mmcif/104m.cif")

policy = canonicalisationPolicy(
    policy_id="p1", policy_name="Default", policy_version="1.0.0"
)
canonical, mappings, provenance = canonicalise_structure(structure, policy)

print(provenance.transforms)

from pandora.canonicalisation import canonicalise_structure
from pandora.parsing import mmcif_to_structure
from pandora.schemas.canonicalisation import (
    ChainIdRules,
    IdentifierRules,
    canonicalisationPolicy,
)


def chain_map(path: str, strategy: str) -> str:
    structure, _, _ = mmcif_to_structure(path)
    policy = canonicalisationPolicy(
        policy_id="p",
        policy_name="p",
        policy_version="1.0.0",
        identifier_rules=IdentifierRules(
            chain_id=ChainIdRules(strategy=strategy)
        ),
    )
    _, mappings, _ = canonicalise_structure(structure, policy)
    return ", ".join(
        f"{item.original_chain_id}->{item.canonical_chain_id}"
        for item in mappings.chain_id_mapping.items
    )


# 13dg lists its chains as A, E, B, F, ...; remap relabels them in order.
print("remap:", chain_map("datasets/dev/mmcif/13dg.cif", "remap"))
# 1a08: label chain C is author chain B, and ligands share author ids.
print(
    "use_auth_chain_id:",
    chain_map("datasets/dev/mmcif/1a08.cif", "use_auth_chain_id"),
)

from pandora.canonicalisation import canonicalise_structure
from pandora.parsing import mmcif_to_structure
from pandora.schemas.canonicalisation import (
    IdentifierRules,
    ResidueNumberingRules,
    canonicalisationPolicy,
)

# 10mv: chain A starts at SEQRES position 22 and has a gap in the middle.
structure, _, _ = mmcif_to_structure("datasets/dev/mmcif/10mv.cif")

for strategy in ["preserve", "use_auth_seq", "renumber"]:
    policy = canonicalisationPolicy(
        policy_id="p",
        policy_name="p",
        policy_version="1.0.0",
        identifier_rules=IdentifierRules(
            residue_numbering=ResidueNumberingRules(strategy=strategy)
        ),
    )
    canonical, mappings, _ = canonicalise_structure(structure, policy)
    seq_ids = sorted(
        {a.label_seq_id for a in canonical.atoms if a.label_asym_id == "A"}
    )
    print(f"{strategy}: first {seq_ids[:3]}, last {seq_ids[-1]}")

item = mappings.residue_number_mapping.items[0]
print(
    f"renumber mapping: chain {item.original_chain_id} "
    f"{item.original_seq_id} (auth {item.original_auth_seq_id}) "
    f"-> {item.canonical_seq_id}"
)

from pandora.canonicalisation import canonicalise_structure
from pandora.parsing import mmcif_to_structure
from pandora.schemas.canonicalisation import (
    AltlocRules,
    canonicalisationPolicy,
)

# 1b6w: residue 35 has two conformers, A and B, at occupancy 0.5 each.
structure, _, _ = mmcif_to_structure("datasets/dev/mmcif/1b6w.cif")

rules = [
    AltlocRules(strategy="preserve"),
    AltlocRules(
        strategy="select_best_occupancy", tie_breaker="lowest_b_factor"
    ),
    AltlocRules(strategy="select_user_defined", user_defined_altloc="B"),
]
for altloc_rules in rules:
    policy = canonicalisationPolicy(
        policy_id="p",
        policy_name="p",
        policy_version="1.0.0",
        altloc_rules=altloc_rules,
    )
    canonical, mappings, _ = canonicalise_structure(structure, policy)
    atoms = [a for a in canonical.atoms if a.label_seq_id == 35]
    print(f"{altloc_rules.strategy}: {len(atoms)} atoms in residue 35")
    for item in mappings.altloc_selection_mapping.items:
        print(
            f"  {item.residue_id}: kept {item.selected_altloc} of "
            f"{item.available_altlocs} ({item.selection_reason})"
        )

from pandora.canonicalisation import canonicalise_structure
from pandora.parsing import mmcif_to_structure
from pandora.schemas.canonicalisation import (
    AssemblyRules,
    canonicalisationPolicy,
)

# 13dg: assembly 1 is chains A-D under operators 1, 2 and 3.
structure, _, _ = mmcif_to_structure("datasets/dev/mmcif/13dg.cif")
print("asymmetric unit:", [u.id for u in structure.asym_units])

policy = canonicalisationPolicy(
    policy_id="p",
    policy_name="p",
    policy_version="1.0.0",
    assembly_rules=AssemblyRules(strategy="standardize_biological_assembly"),
)
canonical, mappings, _ = canonicalise_structure(structure, policy)
print("after expansion:", [u.id for u in canonical.asym_units])
for item in mappings.assembly_mapping.items:
    for copy in item.chain_copies[:2]:
        print(
            f"  {copy.canonical_chain_id} = chain {copy.source_chain_id} "
            f"under operator {copy.operator_id}"
        )

from pandora.canonicalisation import canonicalise_structure
from pandora.parsing import mmcif_to_structure
from pandora.schemas.canonicalisation import (
    ModifiedResidueRules,
    canonicalisationPolicy,
)


def mapped(path: str, rules: ModifiedResidueRules) -> None:
    structure, _, _ = mmcif_to_structure(path)
    policy = canonicalisationPolicy(
        policy_id="p",
        policy_name="p",
        policy_version="1.0.0",
        modified_residue_rules=rules,
    )
    _, mappings, provenance = canonicalise_structure(structure, policy)
    print(f"{structure.entry_id} {provenance.transforms[0]}")
    for item in mappings.modified_residue_mapping.items:
        print(
            f"  chain {item.chain_id} {item.seq_id}: "
            f"{item.original_comp_id} -> {item.parent_comp_id}"
        )


# Selenomethionine, mapped by default once the strategy is on.
mapped(
    "datasets/dev/mmcif/1b6w.cif",
    ModifiedResidueRules(strategy="map_to_parent"),
)
# Any residue named in comp_ids whose parent the file lists.
mapped(
    "datasets/dev/mmcif/1a08.cif",
    ModifiedResidueRules(strategy="map_to_parent", comp_ids=["FTY"]),
)

from pandora.canonicalisation import canonicalise_structure
from pandora.parsing import mmcif_to_structure
from pandora.schemas.canonicalisation import (
    IncompleteChainRules,
    MissingAtomsRules,
    MissingDataRules,
    canonicalisationPolicy,
)


def residues(structure, chain: str) -> int:
    return len(
        {a.label_seq_id for a in structure.atoms if a.label_asym_id == chain}
    )


def canonicalise(structure, rules: MissingDataRules):
    policy = canonicalisationPolicy(
        policy_id="p",
        policy_name="p",
        policy_version="1.0.0",
        missing_data_rules=rules,
    )
    canonical, _, _ = canonicalise_structure(structure, policy)
    return canonical


# 1a08 chain B: two residues lack part of their backbone.
structure, _, _ = mmcif_to_structure("datasets/dev/mmcif/1a08.cif")
dropped = canonicalise(
    structure,
    MissingDataRules(
        missing_atoms=MissingAtomsRules(strategy="drop_partial_residue")
    ),
)
print(
    "drop_partial_residue, 1a08 chain B:",
    residues(structure, "B"),
    "->",
    residues(dropped, "B"),
    "residues",
)

# 10mv chain A has a gap; keep only its longest unbroken stretch.
structure, _, _ = mmcif_to_structure("datasets/dev/mmcif/10mv.cif")
truncated = canonicalise(
    structure,
    MissingDataRules(
        incomplete_chains=IncompleteChainRules(
            strategy="truncate_to_complete_regions"
        )
    ),
)
print(
    "truncate_to_complete_regions, 10mv chain A:",
    residues(structure, "A"),
    "->",
    residues(truncated, "A"),
    "residues",
)

from pandora.canonicalisation import canonicalise_structure, filter_ligands
from pandora.parsing import mmcif_to_structure
from pandora.schemas.canonicalisation import (
    LigandRules,
    canonicalisationPolicy,
)
from pandora.schemas.common import DiagnosticBundle

# 104m: myoglobin, a sulfate ion, a heme, n-butyl isocyanide and waters.
structure, _, _ = mmcif_to_structure("datasets/dev/mmcif/104m.cif")
names = {e.id: e.pdbx_description for e in structure.entities}

policy = canonicalisationPolicy(
    policy_id="p",
    policy_name="p",
    policy_version="1.0.0",
    ligand_rules=LigandRules(
        strategy="filter", keep_waters=False, keep_ions=False
    ),
)
canonical, _, _ = canonicalise_structure(structure, policy)
print("in the policy:", len(structure.atoms), "->", len(canonical.atoms))
kept = sorted({names[u.entity_id] for u in canonical.asym_units})
print("  kept:", kept)

# The same filter on its own, without the rest of canonicalisation.
atoms, asym_units = filter_ligands(
    list(structure.atoms),
    list(structure.asym_units),
    structure.entities,
    LigandRules(strategy="filter", keep_waters=False, keep_ions=True),
    DiagnosticBundle(),
    structure.entry_id,
)
print("filter_ligands, keep ions:", len(structure.atoms), "->", len(atoms))

from pandora.canonicalisation import canonicalise_structure
from pandora.parsing import mmcif_to_structure
from pandora.schemas.canonicalisation import (
    ChainIdRules,
    IdentifierRules,
    ModifiedResidueRules,
    ResidueNumberingRules,
    canonicalisationPolicy,
    canonicalisationProvenanceRules,
)

structure, _, _ = mmcif_to_structure("datasets/dev/mmcif/1b6w.cif")

policy = canonicalisationPolicy(
    policy_id="p",
    policy_name="p",
    policy_version="1.0.0",
    identifier_rules=IdentifierRules(
        chain_id=ChainIdRules(strategy="use_auth_chain_id"),
        residue_numbering=ResidueNumberingRules(strategy="renumber"),
    ),
    modified_residue_rules=ModifiedResidueRules(strategy="map_to_parent"),
    provenance_rules=canonicalisationProvenanceRules(
        emit_canonicalisation_report=True
    ),
)
canonical, mappings, provenance = canonicalise_structure(structure, policy)

# Which rule groups changed something, in the order they ran.
print("transforms:", provenance.transforms)
# How many diagnostics the run raised (the diagnostics themselves are
# not returned yet).
print("report:", provenance.report)
# One mapping list per kind of change, to trace any id back.
for name, mapping in mappings:
    print(f"{name}: {len(mapping.items)} items")
# Verbatim mmCIF categories that referred to the old chain or residue
# ids, removed so the structure doesn't contradict itself.
print("dropped:", len(provenance.dropped_raw_categories), "raw categories")
print(" ", provenance.dropped_raw_categories[:4])

from pandora.canonicalisation import canonicalise_structure
from pandora.ingestion.policy import load_policy
from pandora.parsing import mmcif_to_structure

policy = load_policy("datasets/canonicalisation.yaml")
structure, _, _ = mmcif_to_structure("datasets/dev/mmcif/104m.cif")
canonical, mappings, provenance = canonicalise_structure(structure, policy)

print(policy.policy_id, policy.policy_version)
print(provenance.transforms)