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

Editors support two modes: An unbuffered edit mode and a buffered edit mode. In the 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. In buffered edit mode, the updates are delayed until one of the following happens:

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. Alternatively, starting from Python version 2.6, one can use the with statement to make sure the destructor are called and the dependent information is updated.

Basic Editing Operations

The basic functionality of editors is implemented in the EditorBase class.

class EditorBase

Inherited by XCSEditor, ICSEditor.

InsertChain(chain_name)

Add new chain to the entity

Parameters:

chain_name (string) – The chain’s name. In the scope of an entity, chain names are unique. If a chain of the same already exists an IntegrityError is raised.

Returns:

ChainHandle

AppendResidue(chain, residue_name[, res_num])

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.

Parameters:

  • chain (ChainHandle) – Must be a valid chain

  • residue_name (string) – 3-letter-code of the residue, e.g. GLY.

Returns:

ResidueHandle

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 residue

  • new_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 chain

  • new_name (string) – is the new name

SetChainType(chain, type)
Parameters:
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. 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 valid

  • atom_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 the conop module rely on proper naming.

  • pos (Vec3) – is the position of the atom in global coordinates

  • element (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:

AtomHandle

InsertAltAtom(residue, atom_name, alt_group, pos, element='', occupancy=1.0, b_factor=0.0)

Insert new atom with alternative position indicator

Parameters:

  • residue (ResidueHandle) – is the parent residue and must be valid

  • atom_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 the conop 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 coordinates

  • element (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.

Returns:

AtomHandle

InsertAltAtom(residue, atom, alt_group)

Insert new atom with alternative position indicator

Parameters:

  • residue (ResidueHandle) – is the parent residue and must be valid

  • atom (AtomHandle) – Must be a valid Atom

  • alt_group (string) – group is the name of the alternative atom position group. If no group of that name exists, it will be created.

Returns:

AtomHandle

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 coordinates

  • occupancy (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 PSI

  • atom1 (AtomHandle) – First atom. must be valid

  • atom2 (AtomHandle) – Second atom. must be valid

  • atom3 (AtomHandle) – Third atom. must be valid

  • atom4 (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 chain

  • new_numbers (ResNumList) – A valid ResNumList

RenumberChain(chain, start, keep_spacing)

Renumber residues of the given chain

Parameters:

  • chain (ChainHandle) – A valid chain

  • start (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

GetMode()

Get edit mode of editor

Returns:

EditMode

RenameAtom(atom, new_name)

Change the name of atom to new_name without changing anything else.

Parameters:

  • atom (AtomHandle) – Must be a valid atom

  • new_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 residue

  • num – Residue number

Connect(atom1, atom2)
Connect(atom1, atom2, bond_order)

Add a bond between two atoms.

Parameters:

  • atom1 (AtomHandle) – Must be a valid atom

  • atom2 (AtomHandle) – Must be a valid atom

  • bond_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) – The transformation to be applied

ApplyTransform(transform)

Apply a transformation to the entity. The transformation is applied to all atoms positions.

Parameters:

transform (Transform) – The transformation to be applied

SetTransform(transform)

Set the entity transformation. See also ApplyTransform()

Parameters:

transform (geom.Mat4) – The transformation to be applied

SetTransform(transform)

Set the entity transformation. See also ApplyTransform()

Parameters:

transform (Transform) – 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.

Setting all positions at once is by far faster than call the function for each atom, but it is only available if OpenStructure was compiled with an enabled USE_NUMPY flag (see here for details). The fastest option to work with all atom positions externally is to extract the list of atoms with ost.mol.EntityHandle.GetPositions() (with sort_by_index = False). Then extract a buffered editor and use the same list of atoms with a modified numpy array as input to this function. Example:

# get atom list and positions
atom_list = ent.atoms
positions = ent.GetPositions(False)
# modify positions but keep ent and atom_list unchanged
# ...
# apply changes to entity all at once
edi = ent.EditXCS(mol.BUFFERED_EDIT)
edi.SetAtomPos(atom_list, positions)
edi.UpdateICS()
Parameters:

  • atom (ost.mol.AtomHandle) – A valid atom handle

  • atom_list (ost.mol.AtomHandleList or list of int) – A valid atom handle list or a list of atom indices.

  • pos (Vec3) – The new position

  • pos_list (numpy.array) – An array of positions (shape [len(atom_list), 3], preferably contiguous array in memory (C order)).

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.

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:

UpdateXCS()

Parameters:

  • torsion (TorsionHandle) – A valid torsion

  • angle (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:

UpdateXCS()

Parameters:

  • atom1 (AtomHandle) – The first atom. Must be valid

  • atom2 (AtomHandle) – The second atom. Must be valid

  • atom3 (AtomHandle) – The third atom. Must be valid

  • atom4 (AtomHandle) – The third atom. Must be valid

  • angle – 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:

UpdateXCS()

Parameters:

  • torsion (TorsionHandle) – A valid torsion

  • delta (Real) – delta

  • update_others (bool) – Update all the the other torsion angles consequently

RotateTorsionAngle(atom1, atom2, atom3, atom4, angle, update_others=True)

Rotate torsion angle

See:

UpdateXCS()

Parameters:

  • atom1 (AtomHandle) – The first atom. Must be valid

  • atom2 (AtomHandle) – The second atom. Must be valid

  • atom3 (AtomHandle) – The third atom. Must be valid

  • atom4 (AtomHandle) – The third atom. Must be valid

  • angle – 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 handle

  • length (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 valid

  • atom2 (AtomHandle) – The second atom. Must be valid

  • atom3 (AtomHandle) – The third atom. Must be valid

  • angle – 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.