icdZddlZddlmZddlZddlZddl m Z m Z ddl m Z ddlmZmZGdde ZGdd e ZGd d eZdS) uDihedral angles analysis --- :mod:`MDAnalysis.analysis.dihedrals` ================================================================= :Author: Henry Mull :Year: 2018 :Copyright: Lesser GNU Public License v2.1+ .. versionadded:: 0.19.0 This module contains classes for calculating dihedral angles for a given set of atoms or residues. This can be done for selected frames or whole trajectories. A list of time steps that contain angles of interest is generated and can be easily plotted if desired. For the :class:`~MDAnalysis.analysis.dihedrals.Ramachandran` and :class:`~MDAnalysis.analysis.dihedrals.Janin` classes, basic plots can be generated using the method :meth:`Ramachandran.plot` or :meth:`Janin.plot`. These plots are best used as references, but they also allow for user customization. See Also -------- :func:`MDAnalysis.lib.distances.calc_dihedrals()` function to calculate dihedral angles from atom positions Example applications -------------------- General dihedral analysis ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :class:`~MDAnalysis.analysis.dihedrals.Dihedral` class is useful for calculating angles for many dihedrals of interest. For example, we can find the phi angles for residues 5-10 of adenylate kinase (AdK). The trajectory is included within the test data files:: import MDAnalysis as mda from MDAnalysisTests.datafiles import GRO, XTC u = mda.Universe(GRO, XTC) # selection of atomgroups ags = [res.phi_selection() for res in u.residues[4:9]] from MDAnalysis.analysis.dihedrals import Dihedral R = Dihedral(ags).run() The angles can then be accessed with :attr:`Dihedral.results.angles`. Ramachandran analysis ~~~~~~~~~~~~~~~~~~~~~ The :class:`~MDAnalysis.analysis.dihedrals.Ramachandran` class allows for the quick calculation of classical Ramachandran plots :footcite:p:`Ramachandran1963` in the backbone :math:`phi` and :math:`psi` angles. Unlike the :class:`~MDanalysis.analysis.dihedrals.Dihedral` class which takes a list of `atomgroups`, this class only needs a list of residues or atoms from those residues. The previous example can repeated with:: u = mda.Universe(GRO, XTC) r = u.select_atoms("resid 5-10") R = Ramachandran(r).run() Then it can be plotted using the built-in plotting method :meth:`Ramachandran.plot()`:: import matplotlib.pyplot as plt fig, ax = plt.subplots(figsize=plt.figaspect(1)) R.plot(ax=ax, color='k', marker='o', ref=True) fig.tight_layout() as shown in the example :ref:`Ramachandran plot figure `. .. _figure-ramachandran: .. figure:: /images/rama_demo_plot.png :scale: 50 % :alt: Ramachandran plot Ramachandran plot for residues 5 to 10 of AdK, sampled from the AdK test trajectory (XTC). The contours in the background are the "allowed region" and the "marginally allowed" regions. To plot the data yourself, the angles can be accessed using :attr:`Ramachandran.results.angles`. .. Note:: The Ramachandran analysis is prone to errors if the topology contains duplicate or missing atoms (e.g. atoms with `altloc` or incomplete residues). If the topology has as an `altloc` attribute, you must specify only one `altloc` for the atoms with more than one (``"protein and not altloc B"``). Janin analysis ~~~~~~~~~~~~~~ Janin plots :footcite:p:`Janin1978` for side chain conformations (:math:`\chi_1` and :math:`chi_2` angles) can be created with the :class:`~MDAnalysis.analysis.dihedrals.Janin` class. It works in the same way, only needing a list of residues; see the :ref:`Janin plot figure ` as an example. The data for the angles can be accessed in the attribute :attr:`Janin.results.angles`. .. _figure-janin: .. figure:: /images/janin_demo_plot.png :scale: 50 % :alt: Janin plot Janin plot for all residues of AdK, sampled from the AdK test trajectory (XTC). The contours in the background are the "allowed region" and the "marginally allowed" regions for all possible residues. .. Note:: The Janin analysis is prone to errors if the topology contains duplicate or missing atoms (e.g. atoms with `altloc` or incomplete residues). If the topology has as an `altloc` attribute, you must specify only one `altloc` for the atoms with more than one (``"protein and not altloc B"``). Furthermore, many residues do not have a :math:`\chi_2` dihedral and if the selections of residues is not carefully filtered to only include those residues with *both* sidechain dihedrals then a :exc:`ValueError` with the message *Too many or too few atoms selected* is raised. Reference plots ~~~~~~~~~~~~~~~ Reference plots can be added to the axes for both the Ramachandran and Janin classes using the kwarg ``ref=True`` for the :meth:`Ramachandran.plot` and :meth:`Janin.plot` methods. The Ramachandran reference data (:data:`~MDAnalysis.analysis.data.filenames.Rama_ref`) and Janin reference data (:data:`~MDAnalysis.analysis.data.filenames.Janin_ref`) were made using data obtained from a large selection of 500 PDB files, and were analyzed using these classes :footcite:p:`Mull2018`. The allowed and marginally allowed regions of the Ramachandran reference plot have cutoffs set to include 90% and 99% of the data points, and the Janin reference plot has cutoffs for 90% and 98% of the data points. The list of PDB files used for the reference plots was taken from :footcite:p:`Lovell2003` and information about general Janin regions was taken from :footcite:p:`Janin1978`. Analysis Classes ---------------- .. autoclass:: Dihedral :members: :inherited-members: .. attribute:: results.angles Contains the time steps of the angles for each atomgroup in the list as an ``n_frames×len(atomgroups)`` :class:`numpy.ndarray` with content ``[[angle 1, angle 2, ...], [time step 2], ...]``. .. versionadded:: 2.0.0 .. attribute:: angles Alias to the :attr:`results.angles` attribute. .. deprecated:: 2.0.0 Will be removed in MDAnalysis 3.0.0. Please use :attr:`results.angles` instead. .. autoclass:: Ramachandran :members: :inherited-members: .. attribute:: results.angles Contains the time steps of the :math:`\phi` and :math:`\psi` angles for each residue as an ``n_frames×n_residues×2`` :class:`numpy.ndarray` with content ``[[[phi, psi], [residue 2], ...], [time step 2], ...]``. .. versionadded:: 2.0.0 .. attribute:: angles Alias to the :attr:`results.angles` attribute. .. deprecated:: 2.0.0 Will be removed in MDAnalysis 3.0.0. Please use :attr:`results.angles` instead. .. autoclass:: Janin :members: :inherited-members: .. attribute:: results.angles Contains the time steps of the :math:`\chi_1` and :math:`\chi_2` angles for each residue as an ``n_frames×n_residues×2`` :class:`numpy.ndarray` with content ``[[[chi1, chi2], [residue 2], ...], [time step 2], ...]``. .. versionadded:: 2.0.0 .. attribute:: angles Alias to the :attr:`results.angles` attribute. .. deprecated:: 2.0.0 Will be removed in MDAnalysis 3.0.0. Please use :attr:`results.angles` instead. References ---------- .. footbibliography:: N) AnalysisBase ResultsGroup)calc_dihedrals)Rama_ref Janin_refcjeZdZdZdZedZfdZdZdZ dZ dZ e d Z xZS) DihedralaCalculate dihedral angles for specified atomgroups. Dihedral angles will be calculated for each atomgroup that is given for each step in the trajectory. Each :class:`~MDAnalysis.core.groups.AtomGroup` must contain 4 atoms. Note ---- This class takes a list as an input and is most useful for a large selection of atomgroups. If there is only one atomgroup of interest, then it must be given as a list of one atomgroup. .. versionchanged:: 2.0.0 :attr:`angles` results are now stored in a :class:`MDAnalysis.analysis.base.Results` instance. .. versionchanged:: 2.8.0 introduced :meth:`get_supported_backends` allowing for parallel execution on ``multiprocessing`` and ``dask`` backends. TcdSN)serialmultiprocessingdaskclss g/srv/www/vhosts/g4struct/public_html/venv/lib/python3.11/site-packages/MDAnalysis/analysis/dihedrals.pyget_supported_backendszDihedral.get_supported_backends   c tt|j|djjfi|||_t d|Drtdtj d|D|_ tj d|D|_ tj d|D|_ tj d|D|_ dS) a-Parameters ---------- atomgroups : list[AtomGroup] a list of :class:`~MDAnalysis.core.groups.AtomGroup` for which the dihedral angles are calculated Raises ------ ValueError If any atomgroups do not contain 4 atoms rc4g|]}t|dkS))len.0ags r z%Dihedral.__init__../s"222B1 222rz#All AtomGroups must contain 4 atomscg|] }|d S)rrrs rrz%Dihedral.__init__..2!=!=!=B"Q%!=!=!=rcg|] }|d Srrs rrz%Dihedral.__init__..3rrcg|] }|d S)rrs rrz%Dihedral.__init__..4rrcg|] }|d S)rrs rrz%Dihedral.__init__..5rrN)superr __init__universe trajectory atomgroupsany ValueErrormda AtomGroupag1ag2ag3ag4)selfr+kwargs __class__s rr(zDihedral.__init__s 'h& qM " -  17   % 22z222 3 3 DBCC C=!=!=*!=!=!=>>=!=!=*!=!=!=>>=!=!=*!=!=!=>>=!=!=*!=!=!=>>rcg|j_dSNresultsanglesr4s r_preparezDihedral._prepare7  rc:tdtjiSNr;)lookuprndarray_vstackr<s r_get_aggregatorzDihedral._get_aggregator:Hl.I#JKKKKrct|jj|jj|jj|jj|jj}|jj |dS)Nbox) rr0 positionsr1r2r3 dimensionsr:r;append)r4angles r _single_framezDihedral._single_frame=s_ H  H  H  H #     ""5)))))rcztjtj|jj|j_dSr8nprad2degarrayr:r;r<s r _concludezDihedral._concludeG+ j$,2E)F)FGG rcRd}tj|t|jjSNzThe `angle` attribute was deprecated in MDAnalysis 2.0.0 and will be removed in MDAnalysis 3.0.0. Please use `results.angles` insteadwarningswarnDeprecationWarningr:r;r4wmsgs rr;zDihedral.anglesJ, '  d.///|""r)__name__ __module__ __qualname____doc__%_analysis_algorithm_is_parallelizable classmethodrr(r=rDrMrSpropertyr; __classcell__r6s@rr r s*-1)  [ ?????4!!!LLL***HHH##X#####rr c|eZdZdZdZedZ dfd ZdZd Z d Z d Z ddZ e dZxZS) Ramachandrana Calculate :math:`\phi` and :math:`\psi` dihedral angles of selected residues. :math:`\phi` and :math:`\psi` angles will be calculated for each residue corresponding to `atomgroup` for each time step in the trajectory. A :class:`~MDAnalysis.ResidueGroup` is generated from `atomgroup` which is compared to the protein to determine if it is a legitimate selection. Parameters ---------- atomgroup : AtomGroup or ResidueGroup atoms for residues for which :math:`\phi` and :math:`\psi` are calculated c_name : str (optional) name for the backbone C atom n_name : str (optional) name for the backbone N atom ca_name : str (optional) name for the alpha-carbon atom check_protein : bool (optional) whether to raise an error if the provided atomgroup is not a subset of protein atoms Example ------- For standard proteins, the default arguments will suffice to run a Ramachandran analysis:: r = Ramachandran(u.select_atoms('protein')).run() For proteins with non-standard residues, or for calculating dihedral angles for other linear polymers, you can switch off the protein checking and provide your own atom names in place of the typical peptide backbone atoms:: r = Ramachandran(u.atoms, c_name='CX', n_name='NT', ca_name='S', check_protein=False).run() The above analysis will calculate angles from a "phi" selection of CX'-NT-S-CX and "psi" selections of NT-S-CX-NT'. Raises ------ ValueError If the selection of residues is not contained within the protein and ``check_protein`` is ``True`` Note ---- If ``check_protein`` is ``True`` and the residue selection is beyond the scope of the protein and, then an error will be raised. If the residue selection includes the first or last residue, then a warning will be raised and they will be removed from the list of residues, but the analysis will still run. If a :math:`\phi` or :math:`\psi` selection cannot be made, that residue will be removed from the analysis. .. versionchanged:: 1.0.0 added c_name, n_name, ca_name, and check_protein keyword arguments .. versionchanged:: 2.0.0 :attr:`angles` results are now stored in a :class:`MDAnalysis.analysis.base.Results` instance. .. versionchanged:: 2.8.0 introduced :meth:`get_supported_backends` allowing for parallel execution on ``multiprocessing`` and ``dask`` backends. TcdSr rrs rrz#Ramachandran.get_supported_backendsrrCNCAc btt|j|jjfi|||_|jj}|r|jjdj}||std| |ddgs1tj d| |ddg}|} |} t!jd| D} | t!jd| Dz} t!j| stj dt'| | } t'| | } || }fd | D} |gfd |D} fd | D}t!j| t!j| zt!j|z} | | } || }| | } |jj| j| jjk|_|jk|_|j|k|_|jk|_| j| jjk|_dS) NproteinznFound atoms outside of protein. Only atoms inside of a 'protein' selection can be used to calculate dihedrals.rzBCannot determine phi and psi angles for the first or last residuescg|]}|duSr8rrrs rrz)Ramachandran.__init__..s5551$555rcg|]}|duSr8rrqs rrz)Ramachandran.__init__..s;;;! ;;;rz.s/EEE1S&011Q6EEErcHg|]tfdDS)c3ZK|]%}tjj|kdkV&dS)r"Nru)rnrrs r z3Ramachandran.__init__...s9==AGMQ&''1,======r)all)rrrrnamess @rrz)Ramachandran.__init__..sD   BCC====f=== = =   rcRg|]#}t|jjkdk$Sr!ru)rrrn_names rrz)Ramachandran.__init__..s/DDD1S&011Q6DDDr)r'rhr(r)r* atomgroupresidues select_atomsissubsetr- isdisjointrXrY difference_get_prev_residues_by_resid_get_next_residues_by_residrPrRr~rvrwrxr0r1r2r3ag5)r4rryrca_name check_proteinr5rrnprevnxtkeep keep_prevkeep_res keep_nextresrr6s `` @rr(zRamachandran.__init__s +lD!!*   )  -3   #>*  An-::9EENG$$W-- A + ((!R)9:: A '$..w2w/?@@33552244x5555566bh;;s;;;<<<vd||  M(   4:#d)nnD>FEEEEEE &'*    GO   EDDDDDD x ""RXh%7%77"(9:M:MMDztn$i:dj.&899Vv-.9Vw./9Vv-.9SY_67rcg|j_dSr8r9r<s rr=zRamachandran._preparer>rc:tdtjiSr@rBr<s rrDzRamachandran._get_aggregatorrErct|jj|jj|jj|jj|jj}t|jj|jj|jj|jj|jj}dt||D}|j j |dS)NrGcg|] \}}||f Srr)rphipsis rrz.Ramachandran._single_frame..s JJJ(#sC:JJJr) rr0rIr1r2r3rJrzipr:r;rK)r4 phi_angles psi_anglesphi_psis rrMzRamachandran._single_frames# H  H  H  H #    $ H  H  H  H #    KJc*j.I.IJJJ ""7+++++rcztjtj|jj|j_dSr8rOr<s rrSzRamachandran._concluderTrNFc |tj}|gd|ddd|ddd|t ddd t ddd d d tjj d }|j ||j ||rytjtjdddtjddd\}}gd}ddg}|||tjt$|||jjtj|jjjddd} |j| dddf| dddffi||S)aPlots data into standard Ramachandran plot. Each time step in :attr:`Ramachandran.results.angles` is plotted onto the same graph. Parameters ---------- ax : :class:`matplotlib.axes.Axes` If no `ax` is supplied or set to ``None`` then the plot will be added to the current active axes. ref : bool, optional Adds a general Ramachandran plot which shows allowed and marginally allowed regions kwargs : optional All other kwargs are passed to :func:`matplotlib.pyplot.scatter`. Returns ------- ax : :class:`matplotlib.axes.Axes` Axes with the plot, either `ax` or the current axes. N)Lrrrkr"colorlwr<z$\phi$z$\psi$xticksyticksxlabelylabel{x:g}$\degree$rr)r"i:#A1D4FF#35A1FFlevelscolorsr$)pltgcaaxisaxhlineaxvlinesetrange matplotlibtickerStrMethodFormatterxaxisset_major_formatteryaxisrPmeshgridarangecontourfloadrr:r;reshapeprodshapescatter r4axrefr5degree_formatterXYrras rplotzRamachandran.plots2 :B &&&''' 1CA &&& 1CA &&& sB''sB''    >0CC    $$%5666 $$%5666  O; $Q''4a)@)@DAq$^^F+F KK1bgh//vK N N N L  ' ' GDL'-bqb1 2 2A    1QQQT7AaaadG..v... rcRd}tj|t|jjSrVrWr[s rr;zRamachandran.angles7r]r)rjrkrlTNF)r^r_r`rarbrcrr(r=rDrMrSrrdr;rerfs@rrhrhUsAAF-1)  [  @8@8@8@8@8@8D!!!LLL,,,$HHH5555n##X#####rrhc6eZdZdZ d fd ZdZd dZxZS) JaninaCalculate :math:`\chi_1` and :math:`\chi_2` dihedral angles of selected residues. :math:`\chi_1` and :math:`\chi_2` angles will be calculated for each residue corresponding to `atomgroup` for each time step in the trajectory. A :class:`~MDAnalysis.ResidueGroup` is generated from `atomgroup` which is compared to the protein to determine if it is a legitimate selection. Note ---- If the residue selection is beyond the scope of the protein, then an error will be raised. If the residue selection includes the residues ALA, CYS*, GLY, PRO, SER, THR, or VAL (the default of the `select_remove` keyword argument) then a warning will be raised and they will be removed from the list of residues, but the analysis will still run. Some topologies have altloc attributes which can add duplicate atoms to the selection and must be removed. $resname ALA CYS* GLY PRO SER THR VALrnc xttj|jjfi||_|j}||j}|j|j}| |std|dt|dkr-tj d|d||}|jd_|jd_|jd_|jd _|jd _t)fd jjjjfDrtd d S)aParameters ---------- atomgroup : AtomGroup or ResidueGroup atoms for residues for which :math:`\chi_1` and :math:`\chi_2` are calculated select_remove : str selection string to remove residues that do not have :math:`chi_2` angles select_protein : str selection string to subselect protein-only residues from `atomgroup` to check that only amino acids are selected; if you have non-standard amino acids then adjust this selection to include them Raises ------ ValueError if the final selection of residues is not contained within the protein (as determined by ``atomgroup.select_atoms(select_protein)``) ValueError if not enough or too many atoms are found for a residue in the selection, usually due to missing atoms or alternative locations, or due to non-standard residues .. versionchanged:: 2.0.0 `select_remove` and `select_protein` keywords were added. :attr:`angles` results are now stored in a :class:`MDAnalysis.analysis.base.Results` instance. zPFound atoms outside of protein. Only atoms inside of a protein (select_protein='z&') can be used to calculate dihedrals.rzAll residues selected with 'z'' have been removed from the selection.zname Nzname CAzname CBz name CG CG1zname CD CD1 OD1 ND1 SDc3bK|])}tjt|kV*dSr8)rr0)rrr4s rr}z!Janin.__init__..sJ   MMSWW $      rzUToo many or too few atoms selected. Check for missing or duplicate atoms in topology.N)r'rhr(r)r*rrrrwrr-rrXrYrr0r1r2r3rr,) r4r select_removeselect_proteinr5rrnremover6s ` rr(zJanin.__init__WsR +lD!!*   )  -3   #%((88A,,];;D  )) 3/$2///  [[A   M8}888    **622H>..x88>..y99>..y99>..}==>../GHH     x48TX>      :    rctjtj|jjdzdz|j_dS)NhrOr<s rrSzJanin._concludes8 Jrx 344 5 5 ;  rNFc |tj}|gd|ddd|ddd|t ddd t ddd d d tjj d }|j ||j ||rytjtjdddtjddd\}}gd}ddg}|||tjt$|||jjtj|jjjddd} |j| dddf| dddffi||S)aPlots data into standard Janin plot. Each time step in :attr:`Janin.results.angles` is plotted onto the same graph. Parameters ---------- ax : :class:`matplotlib.axes.Axes` If no `ax` is supplied or set to ``None`` then the plot will be added to the current active axes. ref : bool, optional Adds a general Janin plot which shows allowed and marginally allowed regions kwargs : optional All other kwargs are passed to :func:`matplotlib.pyplot.scatter`. Returns ------- ax : :class:`matplotlib.axes.Axes` Axes with the plot, either `ax` or the current axes. N)rrrrrrr"rriirz$\chi_1$z$\chi_2$rrr)r"riXrrrr$)rrrrrrrrrrrrrrPrrrrrr:r;rrrrrs rrz Janin.plots2 :B    !!! 3ca ((( 3ca ((( C$$C$$    >0CC    $$%5666 $$%5666  P;ryC33RYq#q5I5IJJDAq [[F+F KK1bgi00K O O O L  ' ' GDL'-bqb1 2 2A    1QQQT7AaaadG..v... r)rrnr)r^r_r`rar(rSrrerfs@rrrBsy.= OOOOOOb 33333333rr)ranumpyrPmatplotlib.pyplotpyplotrrX MDAnalysisr.MDAnalysis.analysis.baserrMDAnalysis.lib.distancesr"MDAnalysis.analysis.data.filenamesrrr rhrrrrrs-.ZZv????????333333BBBBBBBBU#U#U#U#U#|U#U#U#pj#j#j#j#j#<j#j#j#Z^^^^^L^^^^^r