Core Dihedral Classes

General Principles

Dihedrals are the key fundamental units defining many aspects of a molecule’s structure: backbone “twist” or secondary structure, peptide bond conformation, rotamer (sidechain) conformation, planarity, chirality, etc. Fast methods for finding, measuring and tracking them are thus a core part of ISOLDE.

Each of the groups below are arranged in essentially the same way, so I will explain the layout using proper dihedrals as an example. There are three key Python classes:

  • ProperDihedralMgr exists as a single instance per session and is responsible for creation, deletion and retrieval of C++ ProperDihedral objects. The preferred way to find the manager instance is to use session_extensions.get_proper_dihedral_mgr(). This will create the manager if it doesn’t yet exist, or simply retrieve it if it does.

  • ProperDihedral is built on the chimerax.State framework and behaves similarly to e.g. chimerax.Atom.

  • ProperDihedrals is built on the chimerax.Collection framework and behaves similarly to e.g. chimerax.Atoms.

Some general key points:

  • In general, the C++ ProperDihedral objects are only created when needed. ProperDihedralMgr.get_dihedrals() by default will work through the input list of residues, returning dihedrals that already exist and attempting to create those that don’t.

  • If any constituent atom in a C++ ProperDihedral is deleted, the dihedral will be deleted and automatically removed from any ProperDihedrals instances. Any corresponding Python ProperDihedral instances will become invalid, raising an exception if an attempt is made to use them. Similarly, Rotamer objects will be cleaned up if any constituent dihedral is deleted. The exception to this rule is Rama, where each Rama will persist as long as its associated residue has at least a CA atom. Rama instances with missing dihedrals will return valid = False, and will attempt to complete themselves on each call to the underlying C++ class.

  • The combination of the above rules means that these classes for the most part should “just work”, with the user or developer rarely if ever needing to worry about object creation/deletion. If, for example, a residue is mutated from lysine to arginine, the old rotamer will disappear and the next call to RotaMgr.get_rotamers() will have the new one in the expected position.

  • For best performance, you should try to do most tasks using the plural chimerax.Collection calls, which loop over their constituent objects in C++. Looping over individual State objects is at least an order of magnitude slower. So, for example:

    angles = proper_dihedrals.angles

    ... is very fast, whereas:

    angles = []
for d in proper_dihedrals:
    angles.append(d.angle)

    is very slow, since it involves creating and deleting a Python ProperDihedral for every iteration of the loop.

Proper Dihedrals

ProperDihedralMgr

class chimerax.isolde.atomic.ProperDihedralMgr(session, c_pointer=None)

A session-level singleton managing all proper dihedrals (phi, psi, chi etc.). Rather than instantiating directly, it is best created/retrieved using session_extensions.get_proper_dihedral_mgr().

__init__(session, c_pointer=None)
add_dihedral_def(resname, dihedral_name, atom_names, external_mask=None)

Add a custom dihedral definition for tracking and restraint purposes.

Args:

  • resname: the 3-letter residue name

  • dihedral_name: a descriptive name for the dihedral (must be unique to the residue, but is otherwise free-form)

  • atom_names: a list of 4 atom names

  • external_mask: a binary mask: 0 for atoms to be found in the residue, 1 for atoms in a neighboring bonded residue

create_all_dihedrals(residues)

Create C++ objects for all known dihedrals in a set of residues. In general it is not necessary to do this, and preferable to allow them to simply be created as needed.

Args:
  • residues:

    • A chimerax.Residues instance

delete_dihedrals(dihedrals)

Delete all dihedrals in a ProperDihedrals. Note that this will not affect the constituent atoms in any way, and should not actually be necessary in most cases. Dihedrals are automatically deleted at the C++ level when their manager or any of their constituent atoms are deleted. The deleted dihedrals will be automatically re-created if/when needed.

get_all_dihedrals(residues)

Returns a ProperDihedrals containing all dihedrals that have been defined for the given residues. Any standard dihedrals (e.g. phi, psi, omega) will be created.

