Introduction of bond-derived axes for residue level rotation/united atom level translation

[ioanaapapa]

Summary

This PR addresses issues #26, #279, and #370 and introduces custom axes for residue level rotations/UA level translations.

Changes

• DataContainer at the residue level now consists of the residue of interest alongside its neighbours. The residue_group data container contains two residues for the first and last residue (residue + the one neighbours), or three residues otherwise (residue + 2 neighbours).

• When selection does not start with first residue in topology, indexing of residue in topology, i.e. index with respect to first residue in topology, is accounted for.

• Translation axes at UA level for molecules with multiple residues, are calculated the same way as residue level rotation axes.

• New function get_chain in axes.py that identifies the shortest heavy-atom path between two heavy atoms in a given residue and returns only the heavy atoms in between. This is used to define the backbone of a residue as the shortest path between heavy atoms bonded to neighbouring residues. For the first residue, it uses the first atom in the residue as the starting point, and for the last residue, it uses the last heavy atom with only one bond to another heavy atom as the ending point.
  For a protein, it finds the N,CA,C atoms. (+ O in the case of the last residue.) as the backbone, and returns the CA (+C) atom(s) as the in between atoms.
  For a DNA molecule, it finds the chain shown in purple.

• New function get_custom_residue_moment_of_inertia to calculate residue MOI in the coordinate frame of the custom rotation axes.

• New function get_residue_custom_axes which computes the coordinate frame for a residue based on the two edge atoms (heavy atoms linearly bonded to neighbouring atoms) and centre of geometry of backbone atoms in between the edges.

• Unit tests in test_axes.py and test_covariance_node.py were adapted to accommodate new residue axes and residue groups.
• Regression baselines were updated to account for changes.
• New unit tests have been added.
• Text in the Vibrational Entropy subsection of the Multiscale Cell Correlation Theory section of the documentation has been changed to reflect changes.

Impact

• Closes united atom translational axes #26, [Feature]: Bonded Axes for residues #279 and [Feature]: Tests for new residue level custom axes #370.
• UA translation axes always match residue rotation axes. This should mean that translations and rotations at the residue level are correctly discarded when calculating UA transvibrational entropy.
• Center of residue is now located along backbone. The backbone can be identified for any molecule with bonded residues. This leads to higher entropy values than using the residue centre of mass as before with principal axes.
• Entropy values are similar to values using the NCC axes. New axes will be equivalent to NCC for a protein, with the exception of the last residue.

• The coordinate system is general and suitable for molecules such as DNA.

Future work

A coordinate system that does not depend on indices will be chosen for terminal residues.
Branched residues will be dealt with.
If we decide on an external definition for residue axes, there might be slight changes but they would be smaller changes than this.

[harryswift01]

Thanks for putting this together. I’ve just had an initial look through the updated diff, and it seems that some of the newer functionality currently on main may have been overwritten when the axes changes were reapplied. For example, get_residue_axes_from_topology and some of the related performance improvements no longer appear to be included. I think the easiest way to resolve this may be to restore the affected files to their current versions on main, and then apply the specific changes needed for the new axes functionality on top of those. It may also be possible to make use of some of the newer functionality while doing this, which should help retain the recent performance improvements alongside the new changes. Hope this makes sense. I’m happy to help identify which parts need to be retained or work through the changes together if that would be useful.