You are reading the documentation for version 2.1 of ProMod3. You may also want to read the documentation for: 1.3 2.0 3.0 3.1 3.2

# Representing Sidechains - Rotamers & Co.¶

A rotamer represents an amino acid sidechain identified by a RotamerID and is a set of Particle objects. Two types of rotamers exist. The RRMRotamer and FRMRotamer. To gather all possible rotamers for one location, ProMod3 offers the RRMRotamerGroup and FRMRotamerGroup. All parts of the structure that are kept rigid can be represented by a Frame object.

## RotamerID¶

The sidechain module has its own definition of amino acids to satisfy custom requirements for the implemented sidechain construction algorithms. As an example there are histidine in two possible protonation states, that affect the hbond term or different versions of proline/cysteine.

class promod3.sidechain.RotamerID

Enumerates the amino acids. Possible values:

 ARG - Arginine ASN - Asparagine ASP - Aspartate GLN - Glutamine GLU - Glutamate LYS - Lysine SER - Serine CYS - Cystein CYH - “free” Cystein CYD - disulfid bonded Cystein MET - Methionine TRP - Tryptophane TYR - Tyrosine THR - Threonine VAL - Valine ILE - Isoleucine LEU - Leucine PRO - Proline CPR - cis-Proline TPR - trans-Proline HIS - Histidine HSD - d-protonated Histidine HSE - e-protonated Histidine PHE - Phenylalanine GLY - Glycine ALA - Alanine XXX - Invalid

The RotamerID enum can be accessed either directly as promod3.sidechain.ARG or as promod3.sidechain.RotamerID.ARG.

### How can I get an ID?¶

The RotamerID enum can directly be accessed from Python. Two convenient functions exist to get RotamerIDs from the ost.conop.AminoAcid enum or from amino acid three letter codes.

promod3.sidechain.TLCToRotID(tlc)

Directly translates the three letter code into a RotamerID. Following exactly the naming convention defined above.

Parameters: tlc (str) – Three letter code of amino acid RotamerID, XXX if tlc cannot be recoginzed.
promod3.sidechain.AAToRotID(aa)

Directly translates aa into a RotamerID. Note, that it is not possible to generate special IDs this way (e.g. HSD, HSE or the special prolines/cysteins) since they’re simply not defined in ost.conop.AminoAcid

Parameters: aa (ost.conop.AminoAcid) – AA enum of amino acid RotamerID, XXX if aa is invalid.

## The Smallest Building Block - The Particle¶

Particles give raise to more complex objects such as rotamers and frame residues. They contain all data required to calculate pairwise energies. For every energy function available in ProMod3, there’s a particle creation function.

class promod3.sidechain.PScoringFunction

The available scoring functions between Particle objects

class promod3.sidechain.Particle

The particle class. There’s no constructor. You can either use the RotamerConstructor to create full RotamerGroup objects with all underlying particles or the energy function specific creation functions.

PairwiseScore(other_particle)

Calculates score between the two particles

Parameters: other_particle (Particle) – The interacting particle The score float RuntimeError if the scoring function parametrization of the two particles is inconsistent
GetName()
Returns: The name of the particle, which corresponds to the atom name str
GetCollisionDistance()
Returns: The “collision distance” all pairs of particles with their distance below the sum of their collision distances are considered as interacting and thus evaluated by the underlying scoring function. float
GetPos()
Returns: The position of the particle ost.geom.Vec3
GetScoringFunction()
Returns: The underlying scoring function PScoringFunction

### The SCWRL4 scoring function¶

The SCWRL4 scoring function combines a Lennard-Jones style term with a hydrogen bond term. Details can be found in the relevant publication [krivov2009].

class promod3.sidechain.SCWRL4ParticleType

The SCWRL4 energy function differentiates between following particle types that define the behaviour of the Lennard-Jones style term:

• HParticle - represents hydrogen
• CParticle - default representation of a carbon
• CH1Particle - represents carbon bound to 1 hydrogen
• CH2Particle - represents carbon bound to 2 hydrogen
• CH3Particle - represents carbon bound to 3 hydrogen
• NParticle - represents nitrogen
• OParticle - default representation of oxygen
• OCParticle - represents carbonyl-oxygen for ASP/GLU
• SParticle - represents sulfur
promod3.sidechain.CreateSCWRL4Particle(name, particle_type, pos[, charge, lone_pairs=None, polar_direction=None])

Creates and returns a Particle that can evaluate the SCWRL4 scoring function