Args:
  • residues:

    • a chimerax.Residues instance

get_dihedral(residue, name, create=True)

Retrieve a ProperDihedral for the given residue and name, or None if no such dihedral exists.

Args:
  • residue:

    • A chimerax.Residue instance

  • name:

    • A string giving the lowercase name of the dihedral (e.g. ‘phi’, ‘omega’, ‘chi1’, etc.)

  • create (default: True):

    • If True, if the dihedral does not currently exist an attempt will be made to create it.

get_dihedrals(residues, name, create=True)

Returns a ProperDihedrals providing the named dihedral (where it exists) for every residue in residues. The resulting array will be in the same order as residues, but may be shorter.

Args:
  • residues:

    • A chimerax.Residues instance

  • name:

    • A string giving the lowercase name of the dihedral (e.g. ‘phi’, ‘omega’, ‘chi1’, etc.)

  • create (default = True):

    • If True, if any dihedral does not currently exist an attempt will be made to create it.

property num_mapped_dihedrals

Number of dihedrals currently being managed.

residues_have_dihedral(residues, name)

Returns a Numpy Boolean mask indicating which of the given residues contains a dihedral of the specified name with all required atoms present.

ProperDihedral

class chimerax.isolde.atomic.ProperDihedral(c_pointer)

A ProperDihedral is defined as a dihedral in which the four atoms are strictly bonded a1-a2-a3-a4.

INCLUDE_MAPS = 4

state flag

SCENE = 1

state flag

SESSION = 2

state flag

__init__(c_pointer)
property angle

Angle in radians. Read only.

property atoms

Atoms making up this dihedral. Read only.

property axial_bond

Bond forming the axis of this dihedral. Read-only

property center

Centroid of the coordinates for the dihedral atoms. Read only.

property cpp_pointer

Value that can be passed to C++ layer to be used as pointer (Python int)

property deleted

Has the C++ side been deleted?

property name

Name of this dihedral. Read only.

property residue

Residue this dihedral belongs to. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

ProperDihedrals

class chimerax.isolde.atomic.ProperDihedrals(c_pointers=None)
INCLUDE_MAPS = 4

state flag

SCENE = 1

state flag

SESSION = 2

state flag

__init__(c_pointers=None)
property angles

Returns the angle in radians for each dihedral. Read only.

property atoms

Returns a four-tuple of Atoms objects. For each dihedral, its constituent atoms are in the matching position in the four Atoms collections. Read only.

property axial_bonds

Returns a Bonds giving the axial bond for each dihedral. Read-only

property centers

Centroid of the coordinates for the dihedral atoms. Read only.

copy()

Shallow copy, since Collections are immutable.

filter(mask_or_indices)

Return a subset of the collection as a new collection.

Parameters

mask_or_indicesnumpy bool array (mask) or int array (indices)

Bool length must match the length of the collection and filters out items where the bool array is False.

hash()

Can be used for quickly determining if collections have the same elements in the same order. Objects are automatically deleted from the collection when the C++ object is deleted. So this hash value will not be valid if the collection changes. This is not the __hash__ special Python method and it is not supported to use collections as keys of dictionaries or elements of sets since they are mutable (deletions automatically remove items).

index(object)

Find the position of the first occurence of an object in a collection.

indices(objects)

Return int32 array indicating for each element in objects its index of the first occurence in the collection, or -1 if it does not occur in the collection.

instances(instantiate=True)

Returns a list of the Python instances. If ‘instantiate’ is False, then for those items that haven’t yet been instantiated, None will be returned.

intersect(objects)

Return a new collection that is the intersection with the objects Collection.

intersects(objects)

Whether this collection has any element in common with the objects Collection. Returns bool.

intersects_each(objects_list)

Check if each of serveral pointer arrays intersects this array. Return a boolean array of length equal to the length of objects_list.

mask(objects)

Return bool array indicating for each object in current set whether that object appears in the argument objects.

