From fb6d2389f6fb5c07e27fdc94c447f746a62170b4 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Mon, 15 Jan 2024 19:01:31 +1100 Subject: [PATCH 1/7] reorg docs and some fixes --- docs/source/_static/custom.css | 206 ---------- docs/source/api.rst | 16 +- docs/source/conf.py | 2 +- docs/source/index.rst | 2 + docs/source/references.bib | 713 --------------------------------- docs/source/references.rst | 6 + docs/source/usage.rst | 253 ++++++++++++ mdahole2/analysis/__init__.py | 274 ------------- mdahole2/analysis/hole.py | 13 + 9 files changed, 288 insertions(+), 1197 deletions(-) delete mode 100644 docs/source/_static/custom.css create mode 100644 docs/source/references.rst create mode 100644 docs/source/usage.rst diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css deleted file mode 100644 index 480aa32..0000000 --- a/docs/source/_static/custom.css +++ /dev/null @@ -1,206 +0,0 @@ -/* override css for readable.css */ - -/* styles/fonts to match http://mdanalysis.org (see public/css) */ -/* MDAnalysis orange: #FF9200 */ -/* MDAnalysis gray: #808080 */ -/* MDAnalysis white: #FFFFFF */ -/* MDAnalysis black: #000000 */ -/* Darker orange: e76900 */ -/* Even darker orange: #a24900 */ -/* RTD dark grey: #343131 */ -/* RTD light grey: #e6e6e6 */ - -/* -- page layout --------------------------------------------------------- */ - -body { - font-family: 'PT Sans', Helvetica, Arial, 'sans-serif'; - font-size: 17px; -} - -div.body { - color: #000000; -} - -div.sphinxsidebar a:hover { - text-decoration: none !important; -} - -div.sphinxsidebar p { - color: #808080; -} - -/* Home MDAnalysis colour */ -.wy-side-nav-search > a { - color: #343131; -} - -/* Side MDAnalysis version colour */ -.wy-side-nav-search > div.version { - color: #808080; -} - -/* Menubar caption colour */ -div.wy-menu-vertical span.caption-text { - color: #FF9200; -} - -/* Mobile layout menubar option */ -nav.wy-nav-top { - background: #343131; -} - -/* Menu search bar outline (default blue) */ -.wy-side-nav-search input[type="text"] { - border-color: #808080; -} - - -/* -- body styles --------------------------------------------------------- */ - -/* Different coloured links for sidebar vs body) */ -div.rst-content a { - color: #FF9200; - text-decoration: none; -} - -div.rst-content a:visited { - color: #FF9200; -} - -a:hover { - color: #FF9200 !important; - text-decoration: underline; -} - - -pre, tt, code { - font-family: Menlo, Monaco, 'Courier New', monospace -} - - -div.body h1 { - font-weight: bolder; -} - -a.headerlink { - color: #808080; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - background-color: #808080; - color: #fff; -} - -/* ------- admonition boxes ------- */ - -div.admonition { - margin: 10px 0px; - padding: 10px 10px; -} - -div.admonition p.admonition-title { - font-size: 100%; - font-weight: bolder; -} - -/* ----- Tables ----- */ - -/* override table width restrictions */ -/* wrap tables instead of scrolling */ -@media screen and (min-width: 767px) { - - .wy-table-responsive table td, .wy-table-responsive table th { - /* !important prevents the common CSS stylesheets from overriding - this as on RTD they are loaded after this stylesheet */ - white-space: normal !important; - } - - .wy-table-responsive { - overflow: visible !important; - max-width: 100% !important; - } - } - -/* ----- Field lists ------ */ - -.section > dl.field-list { - display: flex; - flex-wrap: wrap; - margin: 0; - padding: 0; -} - -dl.field-list > dt::after { - content: ":"; -} - -.rst-content dl:not(.docutils) dt { - background: none; - color: #000000; - border-top: none; -} - -.section > dl.field-list dt { - margin: 0; - padding: 0; - flex-basis: 20%; - display: block; -} - -.section > dl.field-list > dd { - flex-basis: 70%; - margin: 0; -} - -.section > dl.field-list > dd p { - margin: 0; -} - -/* ----- MDAnalysis coloured elements ------ */ - -.rst-content dl.class dt, .rst-content dl.function dt { - color: #ca6500; - background: #FFEBD0; - border-top: solid 3px #FF9200; -} - -.rst-content .viewcode-link, .rst-content .viewcode-back { - color: #808080; -} - -.rst-content .guilabel { - background: #efefef; - border: 1px solid #808080; -} - - -.rst-content .seealso p.admonition-title { - background: #808080; -} - -.rst-content .seealso { - background: #e3e3e3; -} - -.rst-content .error p.admonition-title, .rst-content .warning p.admonition-title { - background: #F45F4B; -} - -.rst-content .error, .rst-content .warning { - background: #FFEEED; -} - -.rst-content .caution p.admonition-title, .rst-content .note p.admonition-title, .rst-content .important p.admonition-title { - background: #FF9200; -} - -.rst-content .caution, .rst-content .note, .rst-content .important { - background: #FFEBD0; -} - -.rst-content code:not(.xref).literal { - color: #ca6500; -} \ No newline at end of file diff --git a/docs/source/api.rst b/docs/source/api.rst index 4aed112..97903fc 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -10,17 +10,27 @@ API Documentation .. versionadded:: 1.0.0 -This module provides an updated interface for the HOLE_ suite of tools +This toolkit provides an updated interface for the HOLE_ suite of tools :cite:p:`Smart1993,Smart1996` to analyse an ion channel pore or transporter pathway :cite:p:`Stelzl2014` as a function of time or arbitrary order -parameters. It replaces :mod:`mdahole2.analysis.hole`. +parameters. HOLE_ must be installed separately and can be obtained in binary form from http://www.holeprogram.org/ or as source from https://github.com/osmart/hole2. (HOLE is open source and available under the Apache v2.0 license.) +.. _HOLE: http://www.holeprogram.org + Module ------ -.. automodule:: mdahole2.analysis +.. automodule:: mdahole2.analysis.hole + :members: + +.. automodule:: mdahole2.analysis.utils + :members: + +.. automodule:: mdahole2.analysis.templates + :members: + diff --git a/docs/source/conf.py b/docs/source/conf.py index 41839f3..67c91f0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -138,7 +138,7 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -html_css_files = ['custom.css'] # , 'readable.css'] +html_css_files = [] # , 'readable.css'] # Custom sidebar templates, maps document names to template names. # alabaster sidebars diff --git a/docs/source/index.rst b/docs/source/index.rst index c9f7309..1d2a420 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -11,7 +11,9 @@ Welcome to mdahole2's documentation! :caption: Contents: getting_started + usage api + references Indices and tables ================== diff --git a/docs/source/references.bib b/docs/source/references.bib index 13ec4aa..6803862 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -1,470 +1,3 @@ -@article{MichaudAgrawal2011, - author = {Michaud-Agrawal, Naveen and Denning, Elizabeth J. and Woolf, Thomas B. and Beckstein, Oliver}, - title = {MDAnalysis: A toolkit for the analysis of molecular dynamics simulations}, - journal = {Journal of Computational Chemistry}, - volume = {32}, - number = {10}, - pages = {2319-2327}, - doi = {https://doi.org/10.1002/jcc.21787}, - year = {2011} -} - -@article{Gowers2016, - title = {{MDAnalysis}: {A} {Python} {Package} for the {Rapid} {Analysis} of {Molecular} {Dynamics} {Simulations}}, - shorttitle = {{MDAnalysis}}, - url = {https://conference.scipy.org/proceedings/scipy2016/oliver_beckstein.html}, - doi = {10.25080/Majora-629e541a-00e}, - urldate = {2020-02-05}, - journal = {Proceedings of the 15th Python in Science Conference}, - author = {Gowers, Richard J. and Linke, Max and Barnoud, Jonathan and Reddy, Tyler J. E. and Melo, Manuel N. and Seyler, Sean L. and Domański, Jan and Dotson, David L. and Buchoux, Sébastien and Kenney, Ian M. and Beckstein, Oliver}, - year = {2016}, - note = {00152}, - pages = {98--105}, -} - -@article{Alt1995, - author = {Alt, Helmut and Godau, Michael}, - title = {Computing the Frechet distance between two polygonal curves}, - journal = {International Journal of Computational Geometry \& Applications}, - volume = {05}, - number = {01n02}, - pages = {75-91}, - year = {1995}, - doi = {10.1142/S0218195995000064} -} - -@article{ArayaSecchi2014, - author = {Araya-Secchi, Raul and Perez-Acle, Tomas and Kang, Seung-gu and Huynh, Tien and Bernardin, Alejandro and Escalona, Yerko and Garate, Jose-Antonio and Mart{\'\i}nez, Agustin D. and Garc{\'\i}a, Isaac E. and S{\'a}ez, Juan C. and Zhou, Ruhong}, - doi = {10.1016/j.bpj.2014.05.037}, - journal = {Biophysical Journal}, - Number = {3}, - Pages = {599--612}, - Publisher = {Elsevier}, - Title = {Characterization of a Novel Water Pocket Inside the Human Cx26 Hemichannel Structure}, - Volume = {107}, - year = {2014} -} - -@article{BerkHess2002, - title = {Convergence of sampling in protein simulations}, - author = {Hess, Berk}, - journal = {Phys. Rev. E}, - volume = {65}, - issue = {3}, - pages = {031910}, - numpages = {10}, - year = {2002}, - month = {Mar}, - publisher = {American Physical Society}, - doi = {10.1103/PhysRevE.65.031910} -} - -@article{Best2013, - author = {Robert B. Best and Gerhard Hummer and William A. Eaton }, - title = {Native contacts determine protein folding mechanisms in atomistic simulations}, - journal = {Proceedings of the National Academy of Sciences}, - volume = {110}, - number = {44}, - pages = {17874-17879}, - year = {2013}, - doi = {10.1073/pnas.1311599110} -} - -@article{Brodka1994, - author = { Aleksander Bródka }, - title = {Diffusion in restricted volume}, - journal = {Molecular Physics}, - volume = {82}, - number = {5}, - pages = {1075-1078}, - year = {1994}, - publisher = {Taylor & Francis}, - doi = {10.1080/00268979400100764} -} - -@article{Bulow2020, - author = {von Bülow,Sören and Bullerjahn,Jakob Tómas and Hummer,Gerhard }, - title = {Systematic errors in diffusion coefficients from long-time molecular dynamics simulations at constant pressure}, - journal = {The Journal of Chemical Physics}, - volume = {153}, - number = {2}, - pages = {021101}, - year = {2020}, - doi = {10.1063/5.0008316} -} - -@article{Chang2003, - author = {Chang, Chia-En and Potter, Michael J. and Gilson, Michael K.}, - title = {Calculation of Molecular Configuration Integrals}, - journal = {The Journal of Physical Chemistry B}, - volume = {107}, - number = {4}, - pages = {1048-1055}, - year = {2003}, - doi = {10.1021/jp027149c} -} - -@Article{Chavent2014, - author = {Chavent, Matthieu and Reddy, Tyler and Goose, Joseph and Dahl, Anna Caroline E. and Stone, John E. and Jobard, Bruno and Sansom, Mark S. P.}, - title = {Methodologies for the analysis of instantaneous lipid diffusion in md simulations of large membrane systems}, - journal = {Faraday Discuss.}, - year = {2014}, - volume = {169}, - pages = {455-475}, - publisher = {The Royal Society of Chemistry}, - doi = {10.1039/C3FD00145H} -} - -@article{Clementi2011, - author = {Rohrdanz,Mary A. and Zheng,Wenwei and Maggioni,Mauro and Clementi,Cecilia }, - title = {Determination of reaction coordinates via locally scaled diffusion map}, - journal = {The Journal of Chemical Physics}, - volume = {134}, - number = {12}, - pages = {124116}, - year = {2011}, - doi = {10.1063/1.3569857} -} - -@article{Denning2011 - author = {Denning, Elizabeth J. and Priyakumar, U. Deva and Nilsson, Lennart and Mackerell Jr., Alexander D.}, - title = {Impact of 2-hydroxyl sampling on the conformational properties of RNA: Update of the CHARMM all-atom additive force field for RNA}, - journal = {Journal of Computational Chemistry}, - year = {2011}, - volume = {32}, - number = {9}, - pages = {1929-1943}, - doi = {https://doi.org/10.1002/jcc.21777} -} - -@article{Denning2012, - author = {Denning, Elizabeth J. and MacKerell, Alexander D.}, - title = {Intrinsic Contribution of the 2{\'}-Hydroxyl to RNA Conformational Heterogeneity}, - journal = {Journal of the American Chemical Society}, - volume = {134}, - number = {5}, - pages = {2800-2806}, - year = {2012}, - doi = {10.1021/ja211328g}, - note ={PMID: 22242623} -} - -@article{EiterMannila1994, - author = {Eiter, Thomas and Mannila, Heikki}, - year = {1994}, - month = {05}, - journal = {}, - title = {Computing Discrete Frechet Distance} -} - -@article{EiterMannila1997, - author = {Eiter, Thomas and Mannila, Heikki}, - doi = {10.1007/s002360050075}, - journal = {Acta Informatica}, - Number = {2}, - Pages = {109--133}, - Title = {Distance measures for point sets and their computation}, - Volume = {34}, - year = {1997} -} - -@article{Ferguson2011, - author = {Andrew L. Ferguson and Athanassios Z. Panagiotopoulos and Ioannis G. Kevrekidis and Pablo G. Debenedetti}, - title = {Nonlinear dimensionality reduction in molecular simulation: The diffusion map approach}, - journal = {Chemical Physics Letters}, - volume = {509}, - number = {1}, - pages = {1-11}, - year = {2011}, - issn = {0009-2614}, - doi = {https://doi.org/10.1016/j.cplett.2011.04.066}, - url = {https://www.sciencedirect.com/science/article/pii/S0009261411004957} -} - -@article{Franklin2007, - author = {Franklin, Joel and Koehl, Patrice and Doniach, Sebastian and Delarue, Marc}, - title = "{MinActionPath: maximum likelihood trajectory for large-scale structural transitions in a coarse-grained locally harmonic energy landscape}", - journal = {Nucleic Acids Research}, - volume = {35}, - number = {suppl_2}, - pages = {W477-W482}, - year = {2007}, - doi = {10.1093/nar/gkm342} -} - -@article{Frechet1906, - author = {Frèchet, M. Maurice}, - doi = {10.1007/BF03018603}, - journal = {Rendiconti del Circolo Matematico di Palermo (1884-1940)}, - Number = {1}, - Pages = {1--72}, - Title = {Sur quelques points du calcul fonctionnel}, - Volume = {22}, - year = {1906} -} - -@article{Gowers2015, - author = {Gowers,Richard J. and Carbone,Paola }, - title = {A multiscale approach to model hydrogen bonding: The case of polyamide}, - journal = {The journal of Chemical Physics}, - volume = {142}, - number = {22}, - pages = {224907}, - year = {2015}, - doi = {10.1063/1.4922445} -} - -@article{Gregoret1991, - author = {Gregoret, Lydia M. and Rader, Stephen D. and Fletterick, Robert J. and Cohen, Fred E.}, - title = {Hydrogen bonds involving sulfur atoms in proteins}, - journal = {Proteins: Structure, Function, and Bioinformatics}, - year = {1991}, - volume = {9}, - number = {2}, - pages = {99-107}, - doi = {https://doi.org/10.1002/prot.340090204} -} - -@article{Grigera1995, - author = {Grigera, J. Raul and Kalko, Susana G. and Fischbarg, Jorge}, - title = {Wall−Water Interface. A Molecular Dynamics Study}, - journal = {Langmuir}, - volume = {12}, - number = {1}, - pages = {154-158}, - year = {1996}, - doi = {10.1021/la9408681} -} - -@article{Gu2019, - author = {Gu, Ruo-Xu and Baoukina, Svetlana and Tieleman, D. Peter}, - title = {Cholesterol Flip-Flop in Heterogeneous Membranes}, - journal = {Journal of Chemical Theory and Computation}, - volume = {15}, - number = {3}, - pages = {2064-2070}, - year = {2019}, - doi = {10.1021/acs.jctc.8b00933} -} - -@article{Hall2007, - author = {Hall, Benjamin A. and Kaye, Samantha L. and Pang, Andy and Perera, Rafael and Biggin, Philip C.}, - title = {Characterization of Protein Conformational States by Normal-Mode Frequencies}, - journal = {Journal of the American Chemical Society}, - volume = {129}, - number = {37}, - pages = {11394-11401}, - year = {2007}, - doi = {10.1021/ja071797y}, - note ={PMID: 17715919} -} - -@article{Hikiri2016, - author = {Hikiri, Simon and Yoshidome, Takashi and Ikeguchi, Mitsunori}, - title = {Computational Methods for Configurational Entropy Using Internal and Cartesian Coordinates}, - journal = {Journal of Chemical Theory and Computation}, - volume = {12}, - number = {12}, - pages = {5990-6000}, - year = {2016}, - doi = {10.1021/acs.jctc.6b00563}, - note ={PMID: 27951672} -} - -@article{Janin1978, - author = {Joël Janin and Shoshanna Wodak and Michael Levitt and Bernard Maigret}, - title = {Conformation of amino acid side-chains in proteins}, - journal = {Journal of Molecular Biology}, - volume = {125}, - number = {3}, - pages = {357-386}, - year = {1978}, - issn = {0022-2836}, - doi = {https://doi.org/10.1016/0022-2836(78)90408-4}, - url = {https://www.sciencedirect.com/science/article/pii/0022283678904084} -} - -@article{Jorgensen1998, - author = {Jorgensen, William L. and Jenson, Corky}, - title = {Temperature dependence of TIP3P, SPC, and TIP4P water from NPT Monte Carlo simulations: Seeking temperatures of maximum density}, - journal = {Journal of Computational Chemistry}, - year = {1998}, - volume = {19}, - number = {10}, - pages = {1179-1186}, - doi = {https://doi.org/10.1002/(SICI)1096-987X(19980730)19:10<1179::AID-JCC6>3.0.CO;2-J} -} - -@article{Coifman-Lafon, - author = {Ronald R. Coifman and Stéphane Lafon}, - title = {Diffusion maps}, - journal = {Applied and Computational Harmonic Analysis}, - volume = {21}, - number = {1}, - pages = {5-30}, - year = {2006}, - note = {Special Issue: Diffusion Maps and Wavelets}, - issn = {1063-5203}, - doi = {https://doi.org/10.1016/j.acha.2006.04.006}, - url = {https://www.sciencedirect.com/science/article/pii/S1063520306000546} -} - -@article{LindorffLarsen2009, - doi = {10.1371/journal.pone.0004203}, - author = {Lindorff-Larsen, Kresten AND Ferkinghoff-Borg, Jesper}, - journal = {PLOS ONE}, - publisher = {Public Library of Science}, - title = {Similarity Measures for Protein Ensembles}, - year = {2009}, - month = {01}, - volume = {4}, - pages = {1-13}, - number = {1} -} - -@article{Liu2004 - author = {Liu, Pu and Harder, Edward and Berne, B. J.}, - title = {On the Calculation of Diffusion Coefficients in Confined Fluids and Interfaces with an Application to the Liquid−Vapor Interface of Water}, - journal = {The Journal of Physical Chemistry B}, - volume = {108}, - number = {21}, - pages = {6595-6602}, - year = {2004}, - doi = {10.1021/jp0375057} -} - -@article{Lovell2003, - author = {Lovell, Simon C. and Davis, Ian W. and Arendall III, W. Bryan and de Bakker, Paul I. W. and Word, J. Michael and Prisant, Michael G. and Richardson, Jane S. and Richardson, David C.}, - title = {Structure validation by C$/alpha$ geometry: $\psi$,$\phi$ and C$\beta$ deviation}, - journal = {Proteins: Structure, Function, and Bioinformatics}, - year = {2003}, - volume = {50}, - number = {3}, - pages = {437-450}, - doi = {https://doi.org/10.1002/prot.10286} -} - -@article{Lu2003, - author = {Lu, Xiang‐Jun and Olson, Wilma K.}, - title = "{3DNA: a software package for the analysis, rebuilding and visualization of three‐dimensional nucleic acid structures}", - journal = {Nucleic Acids Research}, - volume = {31}, - number = {17}, - pages = {5108-5121}, - year = {2003}, - month = {09}, - issn = {0305-1048}, - doi = {10.1093/nar/gkg680} -} - -@article{Lu2008, - author = {Lu, Xiang-Jun and Olson, Wilma K}, - doi = {10.1038/nprot.2008.104}, - Isbn = {1750-2799}, - journal = {Nature Protocols}, - Number = {7}, - Pages = {1213--1227}, - Title = {3DNA: a versatile, integrated software system for the analysis, rebuilding and visualization of three-dimensional nucleic-acid structures}, - Volume = {3}, - year = {2008}, -} - -@article{Lundborg2014, - author = {Lundborg, Magnus and Apostolov, Rossen and Spångberg, Daniel and Gärdenäs, Anders and van der Spoel, David and Lindahl, Erik}, - title = {An efficient and extensible format, library, and API for binary trajectory data from molecular simulations}, - journal = {Journal of Computational Chemistry}, - volume = {35}, - number = {3}, - pages = {260-269}, - doi = {https://doi.org/10.1002/jcc.23495}, - url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.23495}, - year = {2014} -} - -@article{Maginn2019, - author = {Maginn, Edward J. and Messerly, Richard A. and Carlson, Daniel J. and Roe, Daniel R. and Elliot, J. Richard}, - title = {Best Practices for Computing Transport Properties Self-Diffusivity and Viscosity from Equilibrium Molecular Dynamics}, - volume = {1}, - doi = {10.33011/livecoms.1.1.6324}, - number = {1}, - journal = {Living Journal of Computational Molecular Science}, - year = {2018}, - month = {Dec.}, - pages = {6324}, - url = {https://livecomsjournal.org/index.php/livecoms/article/view/v1i1e6324} -} - -@article{Milischuk2011, - author = {Milischuk,Anatoli A. and Ladanyi,Branka M. }, - title = {Structure and dynamics of water confined in silica nanopores}, - journal = {The Journal of Chemical Physics}, - volume = {135}, - number = {17}, - pages = {174709}, - year = {2011}, - doi = {10.1063/1.3657408} -} - -@article{Minh2020, - author = {Minh, David D. L.}, - title = {Alchemical Grid Dock (AlGDock): Binding Free Energy Calculations between Flexible Ligands and Rigid Receptors}, - journal = {Journal of Computational Chemistry}, - year = {2020}, - volume = {41}, - number = {7}, - pages = {715-730}, - doi = {https://doi.org/10.1002/jcc.26036} -} - -@article{Mull2018, - author = "Henry Mull and Oliver Beckstein", - title = "{Technical Report: - SPIDAL Summer REU 2018 Dihedral Analysis in MDAnalysis}", - year = "2018", - month = "8", - journal = {}, - url ="https://figshare.com/articles/journal_contribution/Technical_Report_SPIDAL_Summer_REU_2018_Dihedral_Analysis_in_MDAnalysis/6957296", - doi = "10.6084/m9.figshare.6957296.v1" -} - -@article{Ramachandran1963, - author = {G.N. Ramachandran and C. Ramakrishnan and V. Sasisekharan}, - title = {Stereochemistry of polypeptide chain configurations}, - journal = {Journal of Molecular Biology}, - volume = {7}, - number = {1}, - pages = {95-99}, - year = {1963}, - issn = {0022-2836}, - doi = {https://doi.org/10.1016/S0022-2836(63)80023-6}, - url = {https://www.sciencedirect.com/science/article/pii/S0022283663800236} -} - -@article{Rapaport1983, - author = { D.C. Rapaport}, - title = {Hydrogen bonds in water}, - journal = {Molecular Physics}, - volume = {50}, - number = {5}, - pages = {1151-1162}, - year = {1983}, - publisher = {Taylor & Francis}, - doi = {10.1080/00268978300102931} -} - -@article{Seyler2015, - doi = {10.1371/journal.pcbi.1004568}, - author = {Seyler, Sean L. AND Kumar, Avishek AND Thorpe, M. F. AND Beckstein, Oliver}, - journal = {PLOS Computational Biology}, - publisher = {Public Library of Science}, - title = {Path Similarity Analysis: A Method for Quantifying Macromolecular Pathways}, - year = {2015}, - month = {10}, - volume = {11}, - pages = {1-37}, - number = {10} -} - @article{Smart1993, title = {The pore dimensions of gramicidin A}, journal = {Biophysical Journal}, @@ -501,249 +34,3 @@ @article{Stelzl2014 author = {Lukas S. Stelzl and Philip W. Fowler and Mark S.P. Sansom and Oliver Beckstein}, id = {Stelzl _et_ al.} } - -@article{Taha2015, - author={Taha, Abdel Aziz and Hanbury, Allan}, - journal={IEEE Transactions on Pattern Analysis and Machine Intelligence}, - title={An Efficient Algorithm for Calculating the Exact Hausdorff Distance}, - year={2015}, - volume={37}, - number={11}, - pages={2153-2163}, - doi={10.1109/TPAMI.2015.2408351} -} - -@article{Theobald2005, -author = "Theobald, Douglas L.", -title = "{Rapid calculation of RMSDs using a quaternion-based characteristic polynomial}", -journal = "Acta Crystallographica Section A", -year = "2005", -volume = "61", -number = "4", -pages = "478--480", -month = "Jul", -doi = {10.1107/S0108767305015266} -} - -@article{Tiberti2015, - doi = {10.1371/journal.pcbi.1004415}, - author = {Tiberti, Matteo AND Papaleo, Elena AND Bengtsen, Tone AND Boomsma, Wouter AND Lindorff-Larsen, Kresten}, - journal = {PLOS Computational Biology}, - publisher = {Public Library of Science}, - title = {ENCORE: Software for Quantitative Ensemble Comparison}, - year = {2015}, - month = {10}, - volume = {11}, - pages = {1-16}, - number = {10} -} - -@article{Welford1962, - author = { B. P. Welford}, - title = {Note on a Method for Calculating Corrected Sums of Squares and Products}, - journal = {Technometrics}, - volume = {4}, - number = {3}, - pages = {419-420}, - year = {1962}, - publisher = {Taylor & Francis}, - doi = {10.1080/00401706.1962.10490022} -} - -@article{Yeh1999, - author = {Yeh, Yu-ling and Mou, Chung-Yuan}, - title = {Orientational Relaxation Dynamics of Liquid Water Studied by Molecular Dynamics Simulation}, - journal = {The Journal of Physical Chemistry B}, - volume = {103}, - number = {18}, - pages = {3699-3705}, - year = {1999}, - doi = {10.1021/jp984584r} -} - -@article{Yeh2004, - author = {Yeh, In-Chul and Hummer, Gerhard}, - title = {System-Size Dependence of Diffusion Coefficients and Viscosities from Molecular Dynamics Simulations with Periodic Boundary Conditions}, - journal = {The Journal of Physical Chemistry B}, - volume = {108}, - number = {40}, - pages = {15873-15879}, - year = {2004}, - doi = {10.1021/jp0477147} -} - -@inproceedings{deLaPorte2008, - author = {Porte, J and Herbst, Ben and Hereman, Willy and van der Walt, Stéfan}, - year = {2008}, - month = {11}, - title = {An Introduction to Diffusion Maps}, - booktitle = {} -} - -@incollection{Goldman1990, - author = {Goldman, Ronald}, - title = {Matrices and Transformations}, - booktitle = {Graphics Gems I}, - year = {1990}, - isbn = {0122861695}, - publisher = {Morgan Kaufmann}, - address = {USA}, - pages = {472–475}, - numpages = {3}, - id = {transformations} -} - -@incollection{Shoemake1992-Uniform, - author = {Ken Shoemake}, - title = {Uniform Random Rotations}, - booktitle = {Graphics Gems III}, - editor = {David Kirk}, - publisher = {Academic Press}, - year = {1992}, - pages = {124--132}, - id = {transformations} -} - -@article{Karney2007, - title = {Quaternions in molecular modeling}, - journal = {Journal of Molecular Graphics and Modelling}, - volume = {25}, - number = {5}, - pages = {595-604}, - year = {2007}, - issn = {1093-3263}, - doi = {https://doi.org/10.1016/j.jmgm.2006.04.002}, - author = {Charles F.F. Karney}, - id = {transformations} -} - -@article{Bar-Itzhack2000, - author = {Bar-Itzhack, Itzhack Y.}, - title = {New Method for Extracting the Quaternion from a Rotation Matrix}, - journal = {Journal of Guidance, Control, and Dynamics}, - volume = {23}, - number = {6}, - pages = {1085-1087}, - year = {2000}, - doi = {10.2514/2.4654}, - id = {transformations} -} - -@incollection{Goldman1991-shear - title = {VII.4 - MORE MATRICES AND TRANSFORMATIONS: SHEAR AND PSEUDO-PERSPECTIVE}, - editor = {JAMES ARVO}, - booktitle = {Graphics Gems II}, - publisher = {Morgan Kaufmann}, - address = {San Diego}, - pages = {338-341}, - year = {1991}, - isbn = {978-0-08-050754-5}, - doi = {https://doi.org/10.1016/B978-0-08-050754-5.50072-4}, - url = {https://www.sciencedirect.com/science/article/pii/B9780080507545500724}, - author = {Ronald N. Goldman}, - id = {transformations} -} - -@incollection{Thomas1991, - title = {VII.1 - DECOMPOSING A MATRIX INTO SIMPLE TRANSFORMATIONS}, - editor = {JAMES ARVO}, - booktitle = {Graphics Gems II}, - publisher = {Morgan Kaufmann}, - address = {San Diego}, - pages = {320-323}, - year = {1991}, - isbn = {978-0-08-050754-5}, - doi = {https://doi.org/10.1016/B978-0-08-050754-5.50069-4}, - url = {https://www.sciencedirect.com/science/article/pii/B9780080507545500694}, - author = {Spencer W. Thomas}, - id = {transformations} -} - -@incollection{Goldman1991-transformation, - title = {VII.2 - RECOVERING THE DATA FROM THE TRANSFORMATION MATRIX}, - editor = {James Arvo}, - booktitle = {Graphics Gems II}, - publisher = {Morgan Kaufmann}, - address = {San Diego}, - pages = {324-331}, - year = {1991}, - isbn = {978-0-08-050754-5}, - doi = {https://doi.org/10.1016/B978-0-08-050754-5.50070-0}, - url = {https://www.sciencedirect.com/science/article/pii/B9780080507545500700}, - author = {Ronald N. Goldman}, - id = {transformations} -} - -@incollection{Shoemake1994-Euler, - author = {Ken Shoemake}, - title = {Euler Angle Conversion}, - booktitle = {Graphics Gems IV}, - editor = {Paul S. Heckbert}, - publisher = {Morgan Kaufmann}, - year = {1994}, - pages = {222--229}, - id = {transformations} -} - -@incollection{Shoemake1991-Arcball, - author = {Ken Shoemake}, - title = {Arcball Rotation Control}, - booktitle = {Graphics Gems IV}, - editor = {Paul S. Heckbert}, - publisher = {Morgan Kaufmann}, - year = {1994}, - pages = {175--192}, - id = {transformations} -} - -@incollection{Shoemake1991-Quaternions, - author = {Ken Shoemake}, - title = {Quaternions}, - booktitle = {}, - year = {}, - url = {https://www.ljll.math.upmc.fr/~frey/papers/scientific%20visualisation/Shoemake%20K.,%20Quaternions.pdf}, - id = {transformations} -} - -@incollection{Diebel2006, - author = {Diebel, James}, - year = {2006}, - title = {Representing Attitude: Euler Angles, Unit Quaternions, and Rotation Vectors}, - booktitle = {}, - id = {transformations} -} - -@article{Kabsch1978, - author = "Kabsch, W.", - title = "{A discussion of the solution for the best rotation to relate two sets of vectors}", - journal = "Acta Crystallographica Section A", - year = "1978", - volume = "34", - number = "5", - pages = "827--828", - month = "Sep", - doi = {10.1107/S0567739478001680}, - url = {https://doi.org/10.1107/S0567739478001680}, - id = {transformations} -} - -@article{Horn1987, - author = {Horn, Berthold}, - year = {1987}, - month = {04}, - pages = {629-642}, - title = {Closed-Form Solution of Absolute Orientation Using Unit Quaternions}, - volume = {4}, - journal = {Journal of the Optical Society A}, - doi = {10.1364/JOSAA.4.000629}, - id = {transformations} -} - -@incollection{Waveren2005 - title = {From Quaternion to Matrix and Back}, - author = {JMP van Waveren}, - year = {2005}, - url = {http://www.intel.com/cd/ids/developer/asmo-na/eng/293748.htm}, - booktitle = {}, - id = {transformations} -} \ No newline at end of file diff --git a/docs/source/references.rst b/docs/source/references.rst new file mode 100644 index 0000000..2e7c41c --- /dev/null +++ b/docs/source/references.rst @@ -0,0 +1,6 @@ + +========== +References +========== + +.. bibliography:: \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..575a3d9 --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,253 @@ +===== +Usage +===== + +This toolkit contains the tools to interface with HOLE_ +:cite:p:`Smart1993,Smart1996` to analyse an ion channel pore or transporter +pathway :cite:p:`Stelzl2014`. + +Using HOLE on a PDB file +------------------------ + +Use the ``hole`` function to run `HOLE`_ on a single PDB file. For example, +the code below runs the `HOLE`_ program installed at `~/hole2/exe/hole`:: + + from MDAnalysis.tests.datafiles import PDB_HOLE + from MDAnalysis.analysis import hole2 + profiles = hole2.hole(PDB_HOLE, executable='~/hole2/exe/hole') + # to create a VMD surface of the pore + hole2.create_vmd_surface(filename='hole.vmd') + +``profiles`` is a dictionary of HOLE profiles, indexed by the frame number. If +only a PDB file is passed to the function, there will only be one profile at +frame 0. You can visualise the pore by loading your PDB file into VMD, and in +:menuselection:`Extensions --> Tk Console`, type:: + + source hole.vmd + +You can also pass a DCD trajectory with the same atoms in the same order as +your PDB file with the ``dcd`` keyword argument. In that case, ``profiles`` +will contain multiple HOLE profiles, indexed by frame. + +The HOLE program will create some output files: + + * an output file (default name: hole.out) + * an sphpdb file (default name: hole.sph) + * a file of van der Waals' radii + (if not specified with ``vdwradii_file``. Default name: simple2.rad) + * a symlink of your PDB or DCD files (if the original name is too long) + * the input text (if you specify ``infile``) + +By default (`keep_files=True`), these files are kept. If you would like to +delete the files after the function is wrong, set `keep_files=False`. Keep in +mind that if you delete the sphpdb file, you cannot then create a VMD surface. + + +Using HOLE on a trajectory +-------------------------- + +You can also run HOLE on a trajectory through the :class:`HoleAnalysis` +class. This behaves similarly to the ``hole`` function, although +arguments such as ``cpoint`` and ``cvect`` become runtime arguments for +the :meth:`~HoleAnalysis.run` function. + +The class can be set-up and run like a normal MDAnalysis analysis class:: + + import MDAnalysis as mda + from MDAnalysis.tests.datafiles import MULTIPDB_HOLE + from MDAnalysis.analysis import hole2 + + u = mda.Universe(MULTIPDB_HOLE) + + ha = hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: + ha.run() + ha.create_vmd_surface(filename='hole.vmd') + +The VMD surface created by the class updates the pore for each frame of the +trajectory. Use it as normal by loading your trajectory in VMD and sourcing the +file in the Tk Console. + +You can access the actual profiles generated in the ``results`` attribute:: + + print(ha.results.profiles) + +Again, HOLE writes out files for each frame. If you would +like to delete these files after the analysis, you can +call :meth:`~HoleAnalysis.delete_temporary_files`:: + + ha.delete_temporary_files() + +Alternatively, you can use HoleAnalysis as a context manager that deletes +temporary files when you are finished with the context manager:: + + with hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: + h2.run() + h2.create_vmd_surface() + + +Using HOLE with VMD +------------------- + +The :program:`sos_triangle` program that is part of HOLE_ can write an input +file for VMD_ to display a triangulated surface of the pore found by +:program:`hole`. This functionality is available with the +:meth:`HoleAnalysis.create_vmd_surface` method +[#create_vmd_surface_function]_. For an input trajectory MDAnalysis writes a +*trajectory* of pore surfaces that can be animated in VMD together with the +frames from the trajectory. + + +Analyzing a full trajectory +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To analyze a full trajectory and write pore surfaces for all frames to file +:file:`hole_surface.vmd`, use :: + + import MDAnalysis as mda + from MDAnalysis.analysis import hole2 + + # load example trajectory MULTIPDB_HOLE + from MDAnalysis.tests.datafiles import MULTIPDB_HOLE + + u = mda.Universe(MULTIPDB_HOLE) + + with hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: + h2.run() + h2.create_vmd_surface(filename="hole_surface.vmd") + +In VMD, load your trajectory and then in the tcl console +(e.g.. :menuselection:`Extensions --> Tk Console`) load the surface +trajectory: + +.. code-block:: tcl + + source hole_surface.vmd + +If you only want to *subsample the trajectory* and only show the surface at +specific frames then you can either load the trajectory with the same +subsampling into VMD or create a subsampled trajectory. + + +Creating subsampled HOLE surface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For example, if we want to start displaying at frame 1 (i.e., skip frame +0), stop at frame 7, and only show every other frame (step 2) then the HOLE +analysis will be :: + + with hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: + h2.run(start=1, stop=9, step=2) + h2.create_vmd_surface(filename="hole_surface_subsampled.vmd") + +The commands produce the file ``hole_surface_subsampled.vmd`` that can be +loaded into VMD. + +.. Note:: + + Python (and MDAnalysis) stop indices are *exclusive* so the parameters + ``start=1``, ``stop=9``, and ``step=2`` will analyze frames 1, 3, 5, 7. + +.. _Loading-a-trajectory-into-VMD-with-subsampling: + +Loading a trajectory into VMD with subsampling +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Load your system into VMD. This can mean to load the topology file with +:menuselection:`File --> New Molecule` and adding the trajectory with +:menuselection:`File --> Load Data into Molecule` or just :menuselection:`File +--> New Molecule`. + +When loading the trajectory, subsample the frames by setting parametes in in +the :guilabel:`Frames` section. Select *First: 1*, *Last: 7*, *Stride: 2*. Then +:guilabel:`Load` everything. + +.. Note:: + + VMD considers the stop/last frame to be *inclusive* so you need to typically + choose one less than the ``stop`` value that you selected in MDAnalysis. + +Then load the surface trajectory: + +.. code-block:: tcl + + source hole_surface_subsampled.vmd + +You should see a different surface for each frame in the trajectory. +[#vmd_extra_frame]_ + + +Creating a subsampled trajectory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Instead of having VMD subsample the trajectory as described in +:ref:`Loading-a-trajectory-into-VMD-with-subsampling` we can write a subsampled +trajectory to a file. Although it requires more disk space, it can be +convenient if we want to visualize the system repeatedly. + +The example trajectory comes as a multi-PDB file so we need a suitable topology +file. If you already have a topology file such as a PSF, TPR, or PRMTOP file +then skip this step. We write frame 0 as a PDB :file:`frame0.pdb` (which we +will use as the topology in VMD):: + + u.atoms.write("frame0.pdb") + +Then write the actual trajectory in a convenient format such as TRR (or +DCD). Note that we apply the same slicing (``start=1``, ``stop=9``, ``step=2``) +to the trajectory itself and then use it as the value for the ``frames`` +parameter of :meth:`AtomGroup.write` +method:: + + u.atoms.write("subsampled.trr", frames=u.trajectory[1:9:2]) + +This command creates the subsampled trajectory file :file:`subsampled.trr` in +TRR format. + +In VMD we load the topology and the trajectory and then load the surface. In +our example we have a PDB file (:file:`frame0.pdb`) as topology so we need to +remove the first frame [#vmd_extra_frame]_ (skip the "trim" step below if you +are using a true topology file such as PSF, TPR, or PRMTOP). To keep this +example compact, we are using the tcl command line interface in VMD_ +(:menuselection:`Extensions --> Tk Console`) for loading and trimming the +trajectory; you can use the menu commands if you prefer. + +.. code-block:: tcl + + # load topology and subsampled trajectory + mol load pdb frame0.pdb trr subsampled.trr + + # trim first frame (frame0) -- SKIP if using PSF, TPR, PRMTOP + animate delete beg 0 end 0 + + # load the HOLE surface trajectory + source hole_surface_subsampled.vmd + +You can now animate your molecule together with the surface and render it. + + +.. _HOLE: http://www.holeprogram.org +.. _VMD: https://www.ks.uiuc.edu/Research/vmd/ + + +.. rubric:: References + +.. footbibliography:: + +.. rubric:: Footnotes + +.. Footnotes + +.. [#create_vmd_surface_function] If you use the :class:`hole` class to run + :program:`hole` on a single PDB file then you can use + :func:`MDAnalysis.analysis.hole2.utils.create_vmd_surface` + function to manually run :program:`sph_process` and + :program:`sos_triangle` on the output files andcr eate a surface + file. + +.. [#vmd_extra_frame] If you loaded your system in VMD_ from separate topology + and trajectory files and the topology file contained coordinates + (such as a PDB or GRO) file then your trajectory will have an + extra initial frame containing the coordinates from your topology + file. Delete the initial frame with :menuselection:`Molecule --> + Delete Frames` by setting *First* to 0 and *Last* to 0 and + selecting :guilabel:`Delete`. + diff --git a/mdahole2/analysis/__init__.py b/mdahole2/analysis/__init__.py index 5b8f7e8..8424adb 100644 --- a/mdahole2/analysis/__init__.py +++ b/mdahole2/analysis/__init__.py @@ -30,280 +30,6 @@ .. versionadded:: 1.0.0 -This module contains the tools to interface with HOLE_ -:cite:p:`Smart1993,Smart1996` to analyse an ion channel pore or transporter -pathway :cite:p:`Stelzl2014`. - -Using HOLE on a PDB file ------------------------- - -Use the :func:``hole`` function to run `HOLE`_ on a single PDB file. For example, -the code below runs the `HOLE`_ program installed at '~/hole2/exe/hole' :: - - from MDAnalysis.tests.datafiles import PDB_HOLE - from MDAnalysis.analysis import hole2 - profiles = hole2.hole(PDB_HOLE, executable='~/hole2/exe/hole') - # to create a VMD surface of the pore - hole2.create_vmd_surface(filename='hole.vmd') - -``profiles`` is a dictionary of HOLE profiles, indexed by the frame number. If -only a PDB file is passed to the function, there will only be one profile at -frame 0. You can visualise the pore by loading your PDB file into VMD, and in -Extensions > Tk Console, type:: - - source hole.vmd - -You can also pass a DCD trajectory with the same atoms in the same order as -your PDB file with the ``dcd`` keyword argument. In that case, ``profiles`` -will contain multiple HOLE profiles, indexed by frame. - -The HOLE program will create some output files: - - * an output file (default name: hole.out) - * an sphpdb file (default name: hole.sph) - * a file of van der Waals' radii - (if not specified with ``vdwradii_file``. Default name: simple2.rad) - * a symlink of your PDB or DCD files (if the original name is too long) - * the input text (if you specify ``infile``) - -By default (`keep_files=True`), these files are kept. If you would like to -delete the files after the function is wrong, set `keep_files=False`. Keep in -mind that if you delete the sphpdb file, you cannot then create a VMD surface. - - -Using HOLE on a trajectory --------------------------- - -You can also run HOLE on a trajectory through the :class:`HoleAnalysis` -class. This behaves similarly to the ``hole`` function, although -arguments such as ``cpoint`` and ``cvect`` become runtime arguments for -the :meth:`~HoleAnalysis.run` function. - -The class can be set-up and run like a normal MDAnalysis analysis class:: - - import MDAnalysis as mda - from MDAnalysis.tests.datafiles import MULTIPDB_HOLE - from MDAnalysis.analysis import hole2 - - u = mda.Universe(MULTIPDB_HOLE) - - ha = hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: - ha.run() - ha.create_vmd_surface(filename='hole.vmd') - -The VMD surface created by the class updates the pore for each frame of the -trajectory. Use it as normal by loading your trajectory in VMD and sourcing the -file in the Tk Console. - -You can access the actual profiles generated in the ``results`` attribute:: - - print(ha.results.profiles) - -Again, HOLE writes out files for each frame. If you would -like to delete these files after the analysis, you can -call :meth:`~HoleAnalysis.delete_temporary_files`:: - - ha.delete_temporary_files() - -Alternatively, you can use HoleAnalysis as a context manager that deletes -temporary files when you are finished with the context manager:: - - with hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: - h2.run() - h2.create_vmd_surface() - - -Using HOLE with VMD -------------------- - -The :program:`sos_triangle` program that is part of HOLE_ can write an input -file for VMD_ to display a triangulated surface of the pore found by -:program:`hole`. This functionality is available with the -:meth:`HoleAnalysis.create_vmd_surface` method -[#create_vmd_surface_function]_. For an input trajectory MDAnalysis writes a -*trajectory* of pore surfaces that can be animated in VMD together with the -frames from the trajectory. - - -Analyzing a full trajectory -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To analyze a full trajectory and write pore surfaces for all frames to file -:file:`hole_surface.vmd`, use :: - - import MDAnalysis as mda - from MDAnalysis.analysis import hole2 - - # load example trajectory MULTIPDB_HOLE - from MDAnalysis.tests.datafiles import MULTIPDB_HOLE - - u = mda.Universe(MULTIPDB_HOLE) - - with hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: - h2.run() - h2.create_vmd_surface(filename="hole_surface.vmd") - -In VMD, load your trajectory and then in the tcl console -(e.g.. :menuselection:`Extensions --> Tk Console`) load the surface -trajectory: - -.. code-block:: tcl - - source hole_surface.vmd - -If you only want to *subsample the trajectory* and only show the surface at -specific frames then you can either load the trajectory with the same -subsampling into VMD or create a subsampled trajectory. - - -Creating subsampled HOLE surface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For example, if we want to start displaying at frame 1 (i.e., skip frame -0), stop at frame 7, and only show every other frame (step 2) then the HOLE -analysis will be :: - - with hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: - h2.run(start=1, stop=9, step=2) - h2.create_vmd_surface(filename="hole_surface_subsampled.vmd") - -The commands produce the file ``hole_surface_subsampled.vmd`` that can be -loaded into VMD. - -.. Note:: - - Python (and MDAnalysis) stop indices are *exclusive* so the parameters - ``start=1``, ``stop=9``, and ``step=2`` will analyze frames 1, 3, 5, 7. - -.. _Loading-a-trajectory-into-VMD-with-subsampling: - -Loading a trajectory into VMD with subsampling -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Load your system into VMD. This can mean to load the topology file with -:menuselection:`File --> New Molecule` and adding the trajectory with -:menuselection:`File --> Load Data into Molecule` or just :menuselection:`File ---> New Molecule`. - -When loading the trajectory, subsample the frames by setting parametes in in -the :guilabel:`Frames` section. Select *First: 1*, *Last: 7*, *Stride: 2*. Then -:guilabel:`Load` everything. - -.. Note:: - - VMD considers the stop/last frame to be *inclusive* so you need to typically - choose one less than the ``stop`` value that you selected in MDAnalysis. - -Then load the surface trajectory: - -.. code-block:: tcl - - source hole_surface_subsampled.vmd - -You should see a different surface for each frame in the trajectory. -[#vmd_extra_frame]_ - - -Creating a subsampled trajectory -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Instead of having VMD subsample the trajectory as described in -:ref:`Loading-a-trajectory-into-VMD-with-subsampling` we can write a subsampled -trajectory to a file. Although it requires more disk space, it can be -convenient if we want to visualize the system repeatedly. - -The example trajectory comes as a multi-PDB file so we need a suitable topology -file. If you already have a topology file such as a PSF, TPR, or PRMTOP file -then skip this step. We write frame 0 as a PDB :file:`frame0.pdb` (which we -will use as the topology in VMD):: - - u.atoms.write("frame0.pdb") - -Then write the actual trajectory in a convenient format such as TRR (or -DCD). Note that we apply the same slicing (``start=1``, ``stop=9``, ``step=2``) -to the trajectory itself and then use it as the value for the ``frames`` -parameter of :meth:`AtomGroup.write` -method:: - - u.atoms.write("subsampled.trr", frames=u.trajectory[1:9:2]) - -This command creates the subsampled trajectory file :file:`subsampled.trr` in -TRR format. - -In VMD we load the topology and the trajectory and then load the surface. In -our example we have a PDB file (:file:`frame0.pdb`) as topology so we need to -remove the first frame [#vmd_extra_frame]_ (skip the "trim" step below if you -are using a true topology file such as PSF, TPR, or PRMTOP). To keep this -example compact, we are using the tcl command line interface in VMD_ -(:menuselection:`Extensions --> Tk Console`) for loading and trimming the -trajectory; you can use the menu commands if you prefer. - -.. code-block:: tcl - - # load topology and subsampled trajectory - mol load pdb frame0.pdb trr subsampled.trr - - # trim first frame (frame0) -- SKIP if using PSF, TPR, PRMTOP - animate delete beg 0 end 0 - - # load the HOLE surface trajectory - source hole_surface_subsampled.vmd - -You can now animate your molecule together with the surface and render it. - - -.. _HOLE: http://www.holeprogram.org -.. _VMD: https://www.ks.uiuc.edu/Research/vmd/ - -Functions and classes ---------------------- - -.. autofunction:: hole - -.. autoclass:: HoleAnalysis - :members: - - -.. rubric:: References - -.. bibliography:: - :filter: False - - Smart1993 - Smart1996 - Stelzl2014 - -.. rubric:: Footnotes - -.. Footnotes - -.. [#create_vmd_surface_function] If you use the :class:`hole` class to run - :program:`hole` on a single PDB file then you can use - :func:`MDAnalysis.analysis.hole2.utils.create_vmd_surface` - function to manually run :program:`sph_process` and - :program:`sos_triangle` on the output files andcr eate a surface - file. - -.. [#vmd_extra_frame] If you loaded your system in VMD_ from separate topology - and trajectory files and the topology file contained coordinates - (such as a PDB or GRO) file then your trajectory will have an - extra initial frame containing the coordinates from your topology - file. Delete the initial frame with :menuselection:`Molecule --> - Delete Frames` by setting *First* to 0 and *Last* to 0 and - selecting :guilabel:`Delete`. - -.. [#HOLEDCD] PDB files are not the only files that :program:`hole` can - read. In principle, it is also able to read CHARMM DCD - trajectories and generate a hole profile for each frame. However, - native support for DCD in :program:`hole` is patchy and not every - DCD is recognized. In particular, At the moment, DCDs generated - with MDAnalysis are not accepted by HOLE. To overcome this - PDB / DCD limitation, use :class:`HoleAnalysis` which creates - temporary PDB files for each frame of a - :class:`~MDAnalysis.core.universe.Universe` or - :class:`~MDAnalysis.core.universe.AtomGroup` and runs - :func:``hole`` on each of them. - """ from .hole import hole, HoleAnalysis from .utils import create_vmd_surface diff --git a/mdahole2/analysis/hole.py b/mdahole2/analysis/hole.py index 20e1858..59ca1da 100644 --- a/mdahole2/analysis/hole.py +++ b/mdahole2/analysis/hole.py @@ -212,6 +212,19 @@ def hole(pdbfile, .. versionadded:: 1.0 + .. [#HOLEDCD] PDB files are not the only files that :program:`hole` can + read. In principle, it is also able to read CHARMM DCD + trajectories and generate a hole profile for each frame. However, + native support for DCD in :program:`hole` is patchy and not every + DCD is recognized. In particular, At the moment, DCDs generated + with MDAnalysis are not accepted by HOLE. To overcome this + PDB / DCD limitation, use :class:`HoleAnalysis` which creates + temporary PDB files for each frame of a + :class:`~MDAnalysis.core.universe.Universe` or + :class:`~MDAnalysis.core.universe.AtomGroup` and runs + ``hole`` on each of them. + + """ if output_level > 3: msg = 'output_level ({}) needs to be < 3 in order to extract a HOLE profile!' From e5da7159f5890f4b7068ca3e5a3dcb93c7ac6208 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Tue, 23 Jan 2024 21:58:28 +1100 Subject: [PATCH 2/7] update notes to include path finding --- docs/source/getting_started.rst | 2 +- docs/source/usage.rst | 40 ++++++++++++++++++++++++--------- 2 files changed, 31 insertions(+), 11 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index fab464f..1d39346 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -2,7 +2,7 @@ Getting Started =============== This page details how to get started with ``mdahole2``. -Note that ``mdahole2`` is only supported on Linux or macOS. +Note that ``mdahole2`` is currently only supported on Linux or macOS. Documentation ~~~~~~~~~~~~~ diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 575a3d9..418e22c 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -6,15 +6,35 @@ This toolkit contains the tools to interface with HOLE_ :cite:p:`Smart1993,Smart1996` to analyse an ion channel pore or transporter pathway :cite:p:`Stelzl2014`. +Finding your hole executable +---------------------------- + +The first step is to find your HOLE executable. If you have installed HOLE +through ``conda-forge``, then you can find the executable path by searching +``which hole``, e.g.: + +.. code-block:: bash + + $ which hole + /home/username/miniforge3/envs/mdahole2/bin/hole + +If you have installed HOLE from the original source, the executable +may be in your home directory instead, e.g. a path such as ``~/hole2/exe/hole``. + +Throughout the rest of this documentation, we will assume that your executable +is at ``~/miniforge3/envs/mdahole2/bin/hole``. + + Using HOLE on a PDB file ------------------------ Use the ``hole`` function to run `HOLE`_ on a single PDB file. For example, -the code below runs the `HOLE`_ program installed at `~/hole2/exe/hole`:: +the code below runs the `HOLE`_ program installed at `~/miniforge3/envs/mdahole2/bin/hole`:: from MDAnalysis.tests.datafiles import PDB_HOLE - from MDAnalysis.analysis import hole2 - profiles = hole2.hole(PDB_HOLE, executable='~/hole2/exe/hole') + from mdahole2.analysis import hole + + profiles = hole(PDB_HOLE, executable='~/miniforge3/envs/mdahole2/bin/hole') # to create a VMD surface of the pore hole2.create_vmd_surface(filename='hole.vmd') @@ -55,11 +75,11 @@ The class can be set-up and run like a normal MDAnalysis analysis class:: import MDAnalysis as mda from MDAnalysis.tests.datafiles import MULTIPDB_HOLE - from MDAnalysis.analysis import hole2 + from mdahole2.analysis import HoleAnalysis u = mda.Universe(MULTIPDB_HOLE) - ha = hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: + ha = HoleAnalysis(u, executable='~/miniforge3/envs/mdahole2/bin/hole') as h2: ha.run() ha.create_vmd_surface(filename='hole.vmd') @@ -80,7 +100,7 @@ call :meth:`~HoleAnalysis.delete_temporary_files`:: Alternatively, you can use HoleAnalysis as a context manager that deletes temporary files when you are finished with the context manager:: - with hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: + with HoleAnalysis(u, executable='~/miniforge3/envs/mdahole2/bin/hole') as h2: h2.run() h2.create_vmd_surface() @@ -104,14 +124,14 @@ To analyze a full trajectory and write pore surfaces for all frames to file :file:`hole_surface.vmd`, use :: import MDAnalysis as mda - from MDAnalysis.analysis import hole2 + from mdahole2.analysis import HoleAnalysis # load example trajectory MULTIPDB_HOLE from MDAnalysis.tests.datafiles import MULTIPDB_HOLE u = mda.Universe(MULTIPDB_HOLE) - with hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: + with HoleAnalysis(u, executable='~/miniforge3/envs/mdahole2/bin/hole') as h2: h2.run() h2.create_vmd_surface(filename="hole_surface.vmd") @@ -135,7 +155,7 @@ For example, if we want to start displaying at frame 1 (i.e., skip frame 0), stop at frame 7, and only show every other frame (step 2) then the HOLE analysis will be :: - with hole2.HoleAnalysis(u, executable='~/hole2/exe/hole') as h2: + with HoleAnalysis(u, executable='~/miniforge3/envs/mdahole2/bin/hole') as h2: h2.run(start=1, stop=9, step=2) h2.create_vmd_surface(filename="hole_surface_subsampled.vmd") @@ -238,7 +258,7 @@ You can now animate your molecule together with the surface and render it. .. [#create_vmd_surface_function] If you use the :class:`hole` class to run :program:`hole` on a single PDB file then you can use - :func:`MDAnalysis.analysis.hole2.utils.create_vmd_surface` + :func:`mdahole2.analysis.utils.create_vmd_surface` function to manually run :program:`sph_process` and :program:`sos_triangle` on the output files andcr eate a surface file. From ef705dcea9dd8ea49a472a3df6d882406c46f0d5 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Tue, 23 Jan 2024 21:59:24 +1100 Subject: [PATCH 3/7] conda activate --- docs/source/usage.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 418e22c..54b5f6e 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -11,10 +11,11 @@ Finding your hole executable The first step is to find your HOLE executable. If you have installed HOLE through ``conda-forge``, then you can find the executable path by searching -``which hole``, e.g.: +``which hole``. First ensure that you have activated the correct conda environment: .. code-block:: bash + $ conda activate mdahole2 $ which hole /home/username/miniforge3/envs/mdahole2/bin/hole From 6171efed4eafa02b321580d2b5101133dd5ebdb0 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Tue, 23 Jan 2024 22:02:31 +1100 Subject: [PATCH 4/7] update installation for hole2 --- docs/source/getting_started.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 1d39346..25c29a7 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -45,3 +45,19 @@ From the repository root directory, run conda build . && conda install --use-local mdahole2 to build the package and install the local build. + +Installing hole2 +~~~~~~~~~~~~~~~~ + +``mdahole2`` requires the ``hole2`` executable to be installed. + +This is most easily done using ``conda``, ``mamba``, or a similar +package manager. For example, to install ``hole2`` using ``mamba``: + +.. code:: bash + + mamba install -c conda-forge hole2 + +Alternatively, ``hole2`` can be installed from the original HOLE_ website. + +.. _HOLE: http://www.holeprogram.org \ No newline at end of file From 8e11e0c300cb5f85fd56f38ca79aed2824483eed Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Mon, 29 Jan 2024 22:09:25 +1100 Subject: [PATCH 5/7] remove specific executable --- docs/source/usage.rst | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 54b5f6e..e6a993b 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -9,33 +9,30 @@ pathway :cite:p:`Stelzl2014`. Finding your hole executable ---------------------------- -The first step is to find your HOLE executable. If you have installed HOLE -through ``conda-forge``, then you can find the executable path by searching -``which hole``. First ensure that you have activated the correct conda environment: - -.. code-block:: bash - - $ conda activate mdahole2 - $ which hole - /home/username/miniforge3/envs/mdahole2/bin/hole - +``mdahole2`` is a Python package that interfaces with the HOLE_ program. +This necessitates having a HOLE executable on your system. +``mdahole2`` will be able to find your executable if it is on your ``PATH``, +i.e. if it can be discovered by calling ``which hole``. +However, if you have installed HOLE_ through a nonstandard pathway, +then you will need to specify a path to your ``hole`` executable. + +For example, if you installed HOLE from the original source, If you have installed HOLE from the original source, the executable may be in your home directory instead, e.g. a path such as ``~/hole2/exe/hole``. Throughout the rest of this documentation, we will assume that your executable -is at ``~/miniforge3/envs/mdahole2/bin/hole``. +is in your ``PATH``, and will not specify a path.. Using HOLE on a PDB file ------------------------ -Use the ``hole`` function to run `HOLE`_ on a single PDB file. For example, -the code below runs the `HOLE`_ program installed at `~/miniforge3/envs/mdahole2/bin/hole`:: +Use the ``hole`` function to run `HOLE`_ on a single PDB file. For example:: from MDAnalysis.tests.datafiles import PDB_HOLE from mdahole2.analysis import hole - profiles = hole(PDB_HOLE, executable='~/miniforge3/envs/mdahole2/bin/hole') + profiles = hole(PDB_HOLE) # to create a VMD surface of the pore hole2.create_vmd_surface(filename='hole.vmd') @@ -80,7 +77,7 @@ The class can be set-up and run like a normal MDAnalysis analysis class:: u = mda.Universe(MULTIPDB_HOLE) - ha = HoleAnalysis(u, executable='~/miniforge3/envs/mdahole2/bin/hole') as h2: + ha = HoleAnalysis(u) ha.run() ha.create_vmd_surface(filename='hole.vmd') @@ -101,7 +98,7 @@ call :meth:`~HoleAnalysis.delete_temporary_files`:: Alternatively, you can use HoleAnalysis as a context manager that deletes temporary files when you are finished with the context manager:: - with HoleAnalysis(u, executable='~/miniforge3/envs/mdahole2/bin/hole') as h2: + with HoleAnalysis(u) as h2: h2.run() h2.create_vmd_surface() @@ -132,12 +129,12 @@ To analyze a full trajectory and write pore surfaces for all frames to file u = mda.Universe(MULTIPDB_HOLE) - with HoleAnalysis(u, executable='~/miniforge3/envs/mdahole2/bin/hole') as h2: + with HoleAnalysis(u) as h2: h2.run() h2.create_vmd_surface(filename="hole_surface.vmd") In VMD, load your trajectory and then in the tcl console -(e.g.. :menuselection:`Extensions --> Tk Console`) load the surface +(e.g. :menuselection:`Extensions --> Tk Console`) load the surface trajectory: .. code-block:: tcl @@ -156,7 +153,7 @@ For example, if we want to start displaying at frame 1 (i.e., skip frame 0), stop at frame 7, and only show every other frame (step 2) then the HOLE analysis will be :: - with HoleAnalysis(u, executable='~/miniforge3/envs/mdahole2/bin/hole') as h2: + with HoleAnalysis(u) as h2: h2.run(start=1, stop=9, step=2) h2.create_vmd_surface(filename="hole_surface_subsampled.vmd") From 2a27a93c8218acd03be0ca05243c318b472863cd Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Mon, 29 Jan 2024 22:13:16 +1100 Subject: [PATCH 6/7] fix punctuation and clear text --- docs/source/usage.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index e6a993b..7359683 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -11,17 +11,24 @@ Finding your hole executable ``mdahole2`` is a Python package that interfaces with the HOLE_ program. This necessitates having a HOLE executable on your system. -``mdahole2`` will be able to find your executable if it is on your ``PATH``, +``mdahole2`` will be able to automatically find your executable if it is in your ``PATH``, i.e. if it can be discovered by calling ``which hole``. +This should be the case for the vast majority of installations +through the recommended pathway of ``conda-forge``. + However, if you have installed HOLE_ through a nonstandard pathway, -then you will need to specify a path to your ``hole`` executable. +then you will need to specify a path to your ``hole`` executable like so:: + + from MDAnalysis.tests.datafiles import PDB_HOLE + from mdahole2.analysis import hole + + profiles = hole(PDB_HOLE, executable='/path/to/hole') -For example, if you installed HOLE from the original source, -If you have installed HOLE from the original source, the executable -may be in your home directory instead, e.g. a path such as ``~/hole2/exe/hole``. +For example, if you installed HOLE from the original source, the executable +may be in your home directory, e.g. a path such as ``~/hole2/exe/hole``. Throughout the rest of this documentation, we will assume that your executable -is in your ``PATH``, and will not specify a path.. +is in your ``PATH``, and will not specify a different path. Using HOLE on a PDB file From 12e3f1bee3a2e427d27676e1933bc48fa751ed44 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Tue, 30 Jan 2024 18:59:51 +1100 Subject: [PATCH 7/7] remove versionadded and versionchanged --- docs/source/api.rst | 2 -- mdahole2/analysis/__init__.py | 2 -- mdahole2/analysis/hole.py | 15 --------------- mdahole2/analysis/templates.py | 2 -- mdahole2/analysis/utils.py | 4 ---- 5 files changed, 25 deletions(-) diff --git a/docs/source/api.rst b/docs/source/api.rst index 97903fc..46cb119 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -8,8 +8,6 @@ API Documentation :Year: 2020 :Copyright: GNU Public License v3 -.. versionadded:: 1.0.0 - This toolkit provides an updated interface for the HOLE_ suite of tools :cite:p:`Smart1993,Smart1996` to analyse an ion channel pore or transporter pathway :cite:p:`Stelzl2014` as a function of time or arbitrary order diff --git a/mdahole2/analysis/__init__.py b/mdahole2/analysis/__init__.py index 8424adb..74c753b 100644 --- a/mdahole2/analysis/__init__.py +++ b/mdahole2/analysis/__init__.py @@ -28,8 +28,6 @@ :Year: 2020 :Copyright: GNU Public License v3 -.. versionadded:: 1.0.0 - """ from .hole import hole, HoleAnalysis from .utils import create_vmd_surface diff --git a/mdahole2/analysis/hole.py b/mdahole2/analysis/hole.py index 59ca1da..a5881ed 100644 --- a/mdahole2/analysis/hole.py +++ b/mdahole2/analysis/hole.py @@ -210,8 +210,6 @@ def hole(pdbfile, - HOLE is very picky and does not read all DCD-like formats [#HOLEDCD]_. If in doubt, look into the `outfile` for error diagnostics. - .. versionadded:: 1.0 - .. [#HOLEDCD] PDB files are not the only files that :program:`hole` can read. In principle, it is also able to read CHARMM DCD trajectories and generate a hole profile for each frame. However, @@ -394,19 +392,13 @@ class HoleAnalysis(AnalysisBase): results.sphpdbs: numpy.ndarray Array of sphpdb filenames - .. versionadded:: 2.0.0 - results.outfiles: numpy.ndarray Arrau of output filenames - .. versionadded:: 2.0.0 - results.profiles: dict Profiles generated by HOLE2. A dictionary of :class:`numpy.recarray`\ s, indexed by frame. - .. versionadded:: 2.0.0 - sphpdbs: numpy.ndarray Alias of :attr:`results.sphpdbs` @@ -428,13 +420,6 @@ class HoleAnalysis(AnalysisBase): This will be removed in MDAnalysis 3.0.0. Please use :attr:`results.profiles` instead. - .. versionadded:: 1.0 - - .. versionchanged:: 2.0.0 - :attr:`sphpdbs`, :attr:`outfiles` and :attr:`profiles ` - are now stored in a :class:`MDAnalysis.analysis.base.Results` - instance. - """ input_file = '{prefix}hole{i:03d}.inp' diff --git a/mdahole2/analysis/templates.py b/mdahole2/analysis/templates.py index 3ab83f1..8665e81 100644 --- a/mdahole2/analysis/templates.py +++ b/mdahole2/analysis/templates.py @@ -28,8 +28,6 @@ :Year: 2020 :Copyright: GNU Public License v3 -.. versionadded:: 1.0 - Templates used in :mod:`mdahole2.analysis.hole` """ diff --git a/mdahole2/analysis/utils.py b/mdahole2/analysis/utils.py index 8694d04..380f0b2 100644 --- a/mdahole2/analysis/utils.py +++ b/mdahole2/analysis/utils.py @@ -30,8 +30,6 @@ :Year: 2020 :Copyright: GNU Public License v3 -.. versionadded:: 1.0 - Helper functions used in :mod:`mdahole2.analysis.hole` """ import logging @@ -308,8 +306,6 @@ def set_up_hole_input(pdbfile, str input text to run HOLE - .. versionadded:: 1.0 - """.format(IGNORE_RESIDUES) short_filename = check_and_fix_long_filename(pdbfile, tmpdir=tmpdir) if vdwradii_file is not None: