molsysmt.build.get_missing_residues#

molsysmt.build.get_missing_residues(molecular_system, sequence=None, selection='all', syntax='MolSysMT', engine='MolSysMT')[source]#

Identify residues that are missing from a molecular system relative to a reference sequence.

This function compares the residues present in the molecular system against a reference sequence and returns a mapping of insertion positions to the names of the residues that are absent.

Parameters:

  • molecular_system (molecular system) – Molecular system in any of the supported forms.

  • sequence (dict or None, default None) –

    Reference sequence as {chain_id: [res_name_1, res_name_2, ...]}, where residue names are 3-letter codes. When None (default), the function attempts to extract the reference sequence automatically:

    • file:pdb — from SEQRES records.

    • file:bcif / file:bcif_gz — from the _entity_poly_seq mmCIF table.

    • string:pdb_id — downloads the binary CIF and uses the same path.

    • All other forms — emits a UserWarning and returns {}.

  • selection (str, list, tuple, or numpy.ndarray, default 'all') – Atom selection used to restrict the search to a subset of the system.

  • syntax (str, default 'MolSysMT') – Syntax used to interpret the selection string.

  • engine ({'MolSysMT', 'PDBFixer'}, default 'MolSysMT') –

    Backend used to detect missing residues.

    • 'MolSysMT': native implementation using SequenceMatcher to align the structural sequence against the reference. Requires a reference sequence (from sequence or auto-detected).

    • 'PDBFixer': delegates to pdbfixer.PDBFixer.findMissingResidues. Ignores the sequence argument.

Returns:

Dictionary mapping (chain_index, insertion_position) tuples to lists of residue names (str). chain_index is the 0-based index of the chain in the (sub)system; insertion_position is the 0-based index within that chain’s structural sequence before which the missing residues should be inserted. For insertions after the last residue of a chain the insertion_position equals the number of residues in that chain.

Return type:

dict

Raises:

NotImplementedMethodError – Raised if the requested engine is not supported.

Notes

engine=’MolSysMT’ limitations: Only amino-acid and nucleotide chains with a detectable reference sequence are analysed. Non-standard residues in the reference that are absent from the structure will be reported as missing; non-standard residues present in the structure but absent from the reference will be silently ignored.

Post-1.0 roadmap: When sequence=None and the molecular system has no embedded sequence information, a future version will optionally query UniProt or the PDB REST API using the entity name or PDB ID.

Added in version 1.0.0.

On this page