merge(objects)

Return a new collection combining this one with the objects Collection. All duplicates are removed.

property residues

Returns a Residues giving the parent residue of each dihedral. Read only

static restore_snapshot(session, data)

Create object using snapshot data.

subtract(objects)

Return a new collection subtracting the objects Collection from this one. All duplicates are removed. Currently does not preserve order

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

unique()

Return a new collection containing the unique elements from this one, preserving order.

Chiral Centres

ChiralMgr

class chimerax.isolde.atomic.ChiralMgr(session, c_pointer=None)

A session-level singleton managing all chiral centres. Rather than instantiating directly, it is best created/retrieved using session_extensions.get_chiral_mgr().

__init__(session, c_pointer=None)
add_chiral_def(residue_name, chiral_atom_name, s1_names, s2_names, s3_names, expected_angle, externals=[0, 0, 0])

Add a definition to the dictionary of known chiral centres. The definition will only be valid for the current session. All instances of the chiral centre will be automatically found and tracked.

Since chiral bonds can occur across residues, substituent atom names should be provided as lists of possible names.

Args:
  • residue_name:

    • the 3-letter name of the residue the centre is found in

  • chiral_atom_name:

    • the name of the central chiral atom

  • s1_names:

    • a list of potential names for the highest priority substituent

  • s2_names:

    • a list of potential names for the second substituent

  • s3_names:

    • a list of potential names for the third substituent

  • expected_angle:

    • the expected dihedral angle (in radians) for the chiral centre at equilibrium. While it is best to provide more accurate measures based on an energy-minimised model of your compound, fairly typical values are 0.6 for a (S) isomer and -0.6 for a (R) isomer. Note that chirality restraints only become active for deviations more than 15 degrees (0.26 radians), from the expected angle, relying on the forcefield parameterisation inside that range.

  • externals:

    • an array of three Boolean values, where True indicates that the corresponding atom should be outside the main atom’s residue.

delete_chirals(chirals)

Delete the C++ objects for the given ChiralCenters. Note that this only deletes the chirality information, not any atoms/bonds. In general it should not be necessary to use this method - creation and deletion is fully automatic.

get_chiral(atom, create=True)

Returns a ChiralCenter for the given atom if it is a known chiral atom. Returns None if the atom is achiral, no definition exists for the chiral centre, required substituent atoms are missing, or create is False and the c++ object has not previously been created.

Args:
  • atom:

    • a chimerax.Atom instance

  • create:

    • if True, an attempt will be made to create the chiral centre if it doesn’t already exist.

get_chirals(atoms, create=True)

Returns a ChiralCenters containing all known chiral centres in the given atoms.

Args:
  • atoms:

    • a chimerax.Atoms instance.

  • create:

    • if True, for every atom where a chiral definition exists but no ChiralCenter has been created, an attempt will be made to create it. Otherwise, only previously-created chirals will be returned.

ChiralCenter

class chimerax.isolde.atomic.ChiralCenter(c_pointer)

A chiral centre is an atom with four chemically distinct substituents, such that it cannot be overlaid with its mirror image by rotation and translation. Within ISOLDE, chiral centres are treated as improper dihedrals (that is, dihedrals for which the axis isn’t a real bond). Atom ordering within a ChiralCenter is defined with the central atom first, followed by the first three substituents in order of decreasing priority by standard Cahn-Ingold-Prelog rules. Typical tetrahedral centres will have dihedral angles in the vicinity of +/-35 degrees - S positive, R negative.

ChiralCenter instances are not created directly - they are generated as needed by ChiralMgr based on dictionary definitions.

INCLUDE_MAPS = 4

state flag

SCENE = 1

state flag

SESSION = 2

state flag

__init__(c_pointer)
property angle

Angle in radians. Read only.

property atoms

Atoms making up this chiral centre. Read only.

property center

Centroid of the coordinates for the atoms defining the chiral center. Read only.

property chiral_atom