Parameters: name (str) – The name of the particle particle_type (SCWRL4ParticleType) – The type of the particle pos (ost.geom.Vec3) – The position of the particle charge (float) – The charge of the particle, relevant for the hydrogen bond term lone_pairs (ost.geom.Vec3List) – Direction of all possible lone pairs of the particle, relevant for the hydrogen bond term. If set, the particle is a potential hydrogen bond acceptor. An example would be the Serine OG atom, where you can represent the two lone pairs with vectors pointing from the OG position towards the lone pair centers. polar_direction (ost.geom.Vec3) – The polar direction of the particle, relevant for the hydrogen bond term. If set, the particle is a potential hydrogen bond donor. An example would be the Serine HG hydrogen. The polar_direction would be a vector estimated as follows: hg_pos-og_pos.

### The SCWRL3 scoring function¶

The SCWRL3 scoring function implements a simple repulsion term that depends on the hard-sphere radius of the involved particles. Details can be found in the relevant publication [canutescu2003].

promod3.sidechain.CreateSCWRL3Particle(name, radius, pos)

Creates and returns a Particle that can evaluate the SCWRL3 scoring function

Parameters: name (str) – The name of the particle radius (float) – The hard-sphere radius of the particle, relevant for the repulsion term. pos (ost.geom.Vec3) – The position of the particle

### The VINA scoring function¶

The VINA scoring function is a combination of scores that are named gaussian1, gaussian2, repulsion, hydrophobic and hbond in the Autodock Vina software [trott2010]. VINA only evaluates heavy atoms. Gaussian1, gaussian2 and repulsion are evaluated for all pairs of particles. Hydrophobic is only evaluated between C_VINAParticle VINAParticleType and hbond is evaluated between hydrogen bond donor/acceptor pairs. While SCWRL3 and SCWRL4 are intended to evaluate sidechain-sidechain interactions in proteins, VINA is mainly targeted at interactions between sidechains and ligands.

The VINA scoring function differentiates between the following particle types:

class promod3.sidechain.VINAParticleType
• O_D_VINAParticle - Oxygen that can be a hydrogen bond donor
• N_D_VINAParticle - Nitrogen that can be a hydrogen bond donor
• O_A_VINAParticle - Oxygen that can be a hydrogen bond acceptor
• N_A_VINAParticle - Nitrogen that can be a hydrogen bond acceptor
• O_AD_VINAParticle - Oxygen that can be a hydrogen bond donor and acceptor
• N_AD_VINAParticle - Nitrogen that can be a hydrogen bond donor and acceptor
• O_VINAParticle - Oxygen
• N_VINAParticle - Nitrogen
• S_VINAParticle - Sulfur
• P_VINAParticle - Phosphorus
• C_P_VINAParticle - Polar carbon that is covalently bound to a charged atom
• C_VINAParticle - Hydrophobic carbon that is only bound to other carbons or hydrogens
• F_VINAParticle - Fluorine
• Cl_VINAParticle - Chlorine
• Br_VINAParticle - Bromine
• I_VINAParticle - Iodine
• M_VINAParticle - Metals
• INVALID_VINAParticle - Invalid particle...
promod3.sidechain.CreateVINAParticle(name, particle_type, pos)

Creates and returns a Particle that can evaluate the VINA scoring function

Parameters: name (str) – The name of the particle radius (VINAParticleType) – The type of the particle pos (ost.geom.Vec3) – The position of the particle

## Rotamers¶

class promod3.sidechain.RRMRotamer(particles, probability, internal_e_prefactor)

The RRMRotamer represents a rotamer of the so called rigid rotamer model.

Parameters: particles (list) – List of Particle objects probability (float) – Probability of rotamers. In case of the SCWRL4 energy calculation, this directly controls the internal energy of that rotamer. internal_e_prefactor (float) – Factor applied to the internal energy calculated as -log(probability/max_probability), where max_probability is the maximum rotamer probability of any rotamer in a particular RRMRotamerGroup.
__getitem__(index)

Access particle at specified index

Parameters: index (int) – Index of particle of interest Particle at specified index RuntimeError if index is invalid
__len__()
Returns: Number of particles the rotamer contains
ApplyOnResidue(res, consider_hydrogens=False, new_res_name="")

Iterates over every particle and searches for the according atom in res. If it’s present, the position gets reset to the particle position. If not, a new atom gets added to res. No atoms are removed from res in this process.

Parameters: res (ost.mol.ResidueHandle) – Residue to be reconstructed consider_hydrogens (bool) – Flag, whether polar hydrogens should be added to res new_res_name (str) – New name of res. Nothing happens in case of the default value (“”) RuntimeError if not all required backbone atoms are present in res
ApplyOnResidue(all_atom, res_idx)

Set all sidechain atom positions for given residue to the positions of the particles in the rotamer.

Parameters: all_atom (AllAtomPositions) – Container to which to apply rotamer res_idx (int) – Residue index into all_atom RuntimeError if res_idx is invalid
ToFrameResidue(res_idx)

Generates and returns a FrameResidue based on the internal particles.

