diff --git a/README.md b/README.md index 4373275..31142b7 100644 --- a/README.md +++ b/README.md @@ -7,23 +7,23 @@ mda-openbabel-converter | **Status** | [![GH Actions Status][badge_actions]][url_actions] [![codecov][badge_codecov]][url_codecov] | | **Community** | [![License: GPL v2][badge_license]][url_license] [![Powered by MDAnalysis][badge_mda]][url_mda]| -[badge_actions]: https://github.com/lunamorrow/mda_openbabel_converter/actions/workflows/gh-ci.yaml/badge.svg -[badge_codecov]: https://codecov.io/gh/lunamorrow/mda_openbabel_converter/branch/main/graph/badge.svg -[badge_commits_since]: https://img.shields.io/github/commits-since/lunamorrow/mda_openbabel_converter/latest -[badge_docs]: https://readthedocs.org/projects/mda_openbabel_converter/badge/?version=latest +[badge_actions]: https://github.com/MDAnalysis/mda-openbabel-converter/actions/workflows/gh-ci.yaml/badge.svg +[badge_codecov]: https://codecov.io/gh/MDAnalysis/mda-openbabel-converter/branch/main/graph/badge.svg +[badge_commits_since]: https://img.shields.io/github/commits-since/MDAnalysis/mda-openbabel-converter/latest +[badge_docs]: https://mda-openbabel-converter.readthedocs.io/en/latest/ [badge_license]: https://img.shields.io/badge/License-GPLv2-blue.svg [badge_mda]: https://img.shields.io/badge/powered%20by-MDAnalysis-orange.svg?logoWidth=16&logo=data:image/x-icon;base64,AAABAAEAEBAAAAEAIAAoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJD+XwCY/fEAkf3uAJf97wGT/a+HfHaoiIWE7n9/f+6Hh4fvgICAjwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACT/yYAlP//AJ///wCg//8JjvOchXly1oaGhv+Ghob/j4+P/39/f3IAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJH8aQCY/8wAkv2kfY+elJ6al/yVlZX7iIiI8H9/f7h/f38UAAAAAAAAAAAAAAAAAAAAAAAAAAB/f38egYF/noqAebF8gYaagnx3oFpUUtZpaWr/WFhY8zo6OmT///8BAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgICAn46Ojv+Hh4b/jouJ/4iGhfcAAADnAAAA/wAAAP8AAADIAAAAAwCj/zIAnf2VAJD/PAAAAAAAAAAAAAAAAICAgNGHh4f/gICA/4SEhP+Xl5f/AwMD/wAAAP8AAAD/AAAA/wAAAB8Aov9/ALr//wCS/Z0AAAAAAAAAAAAAAACBgYGOjo6O/4mJif+Pj4//iYmJ/wAAAOAAAAD+AAAA/wAAAP8AAABhAP7+FgCi/38Axf4fAAAAAAAAAAAAAAAAiIiID4GBgYKCgoKogoB+fYSEgZhgYGDZXl5e/m9vb/9ISEjpEBAQxw8AAFQAAAAAAAAANQAAADcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAjo6Mb5iYmP+cnJz/jY2N95CQkO4pKSn/AAAA7gAAAP0AAAD7AAAAhgAAAAEAAAAAAAAAAACL/gsAkv2uAJX/QQAAAAB9fX3egoKC/4CAgP+NjY3/c3Nz+wAAAP8AAAD/AAAA/wAAAPUAAAAcAAAAAAAAAAAAnP4NAJL9rgCR/0YAAAAAfX19w4ODg/98fHz/i4uL/4qKivwAAAD/AAAA/wAAAP8AAAD1AAAAGwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALGxsVyqqqr/mpqa/6mpqf9KSUn/AAAA5QAAAPkAAAD5AAAAhQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADkUFBSuZ2dn/3V1df8uLi7bAAAATgBGfyQAAAA2AAAAMwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB0AAADoAAAA/wAAAP8AAAD/AAAAWgC3/2AAnv3eAJ/+dgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA9AAAA/wAAAP8AAAD/AAAA/wAKDzEAnP3WAKn//wCS/OgAf/8MAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIQAAANwAAADtAAAA7QAAAMAAABUMAJn9gwCe/e0Aj/2LAP//AQAAAAAAAAAA -[badge_release]: https://img.shields.io/github/release-pre/lunamorrow/mda_openbabel_converter.svg -[url_actions]: https://github.com/lunamorrow/mda_openbabel_converter/actions?query=branch%3Amain+workflow%3Agh-ci -[url_codecov]: https://codecov.io/gh/lunamorrow/mda_openbabel_converter/branch/main -[url_docs]: https://mda_openbabel_converter.readthedocs.io/en/latest/?badge=latest -[url_latest_release]: https://github.com/lunamorrow/mda_openbabel_converter/releases +[badge_release]: https://img.shields.io/github/release-pre/MDAnalysis/mda-openbabel-converter.svg +[url_actions]: https://github.com/MDAnalysis/mda-openbabel-converter/actions?query=branch%3Amain+workflow%3Agh-ci +[url_codecov]: https://codecov.io/gh/MDAnalysis/mda-openbabel-converter/branch/main +[url_docs]: https://mda-openbabel-converter.readthedocs.io/en/latest/?badge=latest +[url_latest_release]: https://github.com/MDAnalysis/mda-openbabel-converter/releases [url_license]: https://www.gnu.org/licenses/gpl-2.0 [url_mda]: https://www.mdanalysis.org A package to convert between MDAnalysis and OpenBabel Objects -mda-openbabel-converter is bound by a [Code of Conduct](https://github.com/lunamorrow/mda_openbabel_converter/blob/main/CODE_OF_CONDUCT.md). +mda-openbabel-converter is bound by a [Code of Conduct](https://github.com/lunamorrow/mda-openbabel-converter/blob/main/CODE_OF_CONDUCT.md). ### Installation @@ -34,6 +34,10 @@ If possible, we strongly recommend that you use Below we provide instructions both for `conda` and for `pip`. +### Documentation + +The docs can be found [here] (https://mda-openbabel-converter.readthedocs.io/en/latest/) + #### With conda Ensure that you have [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) installed. @@ -41,15 +45,15 @@ Ensure that you have [conda](https://docs.conda.io/projects/conda/en/latest/user Create a virtual environment and activate it: ``` -conda create --name mda_openbabel_converter -conda activate mda_openbabel_converter +conda create --name mda-openbabel-converter +conda activate mda-openbabel-converter ``` Install the development and documentation dependencies: ``` -conda env update --name mda_openbabel_converter --file devtools/conda-envs/test_env.yaml -conda env update --name mda_openbabel_converter --file docs/requirements.yaml +conda env update --name mda-openbabel-converter --file devtools/conda-envs/test_env.yaml +conda env update --name mda-openbabel-converter --file docs/requirements.yaml ``` Build this package from source: @@ -87,8 +91,8 @@ pip install ".[test,doc]" ### Copyright -The mda-openbabel-converter source code is hosted at https://github.com/lunamorrow/mda_openbabel_converter -and is available under the GNU General Public License, version 2 (see the file [LICENSE](https://github.com/lunamorrow/mda_openbabel_converter/blob/main/LICENSE)). +The mda-openbabel-converter source code is hosted at https://github.com/lunamorrow/mda-openbabel-converter +and is available under the GNU General Public License, version 2 (see the file [LICENSE](https://github.com/lunamorrow/mda-openbabel-converter/blob/main/LICENSE)). Copyright (c) 2024, Luna Morrow diff --git a/docs/source/autosummary/mda_openbabel_converter.OpenBabel.rst b/docs/source/autosummary/mda_openbabel_converter.OpenBabel.rst new file mode 100644 index 0000000..be61e7d --- /dev/null +++ b/docs/source/autosummary/mda_openbabel_converter.OpenBabel.rst @@ -0,0 +1,13 @@ +mda\_openbabel\_converter.OpenBabel +=================================== + +.. automodule:: mda_openbabel_converter.OpenBabel + + + .. rubric:: Classes + + .. autosummary:: + + OpenBabelConverter + OpenBabelReader + \ No newline at end of file diff --git a/docs/source/autosummary/mda_openbabel_converter.OpenBabelParser.rst b/docs/source/autosummary/mda_openbabel_converter.OpenBabelParser.rst new file mode 100644 index 0000000..5963470 --- /dev/null +++ b/docs/source/autosummary/mda_openbabel_converter.OpenBabelParser.rst @@ -0,0 +1,12 @@ +mda\_openbabel\_converter.OpenBabelParser +========================================= + +.. automodule:: mda_openbabel_converter.OpenBabelParser + + + .. rubric:: Classes + + .. autosummary:: + + OpenBabelParser + \ No newline at end of file diff --git a/docs/source/autosummary/mda_openbabel_converter.data.files.rst b/docs/source/autosummary/mda_openbabel_converter.data.files.rst new file mode 100644 index 0000000..20949f0 --- /dev/null +++ b/docs/source/autosummary/mda_openbabel_converter.data.files.rst @@ -0,0 +1,6 @@ +mda\_openbabel\_converter.data.files +==================================== + +.. automodule:: mda_openbabel_converter.data.files + + \ No newline at end of file diff --git a/docs/source/autosummary/mda_openbabel_converter.data.rst b/docs/source/autosummary/mda_openbabel_converter.data.rst new file mode 100644 index 0000000..4f01a42 --- /dev/null +++ b/docs/source/autosummary/mda_openbabel_converter.data.rst @@ -0,0 +1,13 @@ +mda\_openbabel\_converter.data +============================== + +.. automodule:: mda_openbabel_converter.data + + +.. rubric:: Modules + +.. autosummary:: + :toctree: + :recursive: + + files diff --git a/docs/source/autosummary/mda_openbabel_converter.rst b/docs/source/autosummary/mda_openbabel_converter.rst new file mode 100644 index 0000000..849457b --- /dev/null +++ b/docs/source/autosummary/mda_openbabel_converter.rst @@ -0,0 +1,15 @@ +mda\_openbabel\_converter +========================= + +.. automodule:: mda_openbabel_converter + + +.. rubric:: Modules + +.. autosummary:: + :toctree: + :recursive: + + OpenBabel + OpenBabelParser + data diff --git a/docs/source/conf.py b/docs/source/conf.py index 1259ead..3a1d25f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -193,4 +193,5 @@ intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), "mdanalysis": ("https://docs.mdanalysis.org/stable/", None), + "openbabel": ("https://openbabel.org/", None), } diff --git a/mda_openbabel_converter/OpenBabel.py b/mda_openbabel_converter/OpenBabel.py index ee659cd..2cfa12c 100644 --- a/mda_openbabel_converter/OpenBabel.py +++ b/mda_openbabel_converter/OpenBabel.py @@ -1,5 +1,46 @@ -""" -Documentation... +"""OpenBabel molecule I/O --- :mod:`mda_openbabel_converter.OpenBabel` +====================================================================== + +Read coordinates data from an +`OpenBabel `_ +:class:`openbabel.openbabel.OBMol` with :class:`OpenBabelReader` into an +MDAnalysis Universe. Convert it back to a :class:`openbabel.openbabel.OBMol` +with :class:`OpenBabelConverter`. + +Example +------- + +To read an OpenBabel OBMol and then convert the AtomGroup back to an OpenBabel +OBMol:: + + >>> from openbabel import openbabel as ob + >>> import MDAnalysis as mda + >>> obconversion = ob.OBConversion() + >>> obconversion.SetInFormat("pdb") + >>> mol = ob.OBMol() + >>> obconversion.ReadFile(mol, "1crn.pdb") + >>> u = mda.Universe(mol) + >>> u + + >>> u.trajectory + + >>> u.atoms.convert_to("OPENBABEL") + + + +.. warning:: + The OpenBabel converter is currently *experimental* and may not work as + expected for all molecules. + + +Classes +------- + +.. autoclass:: OpenBabelReader + :members: + +.. autoclass:: OpenBabelConverter + :members: """ import MDAnalysis as mda @@ -22,9 +63,14 @@ class OpenBabelReader(MemoryReader): """ + Coordinate reader for OpenBabel. + Inherits from MemoryReader and converts OpenBabel OBMol Coordinates to a MDAnalysis Trajectory which is used to build a Universe. This reader - does not work in the reverse direction. + does NOT work in the reverse direction. + + See :class:`mda_openbabel_converter.OpenBabel.OpenBabelConverter` for + MDAnalysis Universe to OpenBabel OBMol conversion. """ format = 'OPENBABEL' @@ -77,7 +123,11 @@ def __init__(self, filename: OBMol, **kwargs): class OpenBabelConverter(ConverterBase): """ - Convert a MDAnalysis AtomGroup to an OpenBabel OBMol + Inherits from ConverterBase and converts a MDAnalysis Universe to an + OpenBabel OBMol. This converter does NOT work in the opposite direction. + + See :class:`mda_openbabel_converter.OpenBabelReader` for OpenBabel OBMol + to MDAnalysis Universe conversion. """ def __repr__(self, **kwargs): """ diff --git a/mda_openbabel_converter/OpenBabelParser.py b/mda_openbabel_converter/OpenBabelParser.py index 49b59b3..af4a026 100644 --- a/mda_openbabel_converter/OpenBabelParser.py +++ b/mda_openbabel_converter/OpenBabelParser.py @@ -1,5 +1,24 @@ """ -Documentation... +OpenBabel topology parser --- :mod:`mda_openbabel_converter.OpenBabel` +====================================================================== + +Converts an +`OpenBabel `_ +:class:`openbabel.openbabel.OBMol` into a :class:`MDAnalysis.core.Topology`. + + +See Also +-------- +:mod:`mda_openbabel_converter.OpenBabel` + + +Classes +------- + +.. autoclass:: OpenBabelParser + :members: + :inherited-members: + """ import MDAnalysis as mda @@ -46,9 +65,84 @@ class OpenBabelParser(TopologyReaderBase): """ + For OpenBabel structure + Inherits from TopologyReaderBase and converts an OpenBabel OBMol to a MDAnalysis Topology or adds it to a pre-existing Topology. This parser does not work in the reverse direction. + + For use examples, please see :class:`mda_openbabel_converter.OpenBabel` + + Creates the following Attributes: + - Atomids + - Atomtypes + - Aromaticities + - Elements + - Masses + - Bonds + - Resids + - Resnums + - Segids + + Depending on OpenBabel's input, the following Attributes might be present: + - Charges + - Resnames + - ICodes + + Guesses the following: + - Atomnames + + Missing Attributes unable to be retrieved from OpenBabel: + - Chiralities + - RSChirality + - Occupancies + - Tempfactors + - ChainIDs + - AltLocs + + Attributes table: + + +---------------------------------------------+-------------------------+ + | OpenBabel attribute | MDAnalysis equivalent | + +=============================================+=========================+ + | | altLocs | + +---------------------------------------------+-------------------------+ + | atom.IsAromatic() | aromaticities | + +---------------------------------------------+-------------------------+ + | | chainIDs | + +---------------------------------------------+-------------------------+ + | atom.GetPartialCharge() | charges | + +---------------------------------------------+-------------------------+ + | GetSymbol(atom.GetAtomicNum()) | elements | + +---------------------------------------------+-------------------------+ + | atom.GetResidue().GetInsertionCode() | icodes | + +---------------------------------------------+-------------------------+ + | atom.GetIdx() | indices | + +---------------------------------------------+-------------------------+ + | atom.GetExactMass() | masses | + +---------------------------------------------+-------------------------+ + | "%s%d" % (GetSymbol(atom.GetAtomicNum()), | names | + | atom.GetIdx()) | | + +---------------------------------------------+-------------------------+ + | | chiralities | + +---------------------------------------------+-------------------------+ + | | occupancies | + +---------------------------------------------+-------------------------+ + | atom.GetResidue().GetName() | resnames | + +---------------------------------------------+-------------------------+ + | atom.GetResidue().GetNum() | resnums | + +---------------------------------------------+-------------------------+ + | | tempfactors | + +---------------------------------------------+-------------------------+ + | atom.GetType() | types | + +---------------------------------------------+-------------------------+ + + Raises + ------ + ValueError + If only some of the atoms have ResidueInfo, from resid.GetNum(), + available + """ format = 'OPENBABEL' @@ -84,7 +178,6 @@ def parse(self, **kwargs): ids = [] atomtypes = [] segids = [] - chainids = [] icodes = [] if mol.Empty(): diff --git a/mda_openbabel_converter/tests/conftest.py b/mda_openbabel_converter/tests/conftest.py index ef71494..d353ac3 100644 --- a/mda_openbabel_converter/tests/conftest.py +++ b/mda_openbabel_converter/tests/conftest.py @@ -2,11 +2,6 @@ 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 mda_openbabel_converter.data.files import MDANALYSIS_LOGO diff --git a/mda_openbabel_converter/tests/test_mda_openbabel_converter.py b/mda_openbabel_converter/tests/test_mda_openbabel_converter.py index 649d911..18be113 100644 --- a/mda_openbabel_converter/tests/test_mda_openbabel_converter.py +++ b/mda_openbabel_converter/tests/test_mda_openbabel_converter.py @@ -1,8 +1,7 @@ """ -Unit and regression test for the mda_openbabel_converter package. +Base tests for the mda_openbabel_converter package. """ -# Import package, test suite, and other packages as needed import mda_openbabel_converter import pytest import sys diff --git a/mda_openbabel_converter/tests/test_openbabel_parser.py b/mda_openbabel_converter/tests/test_openbabel_parser.py index a5dc3aa..597f147 100644 --- a/mda_openbabel_converter/tests/test_openbabel_parser.py +++ b/mda_openbabel_converter/tests/test_openbabel_parser.py @@ -1,4 +1,8 @@ -# Testing OpenBabel and Pybel +""" +Test suite for the OpenBabel Parser that converts an OBMol's attributes to an +MDAnalysis topology, alongside the OpenBabel Reader, that can be used to +construct an MDAnalysis Universe. +""" import MDAnalysis as mda import openbabel diff --git a/mda_openbabel_converter/tests/test_openbabel_reader.py b/mda_openbabel_converter/tests/test_openbabel_reader.py index 5dc3dbc..5092667 100644 --- a/mda_openbabel_converter/tests/test_openbabel_reader.py +++ b/mda_openbabel_converter/tests/test_openbabel_reader.py @@ -1,4 +1,8 @@ -# Testing OpenBabel and Pybel +""" +Test suite for the OpenBabel Reader that converts an OBMol's atom coordinates +to an MDAnalysis topology, alongside the OpenBabel Parser, that can be used to +construct an MDAnalysis Universe. +""" import MDAnalysis as mda import openbabel