The chiral atom. Read only.

property cpp_pointer

Value that can be passed to C++ layer to be used as pointer (Python int)

property deleted

Has the C++ side been deleted?

property deviation

The difference between the current dihedral angle and expected_angle. Read only.

property expected_angle

The equilibrium angle of the chiral dihedral in its correct isomeric state. Read only.

property residue

Residue this chiral centre belongs to. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

ChiralCenters

class chimerax.isolde.atomic.ChiralCenters(c_pointers=None)
INCLUDE_MAPS = 4

state flag

SCENE = 1

state flag

SESSION = 2

state flag

__init__(c_pointers=None)
property angles

Returns the angle in radians for each dihedral. Read only.

property atoms

Returns a four-tuple of Atoms objects. For each dihedral, its constituent atoms are in the matching position in the four Atoms collections. Read only.

property centers

Centroid of the coordinates for the atoms defining the chiral center. Read only.

property chiral_atoms

The chiral atoms. Read only.

copy()

Shallow copy, since Collections are immutable.

property deviations

The difference between each current dihedral angle and its expected_angle. Read only.

property expected_angles

The equilibrium angle of each chiral dihedral in its correct isomeric state. Read only.

filter(mask_or_indices)

Return a subset of the collection as a new collection.

Parameters

mask_or_indicesnumpy bool array (mask) or int array (indices)

Bool length must match the length of the collection and filters out items where the bool array is False.

hash()

Can be used for quickly determining if collections have the same elements in the same order. Objects are automatically deleted from the collection when the C++ object is deleted. So this hash value will not be valid if the collection changes. This is not the __hash__ special Python method and it is not supported to use collections as keys of dictionaries or elements of sets since they are mutable (deletions automatically remove items).

index(object)

Find the position of the first occurence of an object in a collection.

indices(objects)

Return int32 array indicating for each element in objects its index of the first occurence in the collection, or -1 if it does not occur in the collection.

instances(instantiate=True)

Returns a list of the Python instances. If ‘instantiate’ is False, then for those items that haven’t yet been instantiated, None will be returned.

intersect(objects)

Return a new collection that is the intersection with the objects Collection.

intersects(objects)

Whether this collection has any element in common with the objects Collection. Returns bool.

intersects_each(objects_list)

Check if each of serveral pointer arrays intersects this array. Return a boolean array of length equal to the length of objects_list.

mask(objects)

Return bool array indicating for each object in current set whether that object appears in the argument objects.

merge(objects)

Return a new collection combining this one with the objects Collection. All duplicates are removed.

property residues

Returns a Residues giving the parent residue of each dihedral. Read only

static restore_snapshot(session, data)

Create object using snapshot data.

subtract(objects)

Return a new collection subtracting the objects Collection from this one. All duplicates are removed. Currently does not preserve order

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

unique()

Return a new collection containing the unique elements from this one, preserving order.

Ramachandran validation

RamaMgr

class chimerax.isolde.atomic.RamaMgr(session, c_pointer=None)

Session-level singleton managing the Ramachandran scoring of protein residues. Rather than instantiating directly, it is best created/retrieved using session_extensions.get_ramachandran_mgr().

class RamaBin(value)

Enumerator for validation bins. Values match an enumerator in the C++ layer, so don’t change them unless you know exactly what you’re doing.

class RamaCase(value)

Enumerators for the different Ramachandran cases. These match an enumerator in the C++ layer, so don’t change them unless you know exactly what you’re doing.

__init__(session, c_pointer=None)
bin_scores(scores, cases)

Returns an array of integer values corresponding to the enumerator RamaMgr.RamaBin to bin the given Ramachandran scores into favoured, allowed, outlier and N/A. The input arrays are the product of validate().

Args:
  • scores:

    • an array of floating-point scores

  • cases:

    • a matching integer array defining the Ramachandran cases

cis(residues)

Returns a chimerax.Residues instance encompassing the subset of input residues whose peptide bonds are in the cis conformation.

