schrodinger.livedesign.biologics.helm_mapping module¶

Functions and classes related to mapping monomers between two HELM strings using MCES.

class schrodinger.livedesign.biologics.helm_mapping.MonomerMapping(helm_mapping: dict[tuple[str, int], tuple[str, int]], similarity: float, pdb_mapping: dict[tuple[str, int, str], tuple[str, int]] = <factory>, penalty: float = 0.0)¶

Bases: object

Attributes:: helm_mapping (dict[tuple[str, int], tuple[str, int]]): A dictionary representing the atom-to-atom correspondence. - Keys: A tuple of (chain_id, atom_idx) for the query monomer. - Values: A tuple of (chain_id, atom_idx) for the target monomer. - query_helm : target_helm similarity (float): Similarity between 2 molecules. MCES mappings use Johnson similarity adjusted by reversal penalty if reversed segments are detected. Sequence-alignment mappings use monomer Dice similarity, adjusted for unmatched custom connections. pdb_mapping (dict[tuple[str, int, str], tuple[str, int]]): A dictionary representing the atom-to-atom correspondence. Only available if the monomer mol has the pdbToHelmChainMap property. - Keys: A tuple of (chain_id, atom_idx, insertion code) for the query monomer. - Values: A tuple of (chain_id, atom_idx) for the target monomer. - query_pdb : target_helm penalty (float): Penalty factor in [0, 1] applied to similarity. Using MCES, this is the reversal penalty based on fraction of residues in reversed segments. 0.0 means no reversals, 1.0 means all residues are reversed. Using Sequence Alignment, this is the missing connection penalty.

helm_mapping: dict[tuple[str, int], tuple[str, int]]¶

similarity: float¶

pdb_mapping: dict[tuple[str, int, str], tuple[str, int]]¶

penalty: float = 0.0¶

__init__(helm_mapping: dict[tuple[str, int], tuple[str, int]], similarity: float, pdb_mapping: dict[tuple[str, int, str], tuple[str, int]] = <factory>, penalty: float = 0.0) → None¶

schrodinger.livedesign.biologics.helm_mapping.find_monomer_mapping(query_mol: Mol, target_mol: Mol, max_bond_pairs: int = 1000) → MonomerMapping | None¶

Return a mapping from monomer index in query_helm to monomer index in target_helm.

Operates on the coarse-grained mol where each atom is one monomer, so atom indices are monomer indices directly. Monomers are matched by identity (same HELM name = same atomic number for MCES).

Parameters:: max_bond_pairs – the max number of bonds to evaluate. For large antibodies there are many bond pairs so this number will need to be increased. This also significantly increases the memory.
Raises:: RuntimeError – If either query_mol or target_mol is not monomeric

Note: MCES is edge-based, so a mutation that breaks all edges around a monomer will split the match into disconnected fragments. Short chains (e.g. 3 monomers with a central mutation) may return incomplete mappings because the fragments are too small. This works well for realistic-length chains. Note: There is also a default time out of 60 seconds for the search.

schrodinger.livedesign.biologics.helm_mapping.find_monomer_mapping_sequence_alignment(query_mol: Mol, target_mol: Mol) → MonomerMapping | None¶

Return a directed monomer mapping using global sequence alignment.

This is intended as a faster benchmark alternative to MCES for ordered biopolymer chains. Each compatible query/target chain pair is globally aligned in its natural direction, then chains are assigned one-to-one to maximize exact monomer matches. Mutated aligned positions are omitted from the returned mapping, matching the current MCES-facing behavior.

CHEM polymers are skipped.

schrodinger.livedesign.biologics.helm_mapping.find_monomer_mapping_helm(query_helm: str, target_helm: str, max_bond_pairs: int = 1000) → MonomerMapping¶

Find monomer-to-monomer mapping between two HELM strings using MCES.

Converts both HELM strings to coarse-grained RDKit molecules and computes the maximum common edge subgraph (MCES) to identify corresponding monomers between the query and target sequences.

Parameters:

query_helm – HELM string representing the query molecule
target_helm – HELM string representing the target molecule
max_bond_pairs – Maximum number of bond pairs to evaluate during MCES. Increase for large antibodies or complex structures. Higher values increase memory usage and computation time. Default is 1000.

Returns:

MonomerMapping object containing the helm_mapping dictionary and similarity score. Returns None if no mapping is found.

schrodinger.livedesign.biologics.helm_mapping.find_monomer_mapping_helm_sequence_alignment(query_helm: str, target_helm: str) → MonomerMapping | None¶: Find monomer-to-monomer mapping between two HELM strings using directed global monomer-sequence alignment.

schrodinger.livedesign.biologics.helm_mapping.find_monomer_mapping_mol_helm(query_mol: Mol, target_helm: str, max_bond_pairs: int = 1000) → MonomerMapping¶

Find monomer-to-monomer mapping between a molecule and a HELM string using MCES.

Converts the target HELM string to a coarse-grained RDKit molecule and computes the maximum common edge subgraph (MCES) to identify corresponding monomers. If the query molecule contains PDB residue information (via the “pdbToHelmChainMap” property), this function also populates the pdb_mapping field to provide a mapping from the query PDB residue numbering to target HELM monomer indices.

Parameters:

query_mol – RDKit molecule representing the query structure. May contain PDB residue information via the “pdbToHelmChainMap” property.
target_helm – HELM string representing the target molecule
max_bond_pairs – Maximum number of bond pairs to evaluate during MCES. Increase for large antibodies or complex structures. Higher values increase memory usage and computation time. Default is 1000.

Returns:

MonomerMapping object

schrodinger.livedesign.biologics.helm_mapping.find_monomer_mapping_mol_helm_sequence_alignment(query_mol: Mol, target_helm: str) → MonomerMapping | None¶

Find monomer-to-monomer mapping between a molecule and a HELM string using directed global monomer-sequence alignment.

If the query molecule contains PDB residue information, the returned mapping includes the same pdb_mapping field populated by the MCES API.