omic/propka
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

initial sphinx docs

Browse Source 
starts #69

- basic structure
- RTD theme
- installation
- quickstart (more to do)
- references
- added start page with license and links to repo and issues
- authors in docs: papers and repo contributors (to be discussed)
This commit is contained in:
Oliver Beckstein
2020-06-19 12:13:53 -07:00
parent 4875d9ee65
commit 2bf031fd65
7 changed files with 477 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/Makefile Normal file
View File

@@ -0,0 +1,20 @@
# 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
# 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)

35
docs/make.bat Normal file
View File

@@ -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

69
docs/source/conf.py Normal file
View File

@@ -0,0 +1,69 @@
# -*- 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_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 = []
# -- 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']

86
docs/source/index.rst Normal file
View File

@@ -0,0 +1,86 @@
.. -*- 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]_.
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
references

52
docs/source/installation.rst Normal file
View File

@@ -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
:command:`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

192
docs/source/quickstart.rst Normal file
View File

@@ -0,0 +1,192 @@
.. -*- coding: utf-8 -*-
.. |pKa| replace:: :math:`\text{p}K_\text{a}`
==================
Quickstart Guide
==================
PROPKA can be used either as a module or via the installed script :command:`propka3`; i.e., either
.. code-block:: bash
propka3
or :mod:`propka`
.. code-block:: bash
python -m propka
works for invoking PROPKA.
Predicting protein residue |pKa| values
=======================================
Most users run PROPKA by invoking the 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:`--help` option:
.. code-block:: bash
propka3 --help
.. links
.. _1HPX: https://www.rcsb.org/structure/1HPX

23
docs/source/references.rst Normal file
View File

@@ -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 <https://doi.org/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 <https://doi.org/10.1021/ct100578z>`_