color_cas_by_rama_score(ramas, hide_favored=False)

Colours the alpha carbon atoms by Ramachandran score.

Args:
  • ramas:
  • hide_favored:

    • if True, only the data for non-favoured residues will be returned.

property color_scale

Returns the current colour scale as a 4-tuple of (max, mid, min, n/a)

property cpp_pointer

Value that can be passed to C++ layer to be used as pointer (Python int)

property cutoffs

Returns a dict giving the allowed and outlier cutoffs for each Ramachandran case. Read only.

property deleted

Has the C++ side been deleted?

property dihedral_manager

Returns the session ProperDihedralMgr singleton.

get_ramas(residues)

Returns a Ramas with one Rama for each protein residue in the list. Non-protein residues will be skipped so the length of the result may be different from the input array, but the returned Ramas will be in the same order as the protein residues in the input.

Args:
  • residues:

    • a chimerax.Residues instance

interpolator_axes(rama_case)

Convenience function combining interpolator_axis_lengths() and interpolator_limits() to provide a tuple of arrays giving the axis values at each grid point.

Args:
  • rama_case:

    • integer value corresponding to the RamaCases enum

interpolator_axis_lengths(rama_case)

Retrieve the (phi,psi) axis dimensions of the RegularGridInterpolator object for a given Ramachandran case.

Args:
  • rama_case:

    • integer value corresponding to the RamaCases enum

interpolator_dim(rama_case)

Retrieve the number of dimensions in the RegularGridInterpolator object for a given Ramachandran case. Should always return 2.

Args:
  • rama_case:

    • integer value corresponding to the RamaCases enum

interpolator_limits(rama_case)

Returns a (minimum_values, maximum_values) tuple giving the limiting values for each axis in the RegularGridInterpolator object for a given Ramachandran case.

Args:
  • rama_case:

    • integer value corresponding to the RamaCases enum

interpolator_values(rama_case)

Returns a multidimensional array containing the contour data for a given Ramachandran case.

Args:
  • rama_case:

    • integer value corresponding to the RamaCases enum

non_favored(residues)

Returns a chimerax.Residues instance encompassing the subset of input residues that are outside favored Ramachandran space.

Args:
  • residues:

    • a chimerax.Residues instance

outliers(residues)

Returns a chimerax.Residues instance encompassing the subset of input residues that are Ramachandran outliers.

Args:
  • residues:

    • a chimerax.Residues instance

rama_cases(residues)

Returns an array of integer values corresponding to the Ramachandran case enumerator RamaMgr.RamaCases.

Args:
  • residues:

    • A chimerax.Residues instance

rama_colors(ramas)

Returns a nx4 uint8 array giving a color for each rama corresponding to the current colormap.

Args:
  • ramas:
set_color_scale(max_c, mid_c, min_c, na_c)

Define a custom colour scale for visualisation of Ramachandran scores. All arguments are iterables of four integers providing (red, green, blue, alpha) in the range (0..255).

Args:
  • max_c:

    • colour associated with the maximum (most favourable) score

  • mid_c:

    • colour at the favoured/allowed cutoff

  • min_c:

    • colour at the allowed/outlier cutoff. All scores below the outlier cutoff will have this colour

  • na_c:

    • colour to associate with residues that don’t have Ramachandran scores (e.g. N/C termini)

set_default_colors()

Set the colours for visualisation of scores back to their defaults.

set_default_cutoffs()

Reset the Ramachandran cutoffs to default values.

twisted(residues)

Returns a list of (chimerax.Residue, angle) 2-tuples giving the subset of input residues whose peptide bonds are twisted more than 30 degrees from planar.

validate(residues_or_ramas)

Returns an 2-tuple containing an array of Ramachandran scores and an array of case enum values for a set of residues or ramas. Residues lacking either phi or psi will have a score of -1.

Args:

  • residues_or_ramas: either a chimerax.Residues or Ramas instance

Rama

