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

Returns:

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

Returns:

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

Returns:

The score

Return type:

float

Raises:

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

Return type:

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.

Return type:

float

GetPos()
Returns:

The position of the particle

Return type:

ost.geom.Vec3

GetScoringFunction()
Returns:

The underlying scoring function

Return type:

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 functional forms 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 functional forms are linearly combined with the default weights from the Autodock Vina Software. They’re set as global variables and can be extracted with:

promod3.sidechain.GetVINAWeightGaussian1()
promod3.sidechain.GetVINAWeightGaussian2()
promod3.sidechain.GetVINAWeightRepulsion()
promod3.sidechain.GetVINAWeightHydrophobic()
promod3.sidechain.GetVINAWeightHBond()

You can set custom weights. A call to the following functions overwrites according weights globally which affects any subsequent score evaluation:

promod3.sidechain.SetVINAWeightGaussian1(w)
promod3.sidechain.SetVINAWeightGaussian2(w)
promod3.sidechain.SetVINAWeightRepulsion(w)
promod3.sidechain.SetVINAWeightHydrophobic(w)
promod3.sidechain.SetVINAWeightHBond(w)

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:

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

Returns:

Particle at specified index

Raises:

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 (“”)

Raises:

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

Raises:

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

Returns:

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

Returns:

Particle at specified index

Raises:

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 (“”)

Raises:

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

Raises:

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

Returns:

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

Returns:

list of particle indices belonging to this particular subrotamer

Raises:

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

Returns:

Frame energy if calculated, 0.0 otherwise

Raises:

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.

Raises:

RuntimeError if provided rotamers is empty

__len__()
Returns:

Number of rotamers in group

__getitem__(index)
Returns:

RRMRotamer at given index

Raises:

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

Raises:

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.

Raises:

RuntimeError if provided rotamers is empty

__len__()
Returns:

Number of rotamers in group

__getitem__(index)
Returns:

FRMRotamer at given index

Raises:

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

Raises:

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.

Contents