1 2.. image:: https://travis-ci.org/charnley/rmsd.svg?branch=master 3 :target: https://travis-ci.org/charnley/rmsd 4 5 6.. image:: https://badge.fury.io/py/rmsd.svg 7 :target: https://badge.fury.io/py/rmsd 8 9 10Calculate Root-mean-square deviation (RMSD) of Two Molecules Using Rotation 11=========================================================================== 12 13The root-mean-square deviation (RMSD) is calculated, using Kabsch algorithm 14(1976) or Quaternion algorithm (1991) for rotation, between two Cartesian 15coordinates in either ``.xyz`` or ``.pdb`` format, resulting in the minimal 16RMSD. 17 18For more information please read RMSD_ and `Kabsch algorithm`_. 19 20.. _RMSD: http://en.wikipedia.org/wiki/Root-mean-square_deviation 21.. _Kabsch algorithm: http://en.wikipedia.org/wiki/Kabsch_algorithm 22 23Motivation 24---------- 25 26You have molecule A and B and want to calculate the structural difference 27between those two. If you just calculate the RMSD_ straight-forward you might 28get a too big of a value as seen below. You would need to first recenter the 29two molecules and then rotate them unto each other to get the true minimal 30RMSD. This is what this script does. 31 32========== =========== ========== 33No Changes Re-centered Rotated 34---------- ----------- ---------- 35|begin| |translate| |rotate| 36========== =========== ========== 37RMSD 2.50 RMSD 1.07 RMSD 0.25 38========== =========== ========== 39 40.. |begin| image:: https://raw.githubusercontent.com/charnley/rmsd/master/img/plot_beginning.png 41.. |translate| image:: https://raw.githubusercontent.com/charnley/rmsd/master/img/plot_translated.png 42.. |rotate| image:: https://raw.githubusercontent.com/charnley/rmsd/master/img/plot_rotated.png 43 44 45Citation 46-------- 47 48- **Implementation**: 49 Calculate Root-mean-square deviation (RMSD) of Two Molecules Using Rotation, GitHub, 50 http://github.com/charnley/rmsd, <git commit hash or version number> 51 52- **Kabsch algorithm**: 53 Kabsch W., 1976, 54 A solution for the best rotation to relate two sets of vectors, 55 Acta Crystallographica, A32:922-923, 56 doi: http://dx.doi.org/10.1107/S0567739476001873 57 58- **Quaternion algorithm**: 59 Michael W. Walker and Lejun Shao and Richard A. Volz, 1991, 60 Estimating 3-D location parameters using dual number quaternions, CVGIP: Image Understanding, 54:358-367, 61 doi: http://dx.doi.org/10.1016/1049-9660(91)90036-o 62 63Please cite this project when using it for scientific publications. 64 65 66Installation 67------------ 68 69Easiest is to get the program vis PyPi under the package name ``rmsd``, 70 71.. code-block:: bash 72 73 pip install rmsd 74 75 76or download the project from GitHub via 77 78.. code-block:: bash 79 80 git clone https://github.com/charnley/rmsd 81 82 83There is only one Python file, so you can also download `calculate_rmsd.py` and 84put it in your bin folder. 85 86.. code-block:: bash 87 88 wget -O calculate_rmsd https://raw.githubusercontent.com/charnley/rmsd/master/rmsd/calculate_rmsd.py 89 chmod +x calculate_rmsd 90 91Usage examples 92-------------- 93 94Use ``calculate_rmsd --help`` to see all the features. Usage is pretty straight 95forward, call ``calculate_rmsd`` with two structures in either ``.xyz`` or 96``.pdb``. In this example Ethane has the exact same structure, but is 97translated in space, so the RMSD should be zero. 98 99.. code-block:: bash 100 101 calculate_rmsd tests/ethane.xyz tests/ethane_translate.xyz 102 103It is also possible to ignore all hydrogens (useful for larger molecules where 104hydrogens move around indistinguishable) and print the rotated structure for 105visual comparison. The output will be in XYZ format. 106 107.. code-block:: bash 108 109 calculate_rmsd --no-hydrogen --print tests/ethane.xyz tests/ethane_mini.xyz 110 111If the atoms are scrambled and not aligned you can use the ``--reorder`` 112argument which will align the atoms from structure B unto A. Use 113``--reorder-method`` to select what method for reordering. Choose between 114Hungarian_ (default), distance (very approximate) and brute force (slow). 115 116.. _Hungarian: https://en.wikipedia.org/wiki/Hungarian_algorithm 117 118.. code-block:: bash 119 120 calculate_rmsd --reorder tests/water_16.xyz tests/water_16_idx.xyz 121 122 123It is also possible to use RMSD as a library in other scripts, see `example.py` for example usage. 124 125 126Problems? 127--------- 128 129Submit issues or pull requests on GitHub. 130 131 132Contributions 133------------- 134 135Please note that we are using ``black`` with line length of 79. Easiest way to 136abide to the code standard is to install the following packages. 137 138.. code-block:: bash 139 140 pip install black flake8 autoflake isort pytest 141 142and 143 144.. code-block:: bash 145 146 make format test lint 147 148to auto-format and test the code. 149 150 151