class chimerax.isolde.atomic.Rama(c_pointer)
__init__(c_pointer)
property angles

The omega, phi and psi angles for this residue in radians. Read only.

property atoms

Returns an unsorted Atoms object encompassing all atoms in phi, psi and omega (if present)

property ca_atom

The alpha carbon chimerax.Atom of the amino acid residue. Read only.

property case

A value representing the Ramachandran case for this residue, matching the case definitions in RamaMgr.RamaCase. Read only.

property center

Returns centroid of the defining phi, psi and omega dihedrals. Read only.

property cpp_pointer

Value that can be passed to C++ layer to be used as pointer (Python int)

property deleted

Has the C++ side been deleted?

property omega_dihedral

Returns a ProperDihedral instance pointing to the omega (peptide bond) dihedral for this residue, or None if there is no preceding residue.

property phi_dihedral

Returns a ProperDihedral instance pointing to the phi dihedral for this residue, or None if there is no preceding residue.

property phipsi

The phi and psi angles for this residue in radians. Read only.

property psi_dihedral

Returns a ProperDihedral instance pointing to the psi dihedral for this residue, or None if there is no following residue.

property residue

The chimerax.Residue to which this Rama belongs. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

property score

The score of this residue on the MolProbity Ramachandran contours. Read only.

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

property valid

True if this residue has all three of omega, phi and psi. Read only.

property visible

True if the alpha carbon of this residue is visible. Read only.

property visible_ignoring_ribbon

True if the only thing hiding the alpha carbon is the ribbon display. Read only.

Ramas

class chimerax.isolde.atomic.Ramas(c_pointers=None)
INCLUDE_MAPS = 4

state flag

SCENE = 1

state flag

SESSION = 2

state flag

__init__(c_pointers=None)
property angles

The omega, phi and psi angles for each residue in radians. Read only.

property atoms

Returns an unsorted Atoms object encompassing all atoms in phi, psi and omega (if present).

property ca_atoms

Returns a chimerax.Atoms instance giving the alpha carbon of each amino acid residue. Read only.

property cases

Values representing the Ramachandran case for these residues, matching the case definitions in RamaMgr.RamaCase. Read only.

property centers

Returns the centroid of the defining phi, psi and omega dihedrals for each residue. Read only.

copy()

Shallow copy, since Collections are immutable.

filter(mask_or_indices)

Return a subset of the collection as a new collection.

Parameters

mask_or_indicesnumpy bool array (mask) or int array (indices)

Bool length must match the length of the collection and filters out items where the bool array is False.

hash()

Can be used for quickly determining if collections have the same elements in the same order. Objects are automatically deleted from the collection when the C++ object is deleted. So this hash value will not be valid if the collection changes. This is not the __hash__ special Python method and it is not supported to use collections as keys of dictionaries or elements of sets since they are mutable (deletions automatically remove items).

index(object)

Find the position of the first occurence of an object in a collection.

indices(objects)

Return int32 array indicating for each element in objects its index of the first occurence in the collection, or -1 if it does not occur in the collection.

instances(instantiate=True)

Returns a list of the Python instances. If ‘instantiate’ is False, then for those items that haven’t yet been instantiated, None will be returned.

intersect(objects)

Return a new collection that is the intersection with the objects Collection.

intersects(objects)

Whether this collection has any element in common with the objects Collection. Returns bool.

intersects_each(objects_list)

Check if each of serveral pointer arrays intersects this array. Return a boolean array of length equal to the length of objects_list.

mask(objects)

Return bool array indicating for each object in current set whether that object appears in the argument objects.

merge(objects)

Return a new collection combining this one with the objects Collection. All duplicates are removed.

property omega_dihedrals

Returns a ProperDihedrals instance pointing to the omega (peptide bond) dihedral for each residue. Note that some residues will not have omega dihedrals, so the output array may be shorter than the Ramas instance.

property phi_dihedrals

