# Live Structure Validation

- General Principles
  - Rama_Annotator
  - Rotamer_Annotator

## General Principles

One of the core design principles underlying ISOLDE is the need for real-time, continuous and visually-clear feedback. When you are working on a structure with thousands of residues, having to stop and generate a table or plot to tell you how you did, then navigate back to each outlier and attempt to fix it before repeating the process is simply too slow, and leads people to give up while their structure is still far from perfect. The aim in ISOLDE is to instead continually show you how you’re going right now by directly marking up problems where and when they occur, telling you directly whether your manipulations are making things better or worse.

### Rama_Annotator

class `chimerax.isolde.validation.``Rama_Annotator`(atomic_structure, hide_favored=False, ignore_ribbon_hides=True)

  Handles the task of real-time Ramachandran validation for a single `chimerax.AtomicStructure` and visualisation of the results. Results are displayed as coloured spheres overlaying the alpha carbon atoms, shading from (by default) green through yellow to hot pink as the Ramachandran score goes from favoured through allowed to outlier.

  Designed to be mostly “fire-and-forget”:

      ra = Rama_Annotator(atomic_structure)

  adds the :py:class`Rama_Annotator` as a child model to atomic_structure and will update its validation drawing every time the coordinates change. Alternatively:

      from chimerax.isolde import session_extensions as sx
      ra = sx.get_rama_annotator(atomic_model)

  creates the `Rama_Annotator` if it doesn’t exist, or returns the existing one if it does.

  Turning off the display of the `Rama_Annotator` model (e.g. via the ChimeraX Model Panel) temporarily turns off automatic validation, which will restart when display is turned back on.

  `__init__`(atomic_structure, hide_favored=False, ignore_ribbon_hides=True)

    Create the validator object, and add it as a child model to the target structure.

    Args:
      - atomic_structure:
          - a `ChimeraX.AtomicStructure` instance
      - hide_favored:
          - if True, indicators will only appear for non-favored residues. (this can be changed at any time later)
      - ignore_ribbon_hides:
          - if True, the `chimerax.HIDE_RIBBON` bit will be ignored when deciding when to display a particular annotation. This is needed because the default ChimeraX ribbon representation hides the CA for any residue whose sidechain is un-displayed or missing (meaning that the glycine CA is always hidden).
  `ca_radius`

    Sets the radius (in Angstroms) of the sphere overlaying each CA atom.

  `color_scale`

    Returns a 3-tuple of (r,g,b,a) arrays defining the current colour scale.

  `delete`()

    Delete this model.

  `display`

    Show/hide the validation markup (automatic validation will pause while hidden).

  `hide_favored`

    Show annotations for favoured rotamers, or just non-favoured/outliers?

  `restrict_to_selected_residues`(residues)

    Restrict validation to a defined set of residues. Use `track_whole_model` = True to once again cover all residues.

    Args:
      - residues:
          - A `chimerax.Residues` instance
  `track_whole_model`

    Tell the validator to track/annotate all protein residues in the model (the default starting state).

### Rotamer_Annotator

class `chimerax.isolde.validation.``Rotamer_Annotator`(atomic_structure)

  Handles the task of real-time validation of rotamers for a single `chimerax.AtomicStructure` and drawing of 3D indicators of their current scores. Designed to be mostly “fire-and-forget”:

      ra = Rotamer_Annotator(atomic_structure)

  adds the :py:class`Rotamer_Annotator` as a child model to atomic_structure and will update its validation drawing every time the coordinates change. Alternatively:

      from chimerax.isolde import session_extensions as sx
      ra = sx.get_rota_annotator(atomic_model)

  creates the `Rotamer_Annotator` if it doesn’t exist, or returns the existing one if it does.

  Each rotamer score visualised as a 3D exclamation mark surrounded by a spiral, which changes colour and grows with outlier severity. By default only non-favoured rotamers are flagged.

  Turning off the display of the `Rotamer_Annotator` model (e.g. via the ChimeraX Model Panel) temporarily turns off automatic validation, which will restart when display is turned back on.

  `__init__`(atomic_structure)

    Create the validator object, and add it as a child model to the target structure.

    Args:
      - atomic_structure:
          - a `ChimeraX.AtomicStructure` instance
  `color_scale`

    Returns a 3-tuple of (r,g,b,a) arrays defining the current colour scale.

  `delete`()

    Delete this model.

  `display`

    Show/hide the validation markup (automatic validation will pause while hidden).

  `hide_favored`

    Show annotations for favoured rotamers, or just non-favoured/outliers?

  `restrict_to_selected_residues`(residues)

    Restrict validation to a defined set of residues. Use `track_whole_model` = True to once again cover all residues.

    Args:
      - residues:
          - A `chimerax.Residues` instance
  `track_whole_model`

    Tell the validator to track/annotate all rotameric residues in the model (the default starting state).