Editors¶
The structure, topology and connectivity of entities
is
edited via editors. This includes operations such as changing atom positions,
connecting atoms with bonds as well as adding and removing chains, residues and
atoms. There are two flavors of editors, one for the internal coordinate system (ICSEditor
) and one for the external coordinate system (XCSEditor
).
Edit Modes¶
- class EditMode¶
Editors support two modes: An unbuffered edit mode and a buffered edit mode.
- UNBUFFERED_EDIT¶
This is the default edit mode in editors. In unbuffered edit mode, dependent information such as the spatial organizer and the internal coordinate system (in case of the
XCSEditor
) are updated after every change.Warning
The unbuffered edit mode can be extremely inefficient as every operation can trigger expensive calculations.
- BUFFERED_EDIT¶
In buffered edit mode, the updates are delayed until one of the following happens:
The last editor goes out of scope.
XCSEditor.UpdateICS()
orICSEditor.UpdateXCS()
is called explicitly.
The editors follow the RIAA (resource allocation is initialization) principle: Whenever an editor is requested an internal reference counter is incremented. In the destructor, this reference count is decremented. When the count drops to zero, the dependent information is updated.
In Python, one can not rely on the destructors being called. It is advised to
always put a call to XCSEditor.UpdateICS()
or
ICSEditor.UpdateXCS()
when the editing is finished.
Here is a short example of how to use the editors to correctly create a methionine residue:
entity = ost.mol.CreateEntity()
# A buffered external coordinate system editor covers most use cases
editor = entity.EditXCS(ost.mol.EditMode.BUFFERED_EDIT)
# Insert a new protein chain
chain = editor.InsertChain("A");
editor.SetChainType(chain, ost.mol.ChainType.CHAINTYPE_POLY_PEPTIDE_L)
# Insert a residue
res1 = editor.AppendResidue(chain, "MET");
res1.SetChemClass(ost.mol.L_PEPTIDE_LINKING)
res1.SetChemType(ost.mol.ChemType.AMINOACIDS)
# Insert atoms
editor.InsertAtom(res1, "N", ost.geom.Vec3(21.609, 35.384, 56.705))
editor.InsertAtom(res1, "CA", ost.geom.Vec3(20.601, 35.494, 57.793))
editor.InsertAtom(res1, "C", ost.geom.Vec3(19.654, 34.300, 57.789))
editor.InsertAtom(res1, "O", ost.geom.Vec3(18.447, 34.456, 57.595))
# Connect them
editor.Connect(res1.FindAtom("N"), res1.FindAtom("CA"))
editor.Connect(res1.FindAtom("CA"), res1.FindAtom("C"))
editor.Connect(res1.FindAtom("C"), res1.FindAtom("O"))
# Finalize
editor.UpdateICS()
Basic Editing Operations¶
The basic functionality of editors is implemented in the EditorBase class.
Note
To use the editing functions available in EditorBase
, it is
recommended to use the external coordinate system XCSEditor
with
buffering for performance reasons.
- class EditorBase¶
Inherited by
XCSEditor
,ICSEditor
.- InsertChain(chain_name[, chain, deep=false])¶
Add new chain to the entity. Properties of
ChainHandle
chain will be inherited, if provided.- Parameters:
chain_name (
string
) – The chain’s name. In the scope of an entity, chain names are unique. If a chain of the same name already exists anIntegrityError
is raised.chain (
ChainHandle
) – The newly created chain will take over all generic properties attached to this handle.deep – If set to true, all residues and atoms of chain will be completely copied into the created chain. No bonds and angles are added.
- Returns:
- AppendResidue(chain, residue_name[, res_num])¶
- AppendResidue(chain, residue, deep=False)
Append residue to the end of the chain.
If res_num is not given, the residue number will be set to the residue number of the last added residue plus one. The insertion code is the same.
It is possible to give a residue handle as second argument, instead of a residue name. By default, atoms and bonds are not added. If deep is True, atoms (but not bonds) are added to the new residue, including alternative atoms.
- Parameters:
chain (
ChainHandle
) – Must be a valid chainresidue_name (
string
) – 3-letter-code of the residue, e.g.GLY
.residue (
ResidueHandle
) – A residue handle to copydeep (
bool
) – If set to true, insert atoms as well.
- Returns:
- RenameResidue(residue, new_name)¶
Change the name of residue to new_name. Just overwrites the 3-letter-code without changing anything else. Be aware that the sequence/ 1-letter-code will not change automatically.
- Parameters:
residue (
ResidueHandle
) – Must be a valid residuenew_name (string) – is the new name. Free to choose and not verified to be a valid identifier.
- RenameChain(chain, new_name)¶
Change the name of a chain to new_name while avoiding duplicated identifiers. If new_name is already in use by any chain, an exception will be generated.
- Parameters:
chain (
ChainHandle
) – Must be a valid chainnew_name (string) – is the new name
- SetChainType(chain, type)¶
- Parameters:
chain (
ChainHandle
) – Must be a valid chaintype (
ChainType
) – Chain type to set
- SetChainDescription(chain, description)¶
- Parameters:
chain – Must be a valid chain
description – Description to be added
- InsertAtom(residue, atom_name, pos, element='', occupancy=1.0, b_factor=0.0, is_hetatm=False)¶
Insert new atom and add it to residue. By convention, this should be the chemical symbol in upper case. For atoms with alternative atom locations use
InsertAltAtom()
. If the element parameter is a valid element, the atom properties mass, charge, and radius are set to default values for that element. If element is an empty string (or an invalid element), the properties are set to rather meaningless default values. You may later set any of the properties manually.- Parameters:
residue (
ResidueHandle
) – is the parent residue and must be validatom_name (string) – is the atom name. While free to choose a name, it is advised to properly name the atoms according to IUPAC rules as several algorithms as well as most
builders
in theconop
module rely on proper naming.pos (
Vec3
) – is the position of the atom in global coordinateselement (class:string) – is the atom’s element. If set to a a valid element, atom properties such as mass, charge, radius are set based on default values for that element. If the element string is empty, or unknown, the properties are filled with rather meaningless default values.
occupancy (float) – The occupancy of the atom. between 0 and 1
b_factor (float) – temperature factor.
is_hetatm (bool) – whether the atom is an atom coming from a HETATM record.
- Returns:
- InsertAltAtom(residue, atom_name, alt_group, pos, ele='', occ=1.0, b_factor=0.0)¶
Insert new atom with alternative position indicator
- Parameters:
residue (
ResidueHandle
) – is the parent residue and must be validatom_name (string) – is the atom name. While free to choose a name, it is advised to properly name the atoms according to IUPAC rules as several algorithms as well as most
builders
in theconop
module rely on proper naming.alt_group (string) – group is the name of the alternative atom position group. If no group of that name exists, it will be created.
pos (
Vec3
) – is the position of the atom in global coordinatesele (class:string) – is the atom’s element. If set to a a valid element, atom properties such as mass, charge, radius are set based on default values for that element. If the element string is empty, or unknown, the properties are filled with rather meaningless default values.
occ (float) – The occupancy of the atom. between 0 and 1
b_factor (float) – temperature factor.
- Returns:
- InsertAltAtom(residue, atom, alt_group)
Insert new atom with alternative position indicator
- Parameters:
residue (
ResidueHandle
) – is the parent residue and must be validatom (
AtomHandle
) – Must be a valid Atomalt_group (string) – group is the name of the alternative atom position group. If no group of that name exists, it will be created.
- Returns:
- AddAltAtomPos(alt_group, atom, pos, occupancy=1.0, b_factor=0.0)¶
Add an alternative atom position
- Parameters:
alt_group (string) – group is the name of the alternative atom position group. If no group of that name exists, it will be created.
atom (
AtomHandle
) – It is required that the atom has been inserted via InsertAltAtom, If the atom is a conventional atom without alternative location, a Error will be thrown.pos (
Vec3
) – is the position of the atom in global coordinatesoccupancy (float) – The occupancy of the atom. between 0 and 1
b_factor (float) – temperature factor.
- AddTorsion(name, atom1, atom2, atom3, atom4)¶
Add a named torsion to the entity. The atoms must have bonds between atom1-atom2-atom3-atom4.
- Parameters:
name (
str
) – The torsion name, e.g. PHI or PSIatom1 (
AtomHandle
) – First atom. must be validatom2 (
AtomHandle
) – Second atom. must be validatom3 (
AtomHandle
) – Third atom. must be validatom4 (
AtomHandle
) – Fourth atom. must be valid
- DeleteAtom(atom)¶
Deletes the atom from the entity and removes all bonds and torsions this atom is involved.
- Parameters:
atom (
EntityHandle
) – A valid atom
- DeleteAllAtoms(residue)¶
Deletes all atoms of this residue from the entity and remove all bonds and torsions for where an atom of the residue is involved.
- Parameters:
residue (
ResidueHandle
) – A valid residue
- DeleteAtoms(atoms)¶
Deletes a set specified atoms. All associated torsions and bonds will be removed as well
- Parameters:
atoms (
AtomHandleList
) – A valid set of atoms
- DeleteResidue(residue)¶
Deletes the residue, it’s atoms and removes all bonds and torsion where one atom of the residue is involved
- Parameters:
residue (
ResidueHandle
) – A valid residue
- DeleteResidues(chain)¶
Deletes all the residues of given chain. All associated atoms, residues, torsions and bonds will also be deleted
- Parameters:
chain (
ChainHandle
) – A valid chain
- DeleteChain(chain)¶
Delete the given chain, and all its residues
- Parameters:
chain (
ChainHandle
) – A valid chain
- ReorderResidues(chain)¶
- ReorderResidues()
Reorder residues of the chain (the entity) such that their residues numbers are continuously increasing. This function might be useful in cases of PDB files that do not list the residues from N to C terminus but rather use the residue number to describe their position in the chain.
- Parameters:
chain (
ChainHandle
) – A valid chain
- ReorderAllResidues()¶
Reorder residues of the all chains such that their residues numbers are continuously increasing. This function might be useful in cases of PDB files that do not list the residues from N to C terminus but rather use the residue number to describe their position in the chain.
- RenumberAllResidues(start, keep_spacing)¶
Renumber residues of all chains
- Parameters:
start (int) – Residues of every chain will be renumbered, whereas the first residue gets the residue number start.
keep_spacing (bool) – If set to false, residues will continously Otherwise the spacings between the residues are kept
- RenumberChain(chain, new_numbers)¶
Renumber residues of the given chain
- Parameters:
chain (
ChainHandle
) – A valid chainnew_numbers (
ResNumList
) – A valid ResNumList
- RenumberChain(chain, start, keep_spacing)
Renumber residues of the given chain
- Parameters:
chain (
ChainHandle
) – A valid chainstart (int) – Residues of given chain will be renumbered, whereas the first residue gets the residue number start.
keep_spacing (bool) – If set to false, residues will continously Otherwise the spacings between the residues are kept
- RenameAtom(atom, new_name)¶
Change the name of atom to new_name without changing anything else.
- Parameters:
atom (
AtomHandle
) – Must be a valid atomnew_name (string) – is the new name. Free to choose and not verified to be a valid atom identifier.
- SetResidueNumber(residue, num)¶
Change the number of residue to num without changing anything else.
- Parameters:
residue (
ResidueHandle
) – Must be a valid residuenum – Residue number
- Connect(atom1, atom2)¶
- Connect(atom1, atom2, bond_order)
Add a bond between two atoms.
- Parameters:
atom1 (
AtomHandle
) – Must be a valid atomatom2 (
AtomHandle
) – Must be a valid atombond_order (
int
) – bond order (e.g. 1=single, 2=double, 3=triple)
- Prune()¶
Removes residues and chains that don’t contain any atoms.
Editor for the External Coordinate System¶
The XCSEditor defines the interface for manipulating the external coordinate system. The external coordinate system directly operates on atom positions in Euclidian space.
- class XCSEditor¶
Inherits
EditorBase
- ApplyTransform(transform)¶
Apply a transformation to the entity. The transformation is applied to all atoms positions.
- Parameters:
transform (
geom.Mat4
orTransform
) – The transformation to be applied
- SetTransform(transform)¶
Set the entity transformation. See also
ApplyTransform()
- Parameters:
transform (
geom.Mat4
orTransform
) – The transformation to be applied
- FixTransform()¶
Set transformed positions to new original positions
- UpdateICS()¶
Immediately update internal coordinate system
- ForceUpdate()¶
Force spatial organizer and ICS update workaround for delayed editor call from Python garbage collection
- SetAtomPos(atom, pos)¶
- SetAtomPos(atom_list, pos_list)
- SetAtomTransformedPos(atom, pos)¶
- SetAtomTransformedPos(atom_list, pos_list)
Set the transformed position of atoms. This method will also update the original position of atoms by applying the inverse of the entity transform.
- SetAtomOriginalPos(atom, pos)¶
- SetAtomOriginalPos(atom_list, pos_list)
Set the original (untransformed) position of atoms. This method will also update the transformed position by applying the entity transform to the original pos. See
SetAtomPos()
for more details.
Editor for the Internal Coordinate System¶
The ICSEditor
is used to manipulate the internal coordinate system that
is defined by bond lengths and angles. You can create an editor with the
EditICS
method of the EntityHandle
.
The use XCSEditor
and ICSEditor
are mutually exclusive. This
means that whenever a XCSEditor
has pending changes, the results of
using an ICSEditor
is undefined and vice versa.
Note
For speed reasons, the internal coordinate system is not initialised until
the first call to EntityHandle.EditICS()
. This involves the build-up of
a directed-graph for the bond network as well as calculating the internal
coordinate matrices.
Warning
The ICSEditor
has a very significant performance impact on the
structure, and can make subsequent access or modifications on the entity
extremely slow to keep the internal coordinate system up-to-date. The
ICSEditor
is never used in SWISS-MODEL, ProMod3 or CAMEO. Only
open one if you absolutely need to.
- class ICSEditor¶
Inherits
EditorBase
- SetTorsionAngle(torsion, angle)¶
Set the angle of the given torsion. If the edit mode of the editor is set to buffered, the external coordinates remain unchanged. If set to unbuffered, the external coordinates are immediately recalculated.
- See:
- Parameters:
torsion (
TorsionHandle
) – A valid torsionangle (
float
) – The angle in radians
- Raises:
RuntimeError
when the torsion handle is invalid
- SetTorsionAngle(atom1, atom2, atom3, atom4, angle, update_others=True)
Set the angles of the given atoms. All connectors at the third atom (A3) will be adjusted accordingly. If you only want to adjust the bond between A3 and A4, and leave the other bonds untouched, use the
SetDihedralAngle()
function- See:
- Parameters:
atom1 (
AtomHandle
) – The first atom. Must be validatom2 (
AtomHandle
) – The second atom. Must be validatom3 (
AtomHandle
) – The third atom. Must be validatom4 (
AtomHandle
) – The third atom. Must be validangle – The angle in radians
update_others (bool) – Update all the the other torsion angles consequently
- Type:
angle:
Real
- RotateTorsionAngle(torsion, delta, update_others=True)¶
Rotate torsion angle
- See:
- Parameters:
torsion (
TorsionHandle
) – A valid torsiondelta (
Real
) – deltaupdate_others (bool) – Update all the the other torsion angles consequently
- RotateTorsionAngle(atom1, atom2, atom3, atom4, angle, update_others=True)
Rotate torsion angle
- See:
- Parameters:
atom1 (
AtomHandle
) – The first atom. Must be validatom2 (
AtomHandle
) – The second atom. Must be validatom3 (
AtomHandle
) – The third atom. Must be validatom4 (
AtomHandle
) – The third atom. Must be validangle – The angle in radians
update_others (bool) – Update all the the other torsion angles consequently
- Type:
angle:
Real
- UpdateXCS()¶
Apply all remaining changes to the internal coordinate system and recalculate external coordinates. In unbuffered edit mode, calling this method has no effect.
- SetBondLength(bond, length)¶
Sets the length of a bond. If the edit mode of the editor is set to buffered, the external coordinates remain unchanged. If set to unbuffered, the external coordinates are immediately recalculated.
- See:
UpdateICS()
- Parameters:
bond (
BondHandle
) – A valid bond handlelength (
float
) – The bond length in Angstrom.
- Raises:
RuntimeError
when the bond handle is invalid
- SetAngle(atom1, atom2, atom3, angle)¶
Sets the angle between 3 atoms. The first atom must be connected to the second, the second to the third with a bond. If the edit mode of the editor is set to buffered, the external coordinates remain unchanged. If set to unbuffered, the external coordinates are immediately recalculated.
- See:
UpdateICS()
- Parameters:
atom1 (
AtomHandle
) – The first atom. Must be validatom2 (
AtomHandle
) – The second atom. Must be validatom3 (
AtomHandle
) – The third atom. Must be validangle – The angle in radians
- Raises:
RuntimeError
when one of the atoms is invalid or there is no bond between atom1 and atom2 or atom2 and atom3.