Returns a ProperDihedrals instance pointing to the phi dihedral for each residue. Note that some residues will not have phi dihedrals, so the output array may be shorter than the Ramas instance.

property phipsis

The phi and psi angles for each residue in radians. Read only.

property psi_dihedrals

Returns a ProperDihedrals instance pointing to the psi dihedral for each residue. Note that some residues will not have psi dihedrals, so the output array may be shorter than the Ramas instance.

property residues

Returns a chimerax.Residues instance giving the residue to which each Rama belongs. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

property scores

The score of each residue on the MolProbity Ramachandran contours. Read only.

subtract(objects)

Return a new collection subtracting the objects Collection from this one. All duplicates are removed. Currently does not preserve order

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

unique()

Return a new collection containing the unique elements from this one, preserving order.

property valids

True for each residue that has all three of omega, phi and psi. Read only.

property visibles

True for each residue whose alpha carbon is visible. Read only.

property visibles_ignoring_ribbon

True if the only thing hiding the alpha carbon is the ribbon display. Read only.

Amino acid rotamers

RotaMgr

class chimerax.isolde.atomic.RotaMgr(session, c_pointer=None)

Session-level singleton managing rotamers and their scoring. Rather than instantiating directly, it is best created/retrieved using session_extensions.get_rotamer_mgr().

class RotaBin(value)

Enumerator for validation bins. Values match an enumerator in the C++ layer, so don’t change them unless you know exactly what you’re doing.

__init__(session, c_pointer=None)
property color_scale

Returns the current colour scale as a 3-tuple of (max, mid, min)

property cpp_pointer

Value that can be passed to C++ layer to be used as pointer (Python int)

property cutoffs

Gives the current (allowed, outlier) P-value cutoffs

property deleted

Has the C++ side been deleted?

get_rotamer(residue)

Create/retrieve the Rotamer object for a given residue

Args:
  • residue:

    • a chimerax.Residue instance

get_rotamers(residues)

Return a Rotamers instance containing all valid rotamers in the selection.

Args:
  • residues:

    • a chimerax.Residues instance

non_favored_rotamers(rotamers)

Returns a 2-tuple containing only the rotamers in non-favoured conformations, and their current scores.

Args:
outliers(rotamers)

Returns a 2-tuple containing only the rotamers in outlying conformations, and their current scores.

Args:
set_color_scale(max_c, mid_c, min_c)

Define a custom colour scale for visualisation of rotamer scores. All arguments are iterables of four integers providing (red, green, blue, alpha) in the range (0..255).

Args:
  • max_c:

    • colour associated with the maximum (most favourable) score

  • mid_c:

    • colour at the favoured/allowed cutoff

  • min_c:

    • colour at the allowed/outlier cutoff. All scores below the outlier cutoff will have this colour

set_default_colors()

Reset the colour map for visualisation of rotamer validation back to the stored default colours.

set_default_cutoffs()

Reset the rotamer P-value cutoffs to default values

validate_residues(residues)

Returns an array of P-values for the current conformations of all rotameric protein residues in the input. Non-rotameric residues will receive a score of -1.

Args:
  • residues:

    • a chimerax.Residues instance

validate_rotamers(rotamers)

Returns an array of P-values for the current conformations of the given rotamers.

Args:
validate_scale_and_color_rotamers(rotamers, max_scale=2.0, non_favored_only=True, visible_only=True)

Used by RotamerAnnotator for visualising rotamer validation.

Args:
  • rotamers:
  • max_scale:

    • size limit when scaling indicators by outlier severity

  • non_favored_only:

    • if True, the return arrays will be limited to only those rotamers outside of favoured conformations

  • visible_only:

    • if True, non-visible residues will be excluded from analysis and return

Returns:

  • A Rotamers instance matching the filtering criteria

  • An array of scale factors (one per rotamer)

  • An array of colours (one per rotamer)

Rotamer

class chimerax.isolde.atomic.Rotamer(c_pointer)
__init__(c_pointer)
property angles