Parameters: res_idx (int) – Idx passed over to FrameResidue constructor The constructed FrameResidue
GetInternalEnergyPrefactor()
Returns: Prefactor used in internal energy calculation
GetInternalEnergy()
Returns: Internal Energy if calculated, 0.0 otherwise
GetFrameEnergy()

Returns frame energy. This energy can either be manually set or calculated using a Frame and the RRMRotamerGroup this rotamer belongs to.

Returns: Frame energy if calculated, 0.0 otherwise
GetSelfEnergy()
Returns: Self energy consisting of internal plus frame energy
GetProbability()
Returns: probability of this rotamer
SetInternalEnergyPrefactor(prefactor)
Parameters: energy (float) – Internal energy prefactor to be set
SetInternalEnergy(energy)
Parameters: energy (float) – Internal energy to be set
SetFrameEnergy(energy)
Parameters: energy (float) – Frame energy to be set
AddFrameEnergy(energy)
Parameters: energy (float) – Frame energy to be added
SetProbability(probability)
Parameters: energy (float) – Internal probability to be set
class promod3.sidechain.FRMRotamer(particles, T, probability, internal_e_prefactor)

The FRMRotamer represents a rotamer of the so called flexible rotamer model, where one rotamer gets represented by several subrotamers. The idea is that all particles of all subrotamers are given at initialization. Subrotamers are then defined by providing lists of indices. One particle can be part of several subrotamers.

Parameters: particles (list) – List of Particle objects probability (float) – Probability of rotamers. In case of the SCWRL4 energy calculation, this directly controls the internal energy of that rotamer. T (float) – Temperature factor, that is used to generate a final energy given the subrotamers according to the formalism described in the SCWRL4 paper. internal_e_prefactor (float) – Factor applied to the internal energy calculated as -log(probability/max_probability), where max_probability is the maximum rotamer probability of any rotamer in a particular FRMRotamerGroup.
__getitem__(index)

Access particle at specified index

Parameters: index (int) – Index of particle of interest Particle at specified index RuntimeError if index is invalid
__len__()
Returns: Number of particles the rotamer contains
GetNumSubrotamers()
Returns: Number of subrotamers
ApplyOnResidue(res, consider_hydrogens=False, new_res_name="")

Iterates over every particle of the active subrotamer and searches for the according atom in res. If it’s present, the position gets reset to the particle position. If not, a new atom gets added to res. No atoms are removed from res in this process.

Parameters: res (ost.mol.ResidueHandle) – Residue to be reconstructed consider_hydrogens (bool) – Flag, whether polar hydrogens should be added to the sidechain new_res_name (str) – New name of residue. Nothing happens in case of the default value (“”) RuntimeError if not all required backbone atoms are present in res
ApplyOnResidue(all_atom, res_idx)

Set all sidechain atom positions for given residue to the positions of the particles in the active surotamer.

Parameters: all_atom (AllAtomPositions) – Container to which to apply rotamer res_idx (int) – Residue index into all_atom RuntimeError if res_idx is invalid
ToFrameResidue(res_idx)

Generates and returns a FrameResidue based on the internal particles of the active subrotamer.

Parameters: res_idx (int) – Idx passed over to FrameResidue constructor The constructed FrameResidue
ToRRMRotamer()

Generates and returns a RRMRotamer based on the internal particles of the active subrotamer. Following parameters of the returned rotamer get set: probability (probability of the whole FRMRotamer), internal_e_prefactor (prefactor of the whole FRMRotamer), frame_energy (The frame energy of that particular subrotamer if already calculated), internal_energy (the internal energy of the whole FRMRotamer)

GetSubrotamerDefinition(index)
Parameters: index (int) – Index of subrotamer list of particle indices belonging to this particular subrotamer RuntimeError if index is invalid
GetInternalEnergyPrefactor()
Returns: Prefactor used in internal energy calculation
GetInternalEnergy()
Returns: Internal Energy if calculated, 0.0 otherwise
GetFrameEnergy()

Returns frame energy. This energy can either be manually set or calculated using a Frame and the FRMRotamerGroup this rotamer belongs to.

Returns: Frame energy if calculated, 0.0 otherwise
GetFrameEnergy(index)

Returns frame energy of specified index.

Parameters: index (int) – Index of subrotamer you want the frame energy from Frame energy if calculated, 0.0 otherwise RuntimeError if index is invalid
GetSelfEnergy()
Returns: Self energy consisting of internal plus frame energy
GetTemperature()
Returns: The temperature factor for this rotamer
GetProbability()
Returns: Probability of this rotamer
SetInternalEnergyPrefactor(prefactor)
Parameters: energy (float) – Internal energy prefactor to be set
SetInternalEnergy(energy)
Parameters: energy (float) – Internal energy to be set
SetFrameEnergy(energy)
Parameters: energy (float) – Frame energy for full rotamer to be set
SetFrameEnergy(energy, index)
Parameters: energy (float) – Frame energy for single subrotamer to be set index – Index of subrotamer
AddFrameEnergy(energy)
Parameters: energy (float) – Frame energy for full rotamer to be added
AddFrameEnergy(energy, index)
Parameters: energy (float) – Frame energy for single subrotamer to be added index – Index of subrotamer
AddSubrotamerDefinition(indices)
Parameters: indices (list) – List of indices defining a subrotamer
SetActiveSubrotamer(idx)

