diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..1245903 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,14 @@ +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "mambaforge-4.10" + +python: + install: + - method: pip + path: . + +conda: + environment: docs/requirements.yaml diff --git a/docs/requirements.yaml b/docs/requirements.yaml index 5340ee6..aeaef6b 100644 --- a/docs/requirements.yaml +++ b/docs/requirements.yaml @@ -9,5 +9,6 @@ dependencies: - pip - mdanalysis-sphinx-theme >=1.0.1 + - sphinxcontrib-bibtex # Pip-only installs #- pip: diff --git a/docs/source/api.rst b/docs/source/api.rst index b920649..a60c504 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -1,8 +1,4 @@ API Documentation ================= -.. autosummary:: - :toctree: autosummary - :recursive: - - pathsimanalysis +.. automodule:: pathsimanalysis.psa diff --git a/docs/source/conf.py b/docs/source/conf.py index 7b829e8..62bd9bd 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -53,9 +53,12 @@ "sphinx.ext.napoleon", "sphinx.ext.intersphinx", "sphinx.ext.extlinks", + 'sphinxcontrib.bibtex', "mdanalysis_sphinx_theme", ] +bibtex_bibfiles = ['references.bib'] + autosummary_generate = True # This skips generating an autodoc of the test module # when using the autosummary directive that is included diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index ed69a6a..dfd56bb 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -2,3 +2,14 @@ Getting Started =============== This page details how to get started with PathSimAnalysis. + +Installation +------------ + +PathSimAnalysis is currently only installable from source. + +.. code-block:: bash + + git clone --depth=1 https://github.com/MDAnalysis/PathSimAnalysis + cd PathSimAnalysis + pip install . \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index da3f5e0..bcec6b7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,6 +6,8 @@ Welcome to PathSimAnalysis's documentation! ========================================================= +PathSimAnalysis is an MDAnalysis based analysis package for calculating the similarity between molecular dynamics trajectories. + .. toctree:: :maxdepth: 2 :caption: Contents: diff --git a/docs/source/references.bib b/docs/source/references.bib new file mode 100644 index 0000000..42c1ff9 --- /dev/null +++ b/docs/source/references.bib @@ -0,0 +1,64 @@ +@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{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{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{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{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} +} \ No newline at end of file diff --git a/pathsimanalysis/data/README.md b/pathsimanalysis/data/README.md deleted file mode 100644 index 550587e..0000000 --- a/pathsimanalysis/data/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Sample Package Data - -This directory contains sample additional data you may want to include with your package. -This is a place where non-code related additional information (such as data files, molecular structures, etc.) can -go that you want to ship alongside your code. - -Please note that it is not recommended to place large files in your git directory. If your project requires files larger -than a few megabytes in size it is recommended to host these files elsewhere. This is especially true for binary files -as the `git` structure is unable to correctly take updates to these files and will store a complete copy of every version -in your `git` history which can quickly add up. As a note most `git` hosting services like GitHub have a 1 GB per repository -cap. - -## Including package data - -Modify your package's `setup.py` file and the `setup()` command. Include the -[`package_data`](http://setuptools.readthedocs.io/en/latest/setuptools.html#basic-use) keyword and point it at the -correct files. \ No newline at end of file diff --git a/pathsimanalysis/data/__init__.py b/pathsimanalysis/data/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/pathsimanalysis/data/files.py b/pathsimanalysis/data/files.py deleted file mode 100644 index 87c4c2f..0000000 --- a/pathsimanalysis/data/files.py +++ /dev/null @@ -1,17 +0,0 @@ -""" -Location of data files -====================== - -Use as :: - - from pathsimanalysis.data.files import * - -""" - -__all__ = [ - "MDANALYSIS_LOGO", # example file of MDAnalysis logo -] - -from pkg_resources import resource_filename - -MDANALYSIS_LOGO = resource_filename(__name__, "mda.txt") diff --git a/pathsimanalysis/data/mda.txt b/pathsimanalysis/data/mda.txt deleted file mode 100644 index 7893f85..0000000 --- a/pathsimanalysis/data/mda.txt +++ /dev/null @@ -1,45 +0,0 @@ - - ▄▄████████▄▄ - ,▓███████████████▄ ____ - ▄███████████████████ ╔D╠╠╠╠╠╠╬φ_ - ▐█████████████████████ ╔╠╠╠╠╠╠╠╠╠╠╠╠▒ - ██████████████████████▌ ╠╠╠╠╠╠╠╠╠╠╠╠╠╠H - ███████████████████████ ╠╠╠╠╠╠╠╠╠╠╠╠╠╠H - ╙██████████████████████ ╠╠╠╠╠╠╠╠╠╠╠╠╠╩ - ╙██████████████████████ ╙╠╠╠╠╠╠╠╠╠╝^ - '██████████████████████_ `'^╙╙^` - `▀███████████▀▀▀███████▄ - `` _╓╗φ@@@φ╗╖,╙▀████▄▄╓,,,▄▄▄▓█████▓▄_ - ,φ▓╬╬╬╬╬╬╬╬╬╬╬╬▒,╙█████████████████████▓_ - Æ╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬▌ ▀██████████████████████ - _,,_ ╣╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬▓ ╚██████████████████████ - ╔╠╠╠╠╠╬_ [╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬L ██████████████████████▌ - ╠╠╠╠╠╠╠H ╟╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬▒ ███████████████████████ - `╚╠╠╠╠╙ ╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬L ██████████████████████▌ - [╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╩ ███████████████████████ - é╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╜ ██████████████████████▀ - _╗▓╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╝╙,▓████████████████████▀" - _╓╗╗╗╗╗╖,__ __╓φ▓╬╬╝╜"▄▄▄▄▄▄▄▄▄╠╙╙^""▄▄▓████▀" └╙╙▀▀▀"" - ╔Æ╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╜╓▓█████████████████████▀ - ╗╣╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╩ ██████████████████████▀ - ╣╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬▌ ██████████████████████Ñ ╔@DD╠DK╓ - [╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬ ╟██████████████████████ ╒╠╠╠╠╠╠╠╠╠╠ - ╢╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬ ██████████████████████▌ ╚╠╠╠╠╠╠╠╠╠╠H - ╚╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬ ╟█████████████████████` '╠╠╠╠╠╠╠╠╠╠ - ╫╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬▒ ████████████████████▌ `╚╠╠╠╠╠╝╙ - ╚╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬W ██████████████████▀ - ╙╣╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬▓╖╙▀█████████████▀ - "╙╨╝╝╝╨╙^`` `"╙╝╬╬▓W╓╙▀▀▀▀▀▀▀▀"_,,,__ - _╓╦φφφφ╦,_ '╝╬╬╬╬▓▒▒▒▒▓╬╬╬╬╬╬╬╬╬▓╗_ - ,φ╠╠╠╠╠╠╠╠╠╠╠D╦_ `╣╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬▓, - ╔╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╦ ╟╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬▄ - j╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠H ╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬L - ╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠ ╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬▓ - ╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠ ║╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬▌ - ²╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠ ╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬ - '╠╠╠╠╠╠╠╠╠╠╠╠╠╠╠╩ `╣╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬╬▓ - '╚╠╠╠╠╠╠╠╠╠╝╙ ╙╣╬╬╬╬╬╬╬╬╬╬╬╬╬╝^ - ````` `╙╨╝╝╝╝╝╨╙` - ---- -asciiart.club diff --git a/pathsimanalysis/psa.py b/pathsimanalysis/psa.py index eed53c1..3f4b188 100644 --- a/pathsimanalysis/psa.py +++ b/pathsimanalysis/psa.py @@ -25,10 +25,6 @@ Calculating path similarity --- :mod:`pathsimanalysis.psa` ========================================================================== -:Author: Sean Seyler -:Year: 2015 -:Copyright: GNU Public License v3 - .. versionadded:: 0.10.0 The module contains code to calculate the geometric similarity of trajectories @@ -88,11 +84,11 @@ .. attribute:: u_original - :class:`MDAnalysis.Universe` object with a trajectory + :class:`~MDAnalysis.Universe` object with a trajectory .. attribute:: u_reference - :class:`MDAnalysis.Universe` object containing a reference structure + :class:`~MDAnalysis.Universe` object containing a reference structure .. attribute:: select @@ -112,7 +108,7 @@ .. attribute:: u_fitted - :class:`MDAnalysis.Universe` object with the fitted trajectory + :class:`~MDAnalysis.Universe` object with the fitted trajectory .. attribute:: path @@ -386,7 +382,7 @@ def hausdorff(P, Q): >>> import MDAnalysis as mda >>> import numpy >>> from MDAnalysis.tests.datafiles import PSF, DCD - >>> from MDAnalysis.analysis import psa + >>> import pathsimanalysis as psa >>> u = mda.Universe(PSF,DCD) >>> mid = int(len(u.trajectory)/2) >>> ca = u.select_atoms('name CA') @@ -453,7 +449,7 @@ def hausdorff_wavg(P, Q): >>> import MDAnalysis as mda >>> from MDAnalysis import Universe >>> from MDAnalysis.tests.datafiles import PSF, DCD - >>> from MDAnalysis.analysis import psa + >>> import pathsimanalysis as psa >>> u = mda.Universe(PSF,DCD) >>> mid = int(len(u.trajectory)/2) >>> ca = u.select_atoms('name CA') @@ -511,7 +507,7 @@ def hausdorff_avg(P, Q): >>> import MDAnalysis as mda >>> from MDAnalysis.tests.datafiles import PSF, DCD - >>> from MDAnalysis.analysis import psa + >>> import pathsimanalysis as psa >>> u = mda.Universe(PSF,DCD) >>> mid = int(len(u.trajectory)/2) >>> ca = u.select_atoms('name CA') @@ -610,7 +606,7 @@ def discrete_frechet(P, Q): >>> import MDAnalysis as mda >>> import numpy as np >>> from MDAnalysis.tests.datafiles import PSF, DCD - >>> from MDAnalysis.analysis import psa + >>> import pathsimanalysis as psa >>> u = mda.Universe(PSF,DCD) >>> mid = int(len(u.trajectory)/2) >>> ca = u.select_atoms('name CA') @@ -1494,7 +1490,7 @@ def run_pairs_analysis(self, **kwargs): indexed according to distance vector convention (i.e., element *(i,j)* in distance matrix representation corresponds to element :math:`s=N*i+j-(i+1)*(i+2)` in distance vector representation, which is - the :math:`s^\text{th}` comparison). For each unique pair of paths, the + the :math:`s`:sup:`th` comparison). For each unique pair of paths, the nearest neighbors for that pair can be stored in :attr:`NN` and the Hausdorff pair in :attr:`HP`. :attr:`PP` stores the full information of Hausdorff pairs analysis that is available for each pair of path, diff --git a/pathsimanalysis/tests/conftest.py b/pathsimanalysis/tests/conftest.py deleted file mode 100644 index 458353c..0000000 --- a/pathsimanalysis/tests/conftest.py +++ /dev/null @@ -1,20 +0,0 @@ -""" -Global pytest fixtures -""" - -# Use this file if you need to share any fixtures -# across multiple modules -# More information at -# https://docs.pytest.org/en/stable/how-to/fixtures.html#scope-sharing-fixtures-across-classes-modules-packages-or-session - -import pytest - -from pathsimanalysis.data.files import MDANALYSIS_LOGO - - -@pytest.fixture -def mdanalysis_logo_text() -> str: - """Example fixture demonstrating how data files can be accessed""" - with open(MDANALYSIS_LOGO, "r", encoding="utf8") as f: - logo_text = f.read() - return logo_text diff --git a/pathsimanalysis/tests/utils.py b/pathsimanalysis/tests/utils.py deleted file mode 100644 index 63a2e16..0000000 --- a/pathsimanalysis/tests/utils.py +++ /dev/null @@ -1,77 +0,0 @@ -from typing import Tuple - -import MDAnalysis as mda -from MDAnalysis.coordinates.memory import MemoryReader -import numpy as np - - -def make_Universe( - extras: Tuple[str] = tuple(), - size: Tuple[int, int, int] = (125, 25, 5), - n_frames: int = 0, - velocities: bool = False, - forces: bool = False -) -> mda.Universe: - """Make a dummy reference Universe - - Allows the construction of arbitrary-sized Universes. Suitable for - the generation of structures for output. - - Preferable for testing core components because: - * minimises dependencies within the package - * very fast compared to a "real" Universe - - Parameters - ---------- - extras : tuple of strings, optional - extra attributes to add to Universe: - u = make_Universe(('masses', 'charges')) - Creates a lightweight Universe with only masses and charges. - size : tuple of int, optional - number of elements of the Universe (n_atoms, n_residues, n_segments) - n_frames : int - If positive, create a fake Reader object attached to Universe - velocities : bool, optional - if the fake Reader provides velocities - force : bool, optional - if the fake Reader provides forces - - Returns - ------- - MDAnalysis.core.universe.Universe object - - """ - - n_atoms, n_residues, n_segments = size - trajectory = n_frames > 0 - u = mda.Universe.empty( - # topology things - n_atoms=n_atoms, - n_residues=n_residues, - n_segments=n_segments, - atom_resindex=np.repeat( - np.arange(n_residues), n_atoms // n_residues), - residue_segindex=np.repeat( - np.arange(n_segments), n_residues // n_segments), - # trajectory things - trajectory=trajectory, - velocities=velocities, - forces=forces, - ) - if extras is None: - extras = [] - for ex in extras: - u.add_TopologyAttr(ex) - - if trajectory: - pos = np.arange(3 * n_atoms * n_frames).reshape(n_frames, n_atoms, 3) - vel = pos + 100 if velocities else None - fcs = pos + 10000 if forces else None - reader = MemoryReader( - pos, - velocities=vel, - forces=fcs, - ) - u.trajectory = reader - - return u