# Core Dihedral Classes

- General Principles
- Proper Dihedrals
  - Proper_Dihedral_Mgr
  - Proper_Dihedral
  - Proper_Dihedrals
- Chiral Centres
  - Chiral_Mgr
  - Chiral_Center
  - Chiral_Centers
- Ramachandran validation
  - Rama_Mgr
  - Rama
  - Ramas
- Amino acid rotamers
  - Rota_Mgr
  - Rotamer
  - Rotamers

## 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 vital to ISOLDE’s success.

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:

> - `Proper_Dihedral_Mgr` exists as a single instance per session and is responsible for creation, deletion and retrieval of C++ `Proper_Dihedral` objects. The preferred way to find the manager instance is to use `session_extensions.get_proper_dihedral_manager()`. This will create the manager if it doesn’t yet exist, or simply retrieve it if it does.
> - `Proper_Dihedral` is built on the `chimerax.State` framework and behaves similarly to e.g. `chimerax.Atom`.
> - `Proper_Dihedrals` is built on the `chimerax.Collection` framework and behaves similarly to e.g. `chimerax.Atoms`.

Some general key points:

  - In general, the C++ `Proper_Dihedral` objects are only created when needed. `Proper_Dihedral_Mgr.get_dihedral()` 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++ `Proper_Dihedral` is deleted, the dihedral will be deleted and automatically removed from any `Proper_Dihedrals` instances. Any corresponding Python `Proper_Dihedral` 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 `Rota_Mgr.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 `Proper_Dihedral` for every iteration of the loop.

## Proper Dihedrals

### Proper_Dihedral_Mgr

> class `chimerax.isolde.atomic.``Proper_Dihedral_Mgr`(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)

>     Initialize self. See help(type(self)) for accurate signature.

>   `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 `Proper_Dihedrals`. 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 `Proper_Dihedrals` 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 `Proper_Dihedral` 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 `Proper_Dihedrals` 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.
>   `num_mapped_dihedrals`

>     Number of dihedrals currently being managed.

### Proper_Dihedral

> class `chimerax.isolde.atomic.``Proper_Dihedral`(c_pointer)

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

>   `__init__`(c_pointer)

>     Initialize self. See help(type(self)) for accurate signature.

>   `angle`

>     Angle in radians. Read only.

>   `atoms`

>     Atoms making up this dihedral. Read only.

>   `axial_bond`

>     Bond forming the axis of this dihedral. Read-only

>   `cpp_pointer`

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

>   `deleted`

>     Has the C++ side been deleted?

>   `name`

>     Name of this dihedral. Read only.

>   `residue`

>     Residue this dihedral belongs to. Read only.

>   classmethod `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.

### Proper_Dihedrals

> class `chimerax.isolde.atomic.``Proper_Dihedrals`(c_pointers=None)
>   `__init__`(c_pointers=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `angles`

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

>   `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.

>   `axial_bonds`

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

>   `copy`()

>     Shallow copy, since Collections are immutable.

>   `filter`(mask_or_indices)

>     Return a subset of the collection as a new collection.

>     mask_or_indices : numpy 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.

>   `residues`

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

>   classmethod `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

### Chiral_Mgr

> class `chimerax.isolde.atomic.``Chiral_Mgr`(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)

>     Initialize self. See help(type(self)) for accurate signature.

>   `add_chiral_def`(residue_name, chiral_atom_name, s1_names, s2_names, s3_names, expected_angle)

>     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.
>   `delete_chirals`(chirals)

>     Delete the C++ objects for the given `Chiral_Centers`. 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 `Chiral_Center` 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 `Chiral_Centers` 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 `Chiral_Center` has been created, an attempt will be made to create it. Otherwise, only previously-created chirals will be returned.

### Chiral_Center

> class `chimerax.isolde.atomic.``Chiral_Center`(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 `Chiral_Center` 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.

>   `Chiral_Center` instances are not created directly - they are generated as needed by `Chiral_Mgr` based on dictionary definitions.

>   `__init__`(c_pointer)

>     Initialize self. See help(type(self)) for accurate signature.

>   `angle`

>     Angle in radians. Read only.

>   `atoms`

>     Atoms making up this chiral centre. Read only.

>   `chiral_atom`

>     The chiral atom. Read only.

>   `cpp_pointer`

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

>   `deleted`

>     Has the C++ side been deleted?

>   `deviation`

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

>   `expected_angle`

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

>   `residue`

>     Residue this chiral centre belongs to. Read only.

>   classmethod `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.

### Chiral_Centers

