diff --git a/.gitignore b/.gitignore index 72d7fb3..25ac1eb 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,12 @@ # PIP stuff *.egg-info # Visual studio code -.vscode \ No newline at end of file +.vscode + +# editor files +*~ + +# generated files +docs/build +docs/source/api/*.rst +build/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..5f7e02d --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,38 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile ghpages + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +# push to this repo's gh-pages (must be named origin and must have a gh-pages branch) + +REPONAME = origin + +ghpages: html + -(ORIGIN_REMOTE_URL=`git config --get remote.$(REPONAME).url`; \ + rev=`git rev-parse --short HEAD`; \ + cd $(BUILDDIR)/$^ \ + && git init \ + && git remote add origin $${ORIGIN_REMOTE_URL} \ + && git fetch --depth 50 origin gh-pages \ + && git reset origin/gh-pages \ + && touch .nojekyll \ + && git add -A . \ + && git diff-index --quiet HEAD -- || git commit -m "updated sphinx docs from $${rev}" \ + && git push -q origin HEAD:gh-pages) + rm -rf $(BUILDDIR)/$^/.git diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst new file mode 100644 index 0000000..0449164 --- /dev/null +++ b/docs/source/_templates/autosummary/module.rst @@ -0,0 +1,61 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + :members: + + {% block attributes %} + {% if attributes %} + .. rubric:: Module Attributes + + .. autosummary:: + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :recursive: +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..b8a1034 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,78 @@ +.. -*- coding: utf-8 -*- + +=============== + API Reference +=============== + +The :program:`propka3` command provides a command-line interface to +PROPKA 3's functionality. It is built on classes and functions in the +:mod:`propka` module. The API of :mod:`propka` is documented here for +developers who might want to directly use the PROPKA 3 code. + +.. Note:: + + The API is still changing and there is currently no guarantee that + it will remain stable between minor releases. + + + +.. currentmodule:: propka + +.. module:: propka + + +Data structures +=============== + +.. autosummary:: + :toctree: api + + atom + bonds + group + conformation_container + molecular_container + + +I/O +=== + +.. autosummary:: + :toctree: api + + input + lib + output + parameters + hybrid36 + ligand_pka_values + run + version + + +Structure processing +==================== + +.. autosummary:: + :toctree: api + + protonate + hydrogens + ligand + + +Calculations +============ + +.. autosummary:: + :toctree: api + + calculations + coupled_groups + determinant + determinants + energy + iterative + vector_algebra + + diff --git a/docs/source/command.rst b/docs/source/command.rst new file mode 100644 index 0000000..48cd3ae --- /dev/null +++ b/docs/source/command.rst @@ -0,0 +1,131 @@ +.. -*- coding: utf-8 -*- + +.. _propka3-command: + +============================ + :program:`propka3` command +============================ + +PROPKA predicts the pKa values of ionizable groups in proteins and +protein-ligand complexes based in the 3D structure. The +:program:`propka3` command has the following options:: + + propka3 [-h] [-f FILENAMES] [-r REFERENCE] [-c CHAINS] [-i TITRATE_ONLY] [-t THERMOPHILES] [-a ALIGNMENT] [-m MUTATIONS] + [-v VERSION_LABEL] [-p PARAMETERS] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-o PH] [-w WINDOW WINDOW WINDOW] + [-g GRID GRID GRID] [--mutator MUTATOR] [--mutator-option MUTATOR_OPTIONS] [-d] [-l] [-k] [-q] [--generate-propka-input] + [--protonate-all] + input_pdb + + +.. program:: propka3 + +.. option:: input_pdb + + read data from file + +.. option:: -h, --help + + show this help message and exit + +.. option:: -f FILENAMES, --file FILENAMES + + read data from , i.e. is added to + arguments (default: []) + +.. option:: -r REFERENCE, --reference REFERENCE + + setting which reference to use for stability calculations + [neutral/low-pH] (default: neutral) + +.. option:: -c CHAINS, --chain CHAINS + + creating the protein with only a specified chain. Specify + " " for chains without ID [all] (default: None) + +.. option:: -i TITRATE_ONLY, --titrate_only TITRATE_ONLY + + Treat only the specified residues as titratable. Value + should be a comma-separated list of "chain:resnum" + values; for example: ``-i "A:10,A:11"`` (default: None) + +.. option:: -t THERMOPHILES, --thermophile THERMOPHILES + + defining a thermophile filename; usually used in + 'alignment-mutations' (default: None) + +.. option:: -a ALIGNMENT, --alignment ALIGNMENT + + alignment file connecting and + [.pir] (default: None) + +.. option:: -m MUTATIONS, --mutation MUTATIONS + + specifying mutation labels which is used to modify + according to, e.g. N25R/N181D (default: None) + +.. option:: -v VERSION_LABEL, --version VERSION_LABEL + + specifying the sub-version of propka [Jan15/Dec19] + (default: Jan15) + +.. option:: -p PARAMETERS, --parameters PARAMETERS + + set the parameter file (default: + /propka/propka/propka.cfg) + +.. option:: --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL} + + logging level verbosity (default: INFO) + +.. option:: -o PH, --pH PH + + setting pH-value used in e.g. stability calculations + (default: 7.0) + +.. option:: -w WINDOW WINDOW WINDOW, --window WINDOW WINDOW WINDOW + + setting the pH-window to show e.g. stability profiles + (default: (0.0, 14.0, 1.0)) + +.. option:: -g GRID GRID GRID, --grid GRID GRID GRID + + setting the pH-grid to calculate e.g. stability related + properties (default: (0.0, 14.0, 0.1)) + +.. option:: --mutator MUTATOR + + setting approach for mutating + [alignment/scwrl/jackal] (default: None) + +.. option:: --mutator-option MUTATOR_OPTIONS + + setting property for mutator [e.g. type="side-chain"] + (default: None) + +.. option:: -d, --display-coupled-residues + + Displays alternative pKa values due to coupling of + titratable groups (default: False) + +.. option:: -l, --reuse-ligand-mol2-files + + Reuses the ligand mol2 files allowing the user to alter + ligand bond orders (default: False) + +.. option:: -k, --keep-protons + + Keep protons in input file (default: False) + +.. option:: -q, --quiet + + suppress non-warning messages (default: None) + +.. option:: --generate-propka-input + + Generate a PROPKA input file (default: False) + +.. option:: --protonate-all + + Protonate all atoms (will not influence pKa calculation) + (default: False) + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..1ef14ee --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,75 @@ +# -*- coding: utf-8 -*- +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +# make sure sphinx always uses the current branch +sys.path.insert(0, os.path.abspath('../..')) + +# https://sphinx-rtd-theme.readthedocs.io/en/stable/ +import sphinx_rtd_theme + + +# -- Project information ----------------------------------------------------- + +project = 'PROPKA 3' +copyright = '2020, Jan H. Jensen, Chresten R. Søndergaard, Mats H. M. Olsson, Michał Rostkowski, Nathan A. Baker, Matvey Adzhigirey, Oliver Beckstein, Jimmy Charnley Kromann, Mike Beachy, Toni G, Thomas Holder' +author = 'Jan H. Jensen, Chresten R. Søndergaard, Mats H. M. Olsson, Michał Rostkowski, Nathan A. Baker, Matvey Adzhigirey, Oliver Beckstein, Jimmy Charnley Kromann, Mike Beachy, Toni G, Thomas Holder' + +# The full version, including alpha/beta/rc tags +release = '3.2.0' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', + 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', + 'sphinx.ext.napoleon', 'sphinx.ext.todo', + 'sphinx.ext.autosummary', +## 'sphinx_sitemap', + 'sphinx_rtd_theme'] + +mathjax_path = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML' + +# for sitemap with https://github.com/jdillard/sphinx-sitemap +# change if we put it under a custom domain; for right now, assume RTD +##site_url = "https://propka.readthedocs.io" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html +# We use a customized _templates/autosummary/module.rst to document members, too. +autosummary_generate = True +autosummary_imported_members = False +autosummary_generate_overwrite = True + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# 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'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..72f19b3 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,91 @@ +.. -*- coding: utf-8 -*- +.. PROPKA 3 documentation master file, created by + sphinx-quickstart on Fri Jun 19 11:12:18 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. |pKa| replace:: :math:`\text{p}K_\text{a}` + +==================================== +PROPKA 3: Heuristic |pKa| prediction +==================================== + +:Release: |release| +:Date: |today| + + +PROPKA 3 predicts the |pKa| values of ionizable groups in proteins +[Sondergaard2011]_ and protein-ligand complexes based on the 3D +structure [Olsson2011]_. + +This package installs the :ref:`propka3 command ` and +the :mod:`propka` Python package. + + +License and source code +======================= + +PROPKA 3 is released under the `GNU Lesser General Public License v2.1`_ (see the +files *LICENSE* in the repository for details). + +Source code is available in the public GitHub repository +https://github.com/jensengroup/propka. + + + +Getting help +============ + +Please report *bugs and feature requests* for PROPKA through the +`Issue Tracker`_. + + + +Contributing +============ + +PROPKA welcomes new contributions. To contribute code, submit a *pull +request* against the master branch in the `propka repository`_. + + +Citation +======== + +If you use PROPKA 3 in published work please cite [Sondergaard2011]_ and [Olsson2011]_. + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + +.. links + +.. _`GNU Lesser General Public License v2.1`: + https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html +.. _propka repository: https://github.com/jensengroup/propka +.. _issue tracker: https://github.com/jensengroup/propka/issues + + +.. Hide the contents from the front page because they are already in +.. the side bar in the rtd sphinx style + +.. Contents +.. ======== + + +.. toctree:: + :maxdepth: 3 + :numbered: + :hidden: + + installation + quickstart + command + api + references + + diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..fe9f095 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,52 @@ +.. -*- coding: utf-8 -*- + +============== + Installation +============== + + +PROPKA 3 requires Python 3.6 or higher. Additional requirements are +specified in the :file:`requirements.txt` file and automatically satisfied +when installing with pip_. + + +``pip``-based installation +========================== + +The easiest way to install a release of PROPKA 3 is from the `PyPI archive`_ with the command + +.. code-block:: bash + + pip install --upgrade propka + + +This installation will install the :mod:`propka` Python module and the +:program:`propka3` executable script. As always, a virtual environment (e.g., via +`virtualenv`_) is recommended when installing packages. + +Source-based installation +========================= + +The source code can be installed by cloning the `repository`_ or +unpacking from a source code archive and running + +.. code-block:: bash + + pip install . + +in the source directory. + +For the purposes of testing or development, you may prefer to install +PROPKA as an editable module via pip_ by running + +.. code-block:: bash + + pip install -e . + +in the source directory. + + +.. _pip: https://pip.pypa.io/ +.. _PyPI archive: https://pypi.org/project/PROPKA/ +.. _virtualenv: https://pypi.org/project/virtualenv/ +.. _repository: https://github.com/jensengroup/propka diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 0000000..8b80dfe --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,194 @@ +.. -*- coding: utf-8 -*- + + + +.. |pKa| replace:: :math:`\text{p}K_\text{a}` + +================== + Quickstart Guide +================== + +PROPKA can be used either via the installed script :program:`propka3` +or as a Python module. When using the :ref:`propka3-command`, use + +.. code-block:: bash + + propka3 FILENAME + +As a module (:mod:`propka`), also provide the input filename + +.. code-block:: bash + + python -m propka FILENAME + +In both cases, additional options may be added, as described in more +detail for the :ref:`propka3-command`. + + +Predicting protein residue |pKa| values +======================================= + +Most users run PROPKA by invoking the :program:`propka3` program with +a PDB file as its argument; e.g., for PDB 1HPX_ (HIV-1 protease +complexed with the inhibitor KNI-272) + +.. code-block:: bash + + propka3 1hpx.pdb + +In this example, |pKa| values of titratable protein residues and +titratable groups of the inhibitor KNI are calculated. + +The output looks similar to the following (many lines omitted as +"..."). It is also contained in the output file :file:`1hpx.pka` that +is automatically written:: + + + propka3.2 2020-06-19 + ... + ... + Found NAR group: 1530- N1 900-KNI (B) [ 7.907 1.459 5.427] N + Found O3 group: 1531- O1 900-KNI (B) [ 5.235 3.791 9.082] O + Found O2 group: 1532- O3 900-KNI (B) [ 3.327 4.297 11.852] O + Found NAM group: 1533- N2 900-KNI (B) [ 3.955 2.384 10.893] N + Found O2 group: 1539- O6 900-KNI (B) [ 3.758 -0.629 12.111] O + Found NAM group: 1541- N3 900-KNI (B) [ 4.496 0.982 13.492] N + Found O2 group: 1542- O4 900-KNI (B) [ 6.324 -1.234 17.045] O + Found OH group: 1548- O2 900-KNI (B) [ 4.949 0.934 16.427] O + Found O2 group: 1559- O5 900-KNI (B) [ 6.746 -3.574 14.588] O + Found NAM group: 1560- N5 900-KNI (B) [ 7.637 -4.575 16.403] N + ------------------------------------------------------------------------------------------------------- + + + Calculating pKas for Conformation container 1A with 1878 atoms and 480 groups + ------------------------------------------------------------------------------------------------------- + + --------- ----- ------ --------------------- -------------- -------------- -------------- + DESOLVATION EFFECTS SIDECHAIN BACKBONE COULOMBIC + RESIDUE pKa BURIED REGULAR RE HYDROGEN BOND HYDROGEN BOND INTERACTION + --------- ----- ------ --------- --------- -------------- -------------- -------------- + + ASP 25 A 5.07* 100 % 4.30 617 0.19 0 -0.85 KNI O4 B -0.63 GLY 27 A 0.07 ASP 29 A + ASP 25 A -0.85 KNI O2 B -0.09 ALA 28 A 0.00 XXX 0 X + ASP 25 A -0.84 ASP 25 B -0.04 GLY 27 B 0.00 XXX 0 X + + ASP 29 A 3.11 50 % 1.20 420 0.13 0 -0.68 ARG 87 A 0.00 XXX 0 X -0.04 LYS 45 A + ASP 29 A -0.28 ARG 8 B 0.00 XXX 0 X -0.47 ARG 87 A + ASP 29 A 0.00 XXX 0 X 0.00 XXX 0 X -0.54 ARG 8 B + + ASP 30 A 4.62 59 % 1.30 446 0.00 0 -0.11 LYS 45 A 0.00 XXX 0 X -0.07 ARG 87 A + ASP 30 A 0.00 XXX 0 X 0.00 XXX 0 X -0.01 ARG 8 B + ASP 30 A 0.00 XXX 0 X 0.00 XXX 0 X 0.29 ASP 29 A + ASP 30 A 0.00 XXX 0 X 0.00 XXX 0 X -0.57 LYS 45 A + + ASP 60 A 2.55 0 % 0.41 249 0.00 0 -0.40 THR 74 A 0.00 XXX 0 X -0.02 LYS 45 A + ASP 60 A -0.85 LYS 43 A 0.00 XXX 0 X -0.38 LYS 43 A + ... + ... + ... + ARG 87 B 12.28 45 % -1.40 407 0.00 0 0.77 ASP 29 B 0.00 XXX 0 X 0.10 ASP 30 B + ARG 87 B 0.00 XXX 0 X 0.00 XXX 0 X -0.19 ARG 8 A + ARG 87 B 0.00 XXX 0 X 0.00 XXX 0 X 0.50 ASP 29 B + + N+ 1 B 8.96 0 % -0.39 235 0.00 0 0.85 C- 99 A 0.00 XXX 0 X 0.07 CYS 67 B + N+ 1 B 0.00 XXX 0 X 0.00 XXX 0 X 0.04 CYS 95 B + N+ 1 B 0.00 XXX 0 X 0.00 XXX 0 X 0.38 C- 99 A + + KNI N1 B 4.60 0 % -0.36 273 0.00 0 0.00 XXX 0 X 0.00 XXX 0 X -0.03 ARG 8 A + + Coupled residues (marked *) were detected.Please rerun PropKa with the --display-coupled-residues + or -d option for detailed information. + + -------------------------------------------------------------------------------------------------------- + SUMMARY OF THIS PREDICTION + Group pKa model-pKa ligand atom-type + ASP 25 A 5.07 3.80 + ASP 29 A 3.11 3.80 + ASP 30 A 4.62 3.80 + ASP 60 A 2.55 3.80 + ASP 25 B 9.28 3.80 + ASP 29 B 1.78 3.80 + ASP 30 B 4.91 3.80 + ASP 60 B 2.13 3.80 + GLU 21 A 4.78 4.50 + GLU 34 A 3.93 4.50 + GLU 35 A 3.65 4.50 + GLU 65 A 3.89 4.50 + GLU 21 B 4.73 4.50 + GLU 34 B 3.36 4.50 + GLU 35 B 4.07 4.50 + GLU 65 B 3.70 4.50 + C- 99 A 2.08 3.20 + C- 99 B 2.11 3.20 + HIS 69 A 6.98 6.50 + HIS 69 B 7.11 6.50 + CYS 67 A 9.41 9.00 + CYS 95 A 11.68 9.00 + CYS 67 B 9.82 9.00 + CYS 95 B 11.61 9.00 + TYR 59 A 9.67 10.00 + TYR 59 B 9.54 10.00 + LYS 14 A 10.43 10.50 + LYS 20 A 10.32 10.50 + LYS 43 A 11.41 10.50 + LYS 45 A 10.54 10.50 + LYS 55 A 10.42 10.50 + LYS 70 A 10.92 10.50 + LYS 14 B 10.55 10.50 + LYS 20 B 11.01 10.50 + LYS 43 B 11.43 10.50 + LYS 45 B 10.47 10.50 + LYS 55 B 10.41 10.50 + LYS 70 B 11.07 10.50 + ARG 8 A 13.96 12.50 + ARG 41 A 12.41 12.50 + ARG 57 A 14.40 12.50 + ARG 87 A 12.35 12.50 + ARG 8 B 12.76 12.50 + ARG 41 B 12.42 12.50 + ARG 57 B 13.73 12.50 + ARG 87 B 12.28 12.50 + N+ 1 A 8.96 8.00 + N+ 1 B 8.96 8.00 + KNI N1 B 4.60 5.00 NAR + + Writing 1hpx.pka + + + +Some of the important contents: + +- The section *Calculating pKas for Conformation container 1A with 1878 atoms and + 480 groups* lists details on the calculations for all ionizable + residues. It indicates the considerations that went into a |pKa| + estimate such as hydrogen bonds and Coulomb interactions. It also + indicates if there is potentially coupling between residues. +- Values with "XXX" placeholders are not calculated (but appear to + maintain the formatting). +- The section *SUMMARY OF THIS PREDICTION* lists the predicted |pKa| + for each residue together with the model |pKa| (the "default" + value). +- Ligand values are labeled with the residue name of the ligand, in + this case "KNI". + + +.. todo:: + + More detailed discussion of output. + + + +Getting help +============ + +A brief list of available options can be obtained by running PROPKA +with no options. A longer list of options and descriptions is +available using the :option:`propka3 --help` option: + +.. code-block:: bash + + propka3 --help + + +.. links +.. _1HPX: https://www.rcsb.org/structure/1HPX diff --git a/docs/source/references.rst b/docs/source/references.rst new file mode 100644 index 0000000..409795a --- /dev/null +++ b/docs/source/references.rst @@ -0,0 +1,23 @@ +.. -*- coding: utf-8 -*- + +============ + References +============ + +.. [Sondergaard2011] C. R. Søndergaard, M. H. M. Olsson, M. Rostkowski, + and J. H. Jensen. Improved treatment of ligands + and coupling effects in empirical calculation and + rationalization of pKa values. *Journal of + Chemical Theory and Computation*, + 7(7):2284–2295, 2011. + doi: `10.1021/ct200133y `_ + + +.. [Olsson2011] M. H. M. Olsson, C. R. Søndergaard, M. Rostkowski, + and J. H. Jensen. PROPKA3: Consistent treat- ment of + internal and surface residues in empirical pKa + predictions. *Journal of Chemical Theory and + Computation*, 7(2):525–537, 2011. + doi: + `10.1021/ct100578z `_ + diff --git a/propka/__init__.py b/propka/__init__.py index 58533d8..04dd572 100644 --- a/propka/__init__.py +++ b/propka/__init__.py @@ -1,6 +1,6 @@ """PROPKA 3 -See https://github.com/jensengroup/propka-3.1 for more information. +See https://github.com/jensengroup/propka for more information. Please cite these PROPKA references in publications: diff --git a/propka/atom.py b/propka/atom.py index fcd6825..afe20c4 100644 --- a/propka/atom.py +++ b/propka/atom.py @@ -1,4 +1,11 @@ -"""Atom class - contains all atom information found in the PDB file""" +""" +Atom +==== + +The :class:`Atom` class contains all atom information found in the PDB file. + +""" + import string from propka.lib import make_tidy_atom_label from . import hybrid36 diff --git a/propka/bonds.py b/propka/bonds.py index c6656df..67e795f 100644 --- a/propka/bonds.py +++ b/propka/bonds.py @@ -1,4 +1,10 @@ -"""PROPKA representation of bonds.""" +""" +Bonds +===== + +PROPKA representation of bonds. + +""" import math import json import pkg_resources diff --git a/propka/calculations.py b/propka/calculations.py index 1c48384..e93e86e 100644 --- a/propka/calculations.py +++ b/propka/calculations.py @@ -1,8 +1,14 @@ -"""PROPKA calculations.""" +""" +Calculations +============ + +Mathematical helper functions. +""" + import math -# Maximum distance used to bound calculations of smallest distance +#: Maximum distance used to bound calculations of smallest distance MAX_DISTANCE = 1e6 diff --git a/propka/conformation_container.py b/propka/conformation_container.py index d1e57ed..e387f6a 100644 --- a/propka/conformation_container.py +++ b/propka/conformation_container.py @@ -1,4 +1,9 @@ -"""Container for molecular conformations""" +""" +Molecular data structures +========================= + +Container data structure for molecular conformations. +""" import functools import propka.ligand from propka.output import make_interaction_map @@ -10,11 +15,12 @@ from propka.group import Group, is_group from propka.lib import info -# A large number that gets multipled with the integer obtained from applying -# ord() to the atom chain ID. Used in calculating atom keys for sorting. +#: A large number that gets multipled with the integer obtained from applying +#: :func:`ord` to the atom chain ID. Used in calculating atom keys for sorting. UNICODE_MULTIPLIER = 1e7 -# A number that gets mutiplied with an atom's residue number. Used in -# calculating keys for atom sorting. + +#: A number that gets mutiplied with an atom's residue number. Used in +#: calculating keys for atom sorting. RESIDUE_MULTIPLIER = 1000 diff --git a/propka/coupled_groups.py b/propka/coupled_groups.py index bb47dfe..2b80861 100644 --- a/propka/coupled_groups.py +++ b/propka/coupled_groups.py @@ -1,4 +1,10 @@ -"""Describe coupling between groups.""" +""" +Coupling between groups +======================= + +Describe and analyze energetic coupling between groups. +""" + import itertools import propka.lib from propka.group import Group diff --git a/propka/determinant.py b/propka/determinant.py index 5370798..03f06d7 100644 --- a/propka/determinant.py +++ b/propka/determinant.py @@ -1,7 +1,18 @@ -"""Holds the Determinant class +""" +Determinant +=========== + +Provides the :class:`Determinant` class. + +.. TODO:: + + It is confusing to have both `determinant.py` and `determinants.py`. + Should these be merged? + +.. SeeAlso:: + - :mod:`propka.determinants` + - :mod:`propka.iterative` -TODO - it is confusing to have both `determinant.py` and `determinants.py`. -Should these be merged? """ diff --git a/propka/determinants.py b/propka/determinants.py index 7dc8ee3..235ab43 100644 --- a/propka/determinants.py +++ b/propka/determinants.py @@ -1,7 +1,17 @@ -"""Functions to manipulate Determinant objects. +""" +Working with Determinants +========================= + +Functions to manipulate :class:`propka.determinant.Determinant` objects. + +.. TODO:: + + It is confusing to have both `determinant.py` and `determinants.py`. + Should these be merged? + +.. SeeAlso:: + :mod:`propka.determinant` -TODO - it is confusing to have both `determinant.py` and `determinants.py`. -Should these be merged? """ import math import propka.iterative diff --git a/propka/energy.py b/propka/energy.py index 631c1fc..6a1bc96 100644 --- a/propka/energy.py +++ b/propka/energy.py @@ -1,4 +1,10 @@ -"""Energy calculations.""" +""" +Energy calculations +=================== + +Energy calculations. + +""" import math from propka.lib import warning from propka.calculations import squared_distance, get_smallest_distance diff --git a/propka/group.py b/propka/group.py index 96c0a30..17af7e3 100644 --- a/propka/group.py +++ b/propka/group.py @@ -1,4 +1,9 @@ -"""Routines and classes for storing groups important to PROPKA calculations.""" +""" +Data structures for groups +========================== + +Routines and classes for storing groups important to PROPKA calculations. +""" import math import propka.ligand import propka.protonate @@ -10,6 +15,7 @@ from propka.lib import info, warning # Constants that start with "UNK_" are a mystery to me UNK_PKA_SCALING = -1.36 PROTONATOR = propka.protonate.Protonate(verbose=False) +#: acids EXPECTED_ATOMS_ACID_INTERACTIONS = { 'COO': {'O': 2}, 'HIS': {'H': 2, 'N': 2}, 'CYS': {'S': 1}, 'TYR': {'O': 1}, 'LYS': {'N': 1}, 'ARG': {'H': 5, 'N': 3}, 'ROH': {'O': 1}, @@ -21,6 +27,7 @@ EXPECTED_ATOMS_ACID_INTERACTIONS = { 'C2N': {'H': 4, 'N': 2}, 'OCO': {'O': 2}, 'N30': {'H': 4, 'N': 1}, 'N31': {'H': 3, 'N': 1}, 'N32': {'H': 2, 'N': 1}, 'N33': {'H': 1, 'N': 1}, 'NP1': {'H': 2, 'N': 1}, 'N1': {'N': 1}} +#: bases EXPECTED_ATOMS_BASE_INTERACTIONS = { 'COO': {'O': 2}, 'HIS': {'N': 2}, 'CYS': {'S': 1}, 'TYR': {'O': 1}, 'LYS': {'N': 1}, 'ARG': {'N': 3}, 'ROH': {'O': 1}, 'AMD': {'O': 1}, diff --git a/propka/hybrid36.py b/propka/hybrid36.py index b1e934a..5112a5e 100644 --- a/propka/hybrid36.py +++ b/propka/hybrid36.py @@ -1,6 +1,13 @@ -"""Provides alternative PDB format that can encode larger atom numbers. +""" +Hybrid36 PDB-like file format +============================= + +`hybrid36`_ is an alternative PDB format that can encode larger atom +numbers. This module provides the :func:`decode` functon to parse the +atom numbers in hybrid36 "PDB" files. + +.. _hybrid36: http://cci.lbl.gov/hybrid_36/ -http://cci.lbl.gov/hybrid_36/ """ import string diff --git a/propka/hydrogens.py b/propka/hydrogens.py index 1427758..f2e00ed 100644 --- a/propka/hydrogens.py +++ b/propka/hydrogens.py @@ -1,4 +1,10 @@ -"""Calculations related to hydrogen placement.""" +""" +Hydrogens +========= + +Calculations related to hydrogen placement. + +""" import math from propka.lib import info from propka.protonate import Protonate diff --git a/propka/input.py b/propka/input.py index b71b96f..8d70a55 100644 --- a/propka/input.py +++ b/propka/input.py @@ -1,4 +1,9 @@ -"""Input routines.""" +""" +Input handling +============== + +Input routines. +""" from pathlib import Path from pkg_resources import resource_filename from propka.lib import protein_precheck diff --git a/propka/iterative.py b/propka/iterative.py index c3f999a..b8eefdb 100644 --- a/propka/iterative.py +++ b/propka/iterative.py @@ -1,6 +1,10 @@ -"""Iterative functions for pKa calculations. +""" +Working with Determinants +========================= + +Iterative functions for pKa calculations. These appear to mostly +involve :class:`propka.determinant.Determinant` instances. -These appear to mostly involve determinants. """ from propka.determinant import Determinant from propka.lib import info, debug diff --git a/propka/lib.py b/propka/lib.py index f7f5774..2655935 100644 --- a/propka/lib.py +++ b/propka/lib.py @@ -1,4 +1,10 @@ -"""Implements many of the main functions used to call PROPKA.""" +""" +Set-up of a PROPKA calculation +============================== + +Implements many of the main functions used to call PROPKA. +""" + import sys import logging import argparse diff --git a/propka/ligand.py b/propka/ligand.py index 3386793..618f105 100644 --- a/propka/ligand.py +++ b/propka/ligand.py @@ -1,8 +1,17 @@ -"""Ligand classes and functions.""" +""" +Ligand atom typing +================== + +This module contains the :func:`assign_sybyl_type` function to analyze +all :class:`propka.atom.Atom` in terms of SYBYL atom types (see +:data:`ALL_SYBYL_TYPES`). + +""" + from propka.calculations import squared_distance from propka.vector_algebra import Vector - +#: SYBYL atom types ALL_SYBYL_TYPES = [ 'C.3', # carbon sp3 'H', # hydrogen @@ -58,7 +67,7 @@ ALL_SYBYL_TYPES = [ 'Mo', # molybdenum 'Sn'] # tin - +#: PROPKA input types PROPKA_INPUT_TYPES = ['1P', '1N', '2P', '2N', 'C3', 'H', 'C2', 'Hsp', 'C1', 'Ht3', 'Car', 'LP', 'Cca', 'Du', 'N3', 'DuC', 'N2', 'Any', 'N1', 'Hal', 'Nar', 'Het', 'Nam', 'Hev', 'Npl', diff --git a/propka/ligand_pka_values.py b/propka/ligand_pka_values.py index 023845d..bc73dda 100644 --- a/propka/ligand_pka_values.py +++ b/propka/ligand_pka_values.py @@ -1,4 +1,14 @@ -"""Ligand pKa values""" +""" +Ligand pKa values from Marvin +============================= + +Ligand pKa values can be obtained from the commercial `Marvin`_ +software (namely, the :program:`cxcalc` and :program:`molconvert` +programs are required). + +.. _Marvin: https://chemaxon.com/products/marvin + +""" import os import subprocess import sys diff --git a/propka/molecular_container.py b/propka/molecular_container.py index d1492ae..5b7e99b 100644 --- a/propka/molecular_container.py +++ b/propka/molecular_container.py @@ -1,4 +1,9 @@ -"""Molecular container for storing all contents of PDB files.""" +""" +PDB molecular container +======================= + +Molecular container for storing all contents of PDB files. +""" import os import propka.version from propka.output import write_propka, write_pka, print_header, print_result diff --git a/propka/output.py b/propka/output.py index 18768f6..b04471e 100644 --- a/propka/output.py +++ b/propka/output.py @@ -1,4 +1,9 @@ -"""Output routines.""" +""" +Output +====== + +Output routines. +""" from datetime import date from propka.lib import info @@ -408,11 +413,11 @@ Complexes. Delphine C. Bas, David M. Rogers and Jan H. Jensen. PROTEINS: Structure, Function, and Bioinformatics 73:765-783 (2008) PROPKA3: Consistent Treatment of Internal and Surface Residues in Empirical -pKa predictions. Mats H.M. Olsson, Chresten R. Sondergard, Michal Rostkowski, -and Jan H. Jensen. Journal of Chemical Theory and Computation, 7(2):525-537 +pKa predictions. Mats H.M. Olsson, Chresten R. Sondergard, Michal Rostkowski, +and Jan H. Jensen. Journal of Chemical Theory and Computation, 7(2):525-537 (2011) -Improved Treatment of Ligands and Coupling Effects in Empirical Calculation +Improved Treatment of Ligands and Coupling Effects in Empirical Calculation and Rationalization of pKa Values. Chresten R. Sondergaard, Mats H.M. Olsson, Michal Rostkowski, and Jan H. Jensen. Journal of Chemical Theory and Computation, (2011) @@ -441,8 +446,8 @@ def get_determinants_header(): """ str_ = """ --------- ----- ------ --------------------- -------------- -------------- -------------- - DESOLVATION EFFECTS SIDECHAIN BACKBONE COULOMBIC - RESIDUE pKa BURIED REGULAR RE HYDROGEN BOND HYDROGEN BOND INTERACTION + DESOLVATION EFFECTS SIDECHAIN BACKBONE COULOMBIC + RESIDUE pKa BURIED REGULAR RE HYDROGEN BOND HYDROGEN BOND INTERACTION --------- ----- ------ --------- --------- -------------- -------------- -------------- """ return str_ diff --git a/propka/parameters.py b/propka/parameters.py index 5b26dee..923c687 100644 --- a/propka/parameters.py +++ b/propka/parameters.py @@ -1,21 +1,37 @@ -"""Holds parameters and settings.""" +""" +Configuration file parameters +============================= + +Holds parameters and settings that can be set in :file:`propka.cfg`. The file format consists of lines of ``keyword value [value ...]``, blank lines, and comment lines (introduced with ``#``). + +The module attributes below list the names and types of all key words +in configuration file. + +""" from propka.lib import info, warning -# names and types of all key words in configuration file +#: matrices MATRICES = ['interaction_matrix'] +#: pari-wise matrices PAIR_WISE_MATRICES = ['sidechain_cutoffs'] +#: :class:`dict` containing numbers NUMBER_DICTIONARIES = [ 'VanDerWaalsVolume', 'charge', 'model_pkas', 'ions', 'valence_electrons', 'custom_model_pkas'] +#: :class:`dict` containing lists LIST_DICTIONARIES = ['backbone_NH_hydrogen_bond', 'backbone_CO_hydrogen_bond'] +#: :class:`dict` containing strings STRING_DICTIONARIES = ['protein_group_mapping'] +#: :class:`list` containing strings STRING_LISTS = [ 'ignore_residues', 'angular_dependent_sidechain_interactions', 'acid_list', 'base_list', 'exclude_sidechain_interactions', 'backbone_reorganisation_list', 'write_out_order'] +#: distances (:class:`float`) DISTANCES = ['desolv_cutoff', 'buried_cutoff', 'coulomb_cutoff1', 'coulomb_cutoff2'] +#: other parameters PARAMETERS = [ 'Nmin', 'Nmax', 'desolvationSurfaceScalingFactor', 'desolvationPrefactor', 'desolvationAllowance', 'coulomb_diel', 'COO_HIS_exception', @@ -27,6 +43,7 @@ PARAMETERS = [ 'remove_penalised_group', 'max_intrinsic_pka_diff', 'min_interaction_energy', 'max_free_energy_diff', 'min_swap_pka_shift', 'min_pka', 'max_pka', 'sidechain_interaction'] +# :class:`str` parameters STRINGS = ['version', 'output_file_tag', 'ligand_typing', 'pH', 'reference'] diff --git a/propka/protonate.py b/propka/protonate.py index bd74894..69f1eb7 100644 --- a/propka/protonate.py +++ b/propka/protonate.py @@ -1,4 +1,12 @@ -"""Protonate a structure.""" +""" +Protonate a structure +===================== + +The :class:`Protonate` processes a +:class:`propka.molecular_container.MolecularContainer` and adds +protons. + +""" import math import propka.bonds import propka.atom diff --git a/propka/run.py b/propka/run.py index 0769715..a012c52 100644 --- a/propka/run.py +++ b/propka/run.py @@ -1,4 +1,15 @@ -"""Entry point for PROPKA script.""" +""" +Script functionality +==================== + +The :mod:`run` module provides a high-level interface to PROPKA 3. + +The :program:`propka3` script consists of the :func:`main` +function. If similar functionality is desired from a Python script +(without having to call the :program:`propka` script itself) then the +:func:`single` function can be used instead. + +""" import logging from propka.lib import loadOptions from propka.input import read_parameter_file, read_molecule_file @@ -30,11 +41,18 @@ def single(pdbfile, optargs=None): Commandline options can be passed as a **list** in *optargs*. - .. rubric:: Example + Example + ------- + Given an input file "protein.pdb", run the equivalent of ``propka3 + --mutation=N25R/N181D -v --pH=7.2 protein.pdb`` as:: + + propka.run.single("protein.pdb", + optargs=["--mutation=N25R/N181D", "-v", "--pH=7.2"]) + + + .. todo:: + Test :func:`single`, not sure if it is correctly processing ``pdbfile``. - :: - single("protein.pdb", optargs=["--mutation=N25R/N181D", "-v", - "--pH=7.2"]) """ optargs = optargs if optargs is not None else [] options = loadOptions(*optargs) diff --git a/propka/vector_algebra.py b/propka/vector_algebra.py index 1303de5..b91bd35 100644 --- a/propka/vector_algebra.py +++ b/propka/vector_algebra.py @@ -1,4 +1,9 @@ -"""Vector algebra for PROPKA.""" +""" +Vector calculations +=================== + +Vector algebra for PROPKA. +""" import math from propka.lib import info, get_sorted_configurations diff --git a/propka/version.py b/propka/version.py index 0eb0737..93f2c65 100644 --- a/propka/version.py +++ b/propka/version.py @@ -1,4 +1,8 @@ -"""Contains version-specific methods and parameters. +""" +Version-based configuration +=========================== + +Contains version-specific methods and parameters. TODO - this module unnecessarily confuses the code. Can we eliminate it? """ diff --git a/requirements.txt b/requirements.txt index 107957b..95761f8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,4 @@ pytest -numpy \ No newline at end of file +numpy +sphinx +sphinx_rtd_theme