From 60d4e5cc0dc5800f16c94f7a8e80e5069a406293 Mon Sep 17 00:00:00 2001
From: Tobias Schmidt <tobias.schmidt@unibas.ch>
Date: Wed, 2 Oct 2013 13:57:38 +0200
Subject: [PATCH] add documentation for all bindings (fixes BZDNG-399)
---
modules/bindings/doc/bindings.rst | 5 ++
modules/bindings/doc/cadscore.rst | 10 +++
modules/bindings/doc/hbplus.rst | 13 +++
modules/bindings/doc/kclust.rst | 10 +++
modules/bindings/doc/lga.rst | 10 +++
modules/bindings/doc/naccess.rst | 8 ++
modules/bindings/pymod/naccess.py | 140 +++++++++++++++++-------------
modules/index.rst | 2 +
8 files changed, 137 insertions(+), 61 deletions(-)
create mode 100644 modules/bindings/doc/cadscore.rst
create mode 100644 modules/bindings/doc/hbplus.rst
create mode 100644 modules/bindings/doc/kclust.rst
create mode 100644 modules/bindings/doc/lga.rst
create mode 100644 modules/bindings/doc/naccess.rst
diff --git a/modules/bindings/doc/bindings.rst b/modules/bindings/doc/bindings.rst
index 744f6059c..9b4660836 100644
--- a/modules/bindings/doc/bindings.rst
+++ b/modules/bindings/doc/bindings.rst
@@ -18,3 +18,8 @@ So far, the binding module includes:
msms
tmtools
clustalw
+ hbplus
+ kclust
+ naccess
+ lga
+ cadscore
diff --git a/modules/bindings/doc/cadscore.rst b/modules/bindings/doc/cadscore.rst
new file mode 100644
index 000000000..15434508d
--- /dev/null
+++ b/modules/bindings/doc/cadscore.rst
@@ -0,0 +1,10 @@
+:mod:`~ost.bindings.cadscore` - Compare protein structures by difference between physical contacts
+================================================================================
+
+.. module:: ost.bindings.cadscore
+ :synopsis: Compare protein structures by difference between physical contacts
+
+
+.. autofunction:: ost.bindings.cadscore.CADScore
+
+.. autoclass:: ost.bindings.cadscore.CADResult
\ No newline at end of file
diff --git a/modules/bindings/doc/hbplus.rst b/modules/bindings/doc/hbplus.rst
new file mode 100644
index 000000000..005669f8b
--- /dev/null
+++ b/modules/bindings/doc/hbplus.rst
@@ -0,0 +1,13 @@
+:mod:`~ost.bindings.hbplus` - Perform hydrogen bond analysis
+================================================================================
+
+.. module:: ost.bindings.hbplus
+ :synopsis: Perform hydrogen bond analysis
+
+
+.. autofunction:: ost.bindings.hbplus.HBondList
+
+.. autofunction:: ost.bindings.hbplus.HBondScore
+
+
+.. autoclass:: ost.bindings.hbplus.HBond
\ No newline at end of file
diff --git a/modules/bindings/doc/kclust.rst b/modules/bindings/doc/kclust.rst
new file mode 100644
index 000000000..c9aa44ed5
--- /dev/null
+++ b/modules/bindings/doc/kclust.rst
@@ -0,0 +1,10 @@
+:mod:`~ost.bindings.kclust` - Perform fast and sensitive clustering
+================================================================================
+
+.. module:: ost.bindings.kclust
+ :synopsis: Perform fast and sensitive clustering
+
+
+.. autofunction:: ost.bindings.kclust.kClust
+
+.. autoclass:: ost.bindings.kclust.cluster
\ No newline at end of file
diff --git a/modules/bindings/doc/lga.rst b/modules/bindings/doc/lga.rst
new file mode 100644
index 000000000..a989455df
--- /dev/null
+++ b/modules/bindings/doc/lga.rst
@@ -0,0 +1,10 @@
+:mod:`~ost.bindings.lga` - Find 3D similarities in protein structures
+================================================================================
+
+.. module:: ost.bindings.lga
+ :synopsis: Find 3D similarities in protein structures
+
+
+.. autofunction:: ost.bindings.lga.GDT
+
+.. autoclass:: ost.bindings.lga.GDTResult
\ No newline at end of file
diff --git a/modules/bindings/doc/naccess.rst b/modules/bindings/doc/naccess.rst
new file mode 100644
index 000000000..df69ef528
--- /dev/null
+++ b/modules/bindings/doc/naccess.rst
@@ -0,0 +1,8 @@
+:mod:`~ost.bindings.naccess` - Calculate accessible area of a molecule
+================================================================================
+
+.. module:: ost.bindings.naccess
+ :synopsis: Calculate accessible area of a molecule
+
+
+.. autofunction:: ost.bindings.naccess.CalculateSurfaceArea
diff --git a/modules/bindings/pymod/naccess.py b/modules/bindings/pymod/naccess.py
index b02aeab7a..5a064afee 100644
--- a/modules/bindings/pymod/naccess.py
+++ b/modules/bindings/pymod/naccess.py
@@ -23,23 +23,28 @@ from ost import mol
from ost import settings
from ost import geom
-## \brief Method to check if naccess executable is present
-#
-# \param naccess Explicit path to msms executable
-# \return Path to the executable
-# \exception FileNotFound if executable is not found
def _GetExecutable(naccess_exe):
+ """
+ Method to check if naccess executable is present
+
+ :param naccess: Explicit path to msms executable
+ :returns: Path to the executable
+ :exception: FileNotFound if executable is not found
+ """
return settings.Locate('naccess', explicit_file_name=naccess_exe)
-## \brief Setup files for naccess calculation in temporary directory
-#
-# \param entity EntityHandle or EntityView to calculate surface
-# \param selection Calculate surface for subset of entity
-# \param scratch_dir Directory for temporary files (NACCESS is sensitive to "." in directory names
-# \param max_number_of_atoms Max Number of atoms in the entity (i.e. is limited in the default NACCESS version to 50 000)
-# \return array containing temporary directory, input filename for naccess and directory of the input file
-# \exception RuntimeError if selection is not valid
def _SetupFiles(entity, selection, scratch_dir, max_number_of_atoms):
+ """
+ Setup files for naccess calculation in temporary directory
+
+ :param entity: EntityHandle or EntityView to calculate surface
+ :param selection: Calculate surface for subset of entity
+ :param scratch_dir: Directory for temporary files (NACCESS is sensitive to "." in directory names
+ :param max_number_of_atoms: Max Number of atoms in the entity (i.e. is limited in the default NACCESS version to 50 000)
+ :returns: array containing temporary directory, input filename for naccess and directory of the input file
+ :exception: RuntimeError if selection is not valid
+ """
+
# create temporary directory
tmp_dir_name=""
if scratch_dir!=None:
@@ -60,14 +65,15 @@ def _SetupFiles(entity, selection, scratch_dir, max_number_of_atoms):
io.SavePDB(entity_view, tmp_file_name)
return (tmp_dir_name, tmp_file_name, tmp_file_base)
-## \brief Reads Area file (.asa) and attach asa per atom to an entitiy
-#
-# \param entity EntityHandle or EntityView for attaching sasa on atom level
-# \param file Filename of area file
-# \param asa_atom Name of the float property for SASA
-
def _ParseAsaFile(entity, file, asa_atom):
+ """
+ Reads Area file (.asa) and attach asa per atom to an entitiy
+
+ :param entity: EntityHandle or EntityView for attaching sasa on atom level
+ :param file: Filename of area file
+ :param asa_atom: Name of the float property for SASA
+ """
asa_fh = open(file)
asa_lines = asa_fh.readlines()
@@ -99,15 +105,17 @@ def _ParseAsaFile(entity, file, asa_atom):
else:
print chain_id, resNum, atom_name
-## \brief Reads Area file (.rsa) and attach asa (absolute + relative) per residue to an entitiy
-#
-# \param entity EntityHandle or EntityView for attaching sasa on atom level
-# \param file Filename of .rsa file
-# \param asa_atom Name of the float property for absolute SASA
-# \param asa_atom Name of the float property for relative SASA
-# \exception RuntimeError if residue names are not the same
def _ParseRsaFile(enti,file, asa_abs, asa_rel):
+ """
+ Reads Area file (.rsa) and attach asa (absolute + relative) per residue to an entitiy
+
+ :param entity: EntityHandle or EntityView for attaching sasa on atom level
+ :param file: Filename of .rsa file
+ :param asa_atom: Name of the float property for absolute SASA
+ :param asa_atom: Name of the float property for relative SASA
+ :exception: RuntimeError if residue names are not the same
+ """
area_fh = open(file)
area_lines = area_fh.readlines()
area_fh.close()
@@ -143,22 +151,28 @@ def _ParseRsaFile(enti,file, asa_abs, asa_rel):
else:
raise RuntimeError, "Residue Names are not the same for ResNumb: %s (%s vs %s)" % (res_number, res.name, res_name)
-## \brief Method which recursively deletes a directory
-#
-# \warning This method removes also non-empty directories without asking, so
-# be careful!
+
def __CleanupFiles(dir_name):
+ """
+ Method which recursively deletes a directory
+
+ :warning: This method removes also non-empty directories without asking, so
+ be careful!
+ """
import shutil
shutil.rmtree(dir_name)
-## \brief Method to run the MSMS surface calculation
-#
-# This method starts the external MSMS executable and returns the stdout of MSMS
-#
-# \param command Command to execute
-# \return stdout of MSMS
-# \exception CalledProcessError for non-zero return value
+
def _RunNACCESS(command, temp_dir):
+ """
+ Method to run the MSMS surface calculation
+
+ This method starts the external MSMS executable and returns the stdout of MSMS
+
+ :param command: Command to execute
+ :returns: stdout of MSMS
+ :exception: CalledProcessError for non-zero return value
+ """
proc = subprocess.Popen(command, shell=True, stdout=subprocess.PIPE, cwd = temp_dir)
stdout_value, stderr_value = proc.communicate()
@@ -170,34 +184,38 @@ def _RunNACCESS(command, temp_dir):
return stdout_value
-## \brief Calculates analytical the solvent accessible surface
-# area by using the external naccess program
-#
-# This method calculates the molecular surface areas by invoking the external
-# program naccess. First, it is checked if the naccess executable is present, then,
-# the necessary files are prepared in a temporary directory and naccess is
-# executed. The last step is to remove the temporary directory.
-#
-#
-# \param entity OST entity to calculate surface
-# \param radius Surface probe radius
-# \param include_hydrogens Calculate surface including hydrogens
-# \param include_hetatm Calculate surface including hetatms
-# \param include_water Calculate surface including water
-# \param selection Calculate surface for subset of entity
-# \param naccess _exe msms executable (full path to executable)
-# \param keep_files Do not delete temporary files
-# \param asa_abs Attaches per residue absolute SASA to specified FloatProp on residue level
-# \param asa_rel Attaches per residue relative SASA to specified FloatProp on residue level
-# \param asa_atom Attaches per atom SASA to specified FloatProp at atom level
-# \param scratch_dir Directory for temporary files (NACCESS is sensitive to "." in directory names
-# \param max_number_of_atoms Max Number of atoms in the entity (i.e. is limited in the default NACCESS version to 50 000)
-
-# \return absolute SASA calculated using asa_atom
+
def CalculateSurfaceArea(entity, radius=1.4,
include_hydrogens=False, include_hetatm = False,
include_water = False, selection="",
naccess_exe=None, keep_files=False , asa_abs= "asaAbs", asa_rel="asaRel", asa_atom="asaAtom", scratch_dir = None, max_number_of_atoms=50000):
+ """
+ Calculates analytical the solvent accessible surface area by using the
+ external naccess program
+
+ This method calculates the molecular surface areas by invoking the external
+ program naccess. First, it is checked if the naccess executable is present, then,
+ the necessary files are prepared in a temporary directory and naccess is
+ executed. The last step is to remove the temporary directory.
+
+
+ :param entity: OST entity to calculate surface
+ :param radius: Surface probe radius
+ :param include_hydrogens: Calculate surface including hydrogens
+ :param include_hetatm: Calculate surface including hetatms
+ :param include_water: Calculate surface including water
+ :param selection: Calculate surface for subset of entity
+ :param naccess_exe: naccess executable (full path to executable)
+ :param keep_files: Do not delete temporary files
+ :param asa_abs: Attaches per residue absolute SASA to specified FloatProp on residue level
+ :param asa_rel: Attaches per residue relative SASA to specified FloatProp on residue level
+ :param asa_atom: Attaches per atom SASA to specified FloatProp at atom level
+ :param scratch_dir: Directory for temporary files (NACCESS is sensitive to "." in directory names
+ :param max_number_of_atoms: Max Number of atoms in the entity (i.e. is limited in the default NACCESS version to 50 000)
+
+ :returns: absolute SASA calculated using asa_atom
+ """
+
import re
# check if msms executable is specified
diff --git a/modules/index.rst b/modules/index.rst
index 5f043a238..f8b688fa0 100644
--- a/modules/index.rst
+++ b/modules/index.rst
@@ -105,6 +105,8 @@ Varia
Extending OpenStructure
--------------------------------------------------------------------------------
+**External Tools** :doc:`bindings <bindings/bindings>`
+
**Howto:** :doc:`write new modules <newmodule>` | :doc:`integrate third-party tools <external>` | :doc:`logging <base/logging>` | :doc:`instructions for developers <contributing>`
--
GitLab