Returns an array giving the current chi angles (chi1, chi2, …) for this rotamer.

property atoms

Returns an unsorted Atoms object containing all atoms making up this residue’s chi dihedrals

property ca_cb_bond

The “stem” chimerax.Bond of this rotamer. Read only.

property center

Returns mid-point between the CA and CB atoms. Read only.

property chi_dihedrals

Returns a ProperDihedrals giving the chi dihedrals for this rotamer, in order (chi1, chi2, …)

property cpp_pointer

Value that can be passed to C++ layer to be used as pointer (Python int)

property deleted

Has the C++ side been deleted?

get_target(index)

For each rotamer type, RotaMgr stores a set of ideal rotamer targets, based upon the Ultimate Rotamer Library [Hintze et al]_. These are indexed in decreasing order of expected frequency. The number of available target definitions is available from num_targets. The target definition is returned as a dict containing the name, expected frequency, ideal angles and their estimated standard deviations.

moving_atoms(chi_index)

Returns the set of atoms moved by rotating around the given chi dihedral.

property nearest_target

Returns the definition for the nearest ideal rotamer by minimising the sum of differences between the current and target angles. Adds an extra entry [‘Z scores’] to the returned dict giving the Z score for abs(angle-target) for each chi dihedral.

property num_chi_dihedrals

Number of dihedrals defining this rotamer. Read only.

property num_targets

Number of available target conformations. Read only.

property residue

chimerax.Residue this rotamer belongs to. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

property score

P-value for the current conformation of this rotamer. Read only.

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

property visible

True if the CA-CB bond of the rotamer is visible. Read only.

Rotamers

class chimerax.isolde.atomic.Rotamers(c_pointers=None)
INCLUDE_MAPS = 4

state flag

SCENE = 1

state flag

SESSION = 2

state flag

__init__(c_pointers=None)
property atoms

Returns an unsorted Atoms object encompassing all atoms in chi dihedrals. Read only.

property ca_cb_bonds

The “stem” chimerax.Bond of this rotamer. Read only.

property centers

Returns mid-point between the CA and CB atoms for each rotamer. Read only.

copy()

Shallow copy, since Collections are immutable.

filter(mask_or_indices)

Return a subset of the collection as a new collection.

Parameters

mask_or_indicesnumpy bool array (mask) or int array (indices)

Bool length must match the length of the collection and filters out items where the bool array is False.

hash()

Can be used for quickly determining if collections have the same elements in the same order. Objects are automatically deleted from the collection when the C++ object is deleted. So this hash value will not be valid if the collection changes. This is not the __hash__ special Python method and it is not supported to use collections as keys of dictionaries or elements of sets since they are mutable (deletions automatically remove items).

index(object)

Find the position of the first occurence of an object in a collection.

indices(objects)

Return int32 array indicating for each element in objects its index of the first occurence in the collection, or -1 if it does not occur in the collection.

instances(instantiate=True)

Returns a list of the Python instances. If ‘instantiate’ is False, then for those items that haven’t yet been instantiated, None will be returned.

intersect(objects)

Return a new collection that is the intersection with the objects Collection.

intersects(objects)

Whether this collection has any element in common with the objects Collection. Returns bool.

intersects_each(objects_list)

Check if each of serveral pointer arrays intersects this array. Return a boolean array of length equal to the length of objects_list.

mask(objects)

Return bool array indicating for each object in current set whether that object appears in the argument objects.

merge(objects)

Return a new collection combining this one with the objects Collection. All duplicates are removed.

property residues

chimerax.Residue this rotamer belongs to. Read only.

static restore_snapshot(session, data)

Create object using snapshot data.

property scores

P-value for the current conformation of this rotamer. Read only.

subtract(objects)

Return a new collection subtracting the objects Collection from this one. All duplicates are removed. Currently does not preserve order

take_snapshot(session, flags)

Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

unique()

Return a new collection containing the unique elements from this one, preserving order.

property visibles

True for each rotamer whose CA-CB bond is visible