The provided idx relates to the subrotamer definitions added at the rotamer buildup. This idx controls which subrotamer is used when ApplyOnResidue(), ToFrameResidue() or ToRRMRotamer() gets called. By default, the value is 0 => first added subrotamer definition gets used.

Parameters: idx (int) – Index of subrotamer definition applied on residues
GetActiveSubrotamer()

Get the index of the active subrotamer

SetTemperature(temperature)
Parameters: temperature (float) – Temperature factor for this rotamer
SetProbability(probability)
Parameters: energy (float) – Internal probability to be set

## Rotamer Groups¶

class promod3.sidechain.RRMRotamerGroup(rotamers, residue_index)

The RRMRotamerGroup groups several RRMRotamer objects for the same residue position.

Parameters: rotamers (list) – A list of RRMRotamer objects residue_index (int) – Location of residue this FRMRotamerGroup represents. This index is important when calculating frame energies to neglect the interactions to frame particles of the same residue. RuntimeError if provided rotamers is empty
__len__()
Returns: Number of rotamers in group
__getitem__(index)
Returns: RRMRotamer at given index RuntimeError if index is invalid
ApplyOnResidue(index, res, consider_hydrogens=False, new_res_name="")
ApplyOnResidue(index, all_atom, res_idx)

Calls ApplyOnResidue function on rotamer at position index

Parameters: index (int) – Rotamer index res (ost.mol.ResidueHandle) – Residue to be reconstructed consider_hydrogens (bool) – Flag, whether polar hydrogens should be added to the sidechain new_res_name (str) – New name of residue. Nothing happens in case of the default value (“”) all_atom (AllAtomPositions) – Container to which to apply rotamer res_idx (int) – Residue index into all_atom RuntimeError if not all required backbone atoms are present in res or when index or res_idx are invalid
Merge(other)

Adds all rotamers in other to current RRMRotamerGroup

Parameters: other (RRMRotamerGroup) – RotamerGroup to be merged in
SetFrameEnergy(frame)

Calculates sets the energy of all rotamers in the group towards the given frame.

Parameters: frame (Frame) – Frame containing rigid particles
AddFrameEnergy(frame)

Calculates adds the energy of all rotamers in the group towards the given frame.

Parameters: frame (Frame) – Frame containing rigid particles
ApplySelfEnergyThresh(thresh=30)

Searches rotamer with lowest self energy l_e and deletes all rotamers with self_energy > l_e + thresh

class promod3.sidechain.FRMRotamerGroup(rotamers, residue_index)

The FRMRotamerGroup groups several FRMRotamer objects for the same residue position.

Parameters: rotamers (list) – A list of FRMRotamer objects residue_index (int) – Location of residue this FRMRotamerGroup represents. This index is important when calculating frame energies to neglect the interactions to frame particles of the same residue. RuntimeError if provided rotamers is empty
__len__()
Returns: Number of rotamers in group
__getitem__(index)
Returns: FRMRotamer at given index RuntimeError if index is invalid
ApplyOnResidue(index, res, consider_hydrogens=False, new_res_name="")
ApplyOnResidue(index, all_atom, res_idx)

Calls ApplyOnResidue function on rotamer at position index

Parameters: index (int) – Rotamer index res (ost.mol.ResidueHandle) – Residue to be reconstructed consider_hydrogens (bool) – Flag, whether polar hydrogens should be added to the sidechain new_res_name (str) – New name of residue. Nothing happens in case of the default value (“”) all_atom (AllAtomPositions) – Container to which to apply rotamer res_idx (int) – Residue index into all_atom RuntimeError if not all required backbone atoms are present in res or when index or res_idx are invalid
Merge(other)

Adds all rotamers in other to current FRMRotamerGroup

Parameters: other (FRMRotamerGroup) – RotamerGroup to be merged in
SetFrameEnergy(frame)

Calculates sets the energy of all rotamers in the group towards the given frame.

Parameters: frame (Frame) – Frame containing rigid particles
AddFrameEnergy(frame)

Calculates adds the energy of all rotamers in the group towards the given frame.

Parameters: frame (Frame) – Frame containing rigid particles
ApplySelfEnergyThresh(thresh=30)

Searches rotamer with lowest self energy l_e and deletes all rotamers with self_energy > l_e + thresh

## Search

Enter search terms or a module, class or function name.

## Previous topic

sidechain - Sidechain Modelling

## Next topic

Frame - The Rigid Part