Mutate#

Mutating amino acid or nucleotide residues in a molecular system.

The function molsysmt.build.mutate() substitutes amino acids in peptide or protein groups. A target name alone does not establish a complete chemical state or a validated side-chain conformation.

Added in version 1.0.0.

API documentation

Follow this link for a detailed description of the input arguments, raised errors, and returned objects of this function: molsysmt.build.mutate().

Basic usage#

Let’s show how this function works by building a pentapeptide and applying residue mutations:

import molsysmt as msm

molsys = msm.build.build_peptide('TyrGlyGlyPheMet')

msm.info(molsys, element='group')

index	id	name	type	n atoms	molecule type	entity name
0	1	TYR	amino acid	21	peptide	peptide 0
1	2	GLY	amino acid	7	peptide	peptide 0
2	3	GLY	amino acid	7	peptide	peptide 0
3	4	PHE	amino acid	20	peptide	peptide 0
4	5	MET	amino acid	17	peptide	peptide 0

We now mutate glycine at position 2 to alanine using a string mutation code:

new_molsys = msm.build.mutate(molsys, mutations=["GLY-2-ALA"])

msm.info(new_molsys, element='group')

index	id	name	type	n atoms	molecule type	entity name
0	1	TYR	amino acid	22	peptide	peptide 0
1	2	ALA	amino acid	10	peptide	peptide 0
2	3	GLY	amino acid	7	peptide	peptide 0
3	4	PHE	amino acid	20	peptide	peptide 0
4	5	MET	amino acid	17	peptide	peptide 0

Mutations can also be specified using a dictionary mapping group index to target amino-acid name:

new_molsys = msm.build.mutate(molsys, mutations={1: 'ALA', 2: 'VAL'})

Or mapping source residue name to target residue type across all matching residues:

new_molsys = msm.build.mutate(molsys, mutations={'GLY': 'ALA'})

Inspecting reconstruction coverage#

The default native engine removes non-backbone atoms in each target group and uses the bounded molsysmt.build.add_missing_heavy_atoms() tool. Several missing side-chain atoms, invalid anchors or conflicting local geometry remain unassessed with a warning. A VAL or TRP target can therefore retain only its backbone. Always inspect msm.build.get_missing_heavy_atoms(new_molsys) before using a mutant in downstream calculations. Hydrogen addition and sequence labels do not establish a complete target. Keep these diagnostics visible in your own preparation workflow; the introductory notebook filter hides warnings.

Use engine='PDBFixer' explicitly if you choose that optional provider’s wider reconstruction. There is no automatic fallback. Its generated coordinates still need independent geometric assessment; this function does not optimize rotamers, resolve clashes or minimize energy. The source system remains unchanged.