From 26a5ab042e30a8eafbe47528fe5121dd223eab01 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Fri, 19 Jun 2020 16:25:24 -0700 Subject: [PATCH] API docs for propka - use autosummary (with custom module template) - updated module docs for all modules so that they are included with sphinx autodocs --- docs/source/api.rst | 78 ++++++++++++++++++++++++++++++++ docs/source/index.rst | 4 ++ docs/source/installation.rst | 2 +- docs/source/quickstart.rst | 8 ++-- propka/__init__.py | 2 +- propka/atom.py | 9 +++- propka/bonds.py | 8 +++- propka/calculations.py | 10 +++- propka/conformation_container.py | 16 +++++-- propka/coupled_groups.py | 8 +++- propka/determinant.py | 17 +++++-- propka/determinants.py | 16 +++++-- propka/energy.py | 8 +++- propka/group.py | 9 +++- propka/hybrid36.py | 11 ++++- propka/hydrogens.py | 8 +++- propka/input.py | 7 ++- propka/iterative.py | 8 +++- propka/lib.py | 8 +++- propka/ligand.py | 15 ++++-- propka/ligand_pka_values.py | 12 ++++- propka/molecular_container.py | 7 ++- propka/output.py | 17 ++++--- propka/parameters.py | 21 ++++++++- propka/protonate.py | 10 +++- propka/run.py | 28 ++++++++++-- propka/vector_algebra.py | 7 ++- propka/version.py | 6 ++- 28 files changed, 308 insertions(+), 52 deletions(-) create mode 100644 docs/source/api.rst 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/index.rst b/docs/source/index.rst index 5000820..3866fb4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,6 +18,9 @@ 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 :program:`propka3` command and the +:mod:`propka` Python package. + License and source code ======================= @@ -81,6 +84,7 @@ Indices and tables installation quickstart + api references diff --git a/docs/source/installation.rst b/docs/source/installation.rst index dac0ab2..fe9f095 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -21,7 +21,7 @@ The easiest way to install a release of PROPKA 3 is from the `PyPI archive`_ wit This installation will install the :mod:`propka` Python module and the -:command:`propka3` executable script. As always, a virtual environment (e.g., via +:program:`propka3` executable script. As always, a virtual environment (e.g., via `virtualenv`_) is recommended when installing packages. Source-based installation diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 709e205..4a31ae5 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -8,7 +8,7 @@ Quickstart Guide ================== -PROPKA can be used either as a module or via the installed script :command:`propka3`; i.e., either +PROPKA can be used either as a module or via the installed script :program:`propka3`; i.e., either .. code-block:: bash @@ -26,9 +26,9 @@ 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) +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 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? """