> class `chimerax.isolde.atomic.``Chiral_Centers`(c_pointers=None)
>   `__init__`(c_pointers=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `angles`

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

>   `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.

>   `chiral_atoms`

>     The chiral atoms. Read only.

>   `copy`()

>     Shallow copy, since Collections are immutable.

>   `deviations`

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

>   `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.

>     mask_or_indices : numpy 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.

>   `residues`

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

>   classmethod `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

### Rama_Mgr

> class `chimerax.isolde.atomic.``Rama_Mgr`(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 `Rama_Bin`

>     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 `Rama_Case`

>     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)

>     Initialize self. See help(type(self)) for accurate signature.

>   `bin_scores`(scores, cases)

>     Returns an array of integer values corresponding to the enumerator `Rama_Mgr.Rama_Bin` 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:
>           - a `Ramas` instance
>       - hide_favored:
>           - if True, only the data for non-favoured residues will be returned.
>   `color_scale`

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

>   `cpp_pointer`

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

>   `cutoffs`

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

>   `deleted`

>     Has the C++ side been deleted?

>   `dihedral_manager`

>     Returns the session `Proper_Dihedral_Mgr` 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 `Rama_Cases` 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 `Rama_Cases` 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 `Rama_Cases` 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 `Rama_Cases` 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 `Rama_Cases` enum
>   `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 `Rama_Mgr.Rama_Cases`.

>     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:
>           - a `Ramas` instance
>   `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)

>     Initialize self. See help(type(self)) for accurate signature.

>   `angles`

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

>   `ca_atom`

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

>   `case`

>     A value representing the Ramachandran case for this residue, matching the case definitions in `Rama_Mgr.Rama_Case`. Read only.

>   `cpp_pointer`

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

>   `deleted`

>     Has the C++ side been deleted?

>   `omega_dihedral`

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

>   `phi_dihedral`

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

>   `phipsi`

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

>   `psi_dihedral`

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

>   `residue`

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

>   `score`

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

>   `valid`

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

>   `visible`

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

>   `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)
>   `__init__`(c_pointers=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `angles`

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

>   `ca_atoms`

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

>   `cases`

>     Values representing the Ramachandran case for these residues, matching the case definitions in `Rama_Mgr.Rama_Case`. Read only.

>   `copy`()

>     Shallow copy, since Collections are immutable.

>   `filter`(mask_or_indices)

>     Return a subset of the collection as a new collection.

>     mask_or_indices : numpy 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.

>   `omega_dihedrals`

>     Returns a `Proper_Dihedrals` 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.

>   `phi_dihedrals`

>     Returns a `Proper_Dihedrals` 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.

>   `phipsis`

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

>   `psi_dihedrals`

>     Returns a `Proper_Dihedrals` 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.

>   `residues`

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

>   classmethod `restore_snapshot`(session, data)

>     Create object using snapshot data.

>   `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.

>   `valids`

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

>   `visibles`

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

>   `visibles_ignoring_ribbon`

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

## Amino acid rotamers

### Rota_Mgr

> class `chimerax.isolde.atomic.``Rota_Mgr`(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 `Rota_Bin`

>     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)

>     Initialize self. See help(type(self)) for accurate signature.

>   `color_scale`

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

>   `cutoffs`

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

>   `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:
>       - rotamers:
>           - a `Rotamers` instance
>   `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:
>       - rotamers:
>           - a `Rotamers` instance
>   `validate_scale_and_color_rotamers`(rotamers, max_scale=2.0, non_favored_only=True, visible_only=True)

>     Used by `Rotamer_Annotator` for visualising rotamer validation.

>     Args:
>       - rotamers:
>           - a `Rotamers` instance
>       - 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)

>     Initialize self. See help(type(self)) for accurate signature.

>   `angles`

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

>   `ca_cb_bond`

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

>   `chi_dihedrals`

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

>   `cpp_pointer`

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

>   `deleted`

>     Has the C++ side been deleted?

>   `get_target`(index)

>     For each rotamer type, `Rota_Mgr` 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.

>   `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.

>   `num_chi_dihedrals`

>     Number of dihedrals defining this rotamer. Read only.

>   `num_targets`

>     Number of available target conformations. Read only.

>   `residue`

>     `chimerax.Residue` this rotamer belongs to. Read only.

>   `score`

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

>   `visible`

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

### Rotamers

> class `chimerax.isolde.atomic.``Rotamers`(c_pointers=None)
>   `__init__`(c_pointers=None)

>     Initialize self. See help(type(self)) for accurate signature.

>   `ca_cb_bonds`

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

>   `copy`()

>     Shallow copy, since Collections are immutable.

>   `filter`(mask_or_indices)

>     Return a subset of the collection as a new collection.

>     mask_or_indices : numpy 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.

>   `residues`

>     `chimerax.Residue` this rotamer belongs to. Read only.

>   classmethod `restore_snapshot`(session, data)

>     Create object using snapshot data.

>   `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.

>   `visibles`

>     True for each rotamer whose CA-CB bond is visible