Fixed documentation.

modules/index.rst

@@ -30,6 +30,7 @@ OpenStructure documentation
   contributing
   table
   mol/alg/lddt
+  mol/alg/molck
 
 For Starters
 --------------------------------------------------------------------------------
@@ -103,6 +104,8 @@ Varia
 
 **lDDT**: :doc:`lDDT command line executable and Python API<mol/alg/lddt>`
 
+**Molck**: :doc:`Molecular Checker<mol/alg/molck>`
+
 Extending OpenStructure
 --------------------------------------------------------------------------------
 

modules/io/doc/io.rst

@@ -349,14 +349,17 @@ Stereochemical Parameters
 In order to check the structure for some stereo-chemical and steric clashes
 before computing the lDDT scores it is required to pass parameter file based on
 Engh and Huber parameters, and on the atomic radii as defined in the Cambridge
-Structural Database. lDDT ships with default file called `stereo_chemical_props.txt`
-located in `$OST_ROOT/share/openstructure` directory. A class
-:class:`~ost.io.StereoChemicalParamsReader` is used to read this file.
+Structural Database. OpenStructure ships with default file called
+`stereo_chemical_props.txt` located in `$OST_ROOT/share/openstructure`
+directory. A class :class:`~ost.io.StereoChemicalParamsReader` is used to read
+this file.
 
-.. class:: StereoChemicalParamsReader
+.. class:: StereoChemicalParamsReader(filename="")
 
   Object that holds and reads stereochemical parameters.
 
+  :param filename: Sets :attr:`filename`.
+
   .. attribute:: bond_table
 
     The table containing bond information of type :class:`~ost.mol.alg.StereoChemicalParams`.
@@ -371,24 +374,14 @@ located in `$OST_ROOT/share/openstructure` directory. A class
 
   .. attribute:: filename
 
-    The path to the parameter file that will be used.
-
-  .. method:: StereoChemicalParamsReader(filename="")
+    The path to the parameter file that will be used. If set to "", it reads the
+    default file shipped with OpenStructure.
 
-    Initializes StereoChemicalParamsReader.
-
-    :param filename: Path to the stereochemical parameter file - defaults to "".
-    :type filename: str
+    :type: :class:`str`
 
   .. method:: Read(check=False)
 
     Read the file.
 
-    :param check: Raise an error when any of the resulting tables are empty - 
-      defaults to False
-    :type check: bool
-
-
-
-
-
+    :param check: Raise an error when any of the resulting tables are empty.
+    :type check:  :class:`bool`

modules/mol/alg/doc/molalg.rst

@@ -328,11 +328,11 @@ Local Distance Test scores (lDDT, DRMSD)
 
   .. warning::
 
-    This function modifies original list.
+    This function modifies the passed *reference_list* list.
 
-  :param reference_list: a list of reference structures from which distances are
-    derived
-  :type reference_list:  list of :class:`~ost.mol.EntityView`
+  :param reference_list: A list of reference structures from which distances are
+                         derived
+  :type reference_list:  :class:`list` of :class:`~ost.mol.EntityView`
 
 
 .. function:: CheckStructure(ent, \
@@ -385,80 +385,77 @@ Local Distance Test scores (lDDT, DRMSD)
   :type settings: :class:`~ost.mol.alg.lDDTSettings`
 
 
-.. class:: lDDTLocalScore
+.. class:: lDDTLocalScore(cname, rname, rnum, is_assessed, quality_problems, \
+                          local_lddt, conserved_dist, total_dist)
 
   Object containing per-residue information about calculated lDDT.
 
+  :param cname: Sets :attr:`cname`
+  :param rname: Sets :attr:`rname`
+  :param rnum: Sets :attr:`rnum`
+  :param is_assessed: Sets :attr:`is_assessed`
+  :param quality_problems: Sets :attr:`quality_problems`
+  :param local_lddt: Sets :attr:`local_lddt`
+  :param conserved_dist: Sets :attr:`conserved_dist`
+  :param total_dist: Sets :attr:`total_dist`
+
   .. attribute:: cname
 
-    Chain name
+    Chain name.
+
+    :type: :class:`str`
 
   .. attribute:: rname
 
-    Residue name
+    Residue name.
+
+    :type: :class:`str`
 
   .. attribute:: rnum
 
-    Residue number
+    Residue number.
+
+    :type: :class:`int`
 
   .. attribute:: is_assessed
 
-    Is the residue taken into account?
+    Is the residue taken into account? Yes or No.
+
+    :type: :class:`str`
 
   .. attribute:: quality_problems
 
-    Does the residue has quality problems?
+    Does the residue have quality problems?
+    No if there are no problems, NA if the problems were not assessed, Yes if
+    there are sidechain problems and Yes+ if there are backbone problems.
+
+    :type: :class:`str`
 
   .. attribute:: local_lddt
 
-    Local lDDT score
+    Local lDDT score for residue.
+
+    :type: :class:`float`
 
   .. attribute:: conserved_dist
 
-    Number of conserved distances
+    Number of conserved distances.
+
+    :type: :class:`int`
 
   .. attribute:: total_dist
 
-    Total number of conserved distances
-
-
-  .. method:: lDDTLocalScore(cname, \
-                             rname, \
-                             rnum, \
-                             is_assessed, \
-                             quality_problems, \
-                             local_lddt, \
-                             conserved_dist, \
-                             total_dist)
-
-    Initialize lDDTLocalScore object.
-
-    :param cname: Chain name
-    :type cname: str
-    :param rname: Residue name
-    :type rname: str
-    :param rnum: Residue number
-    :type rnum: int
-    :param is_assessed: Is the residue taken into account? Yes or No
-    :type is_assessed: str
-    :param quality_problems: Does the residue has quality problems?
-      No if there are no problems, NA if the problems were not assessed, Yes if
-      there are sidechain problems and Yes+ if there are backbone problems
-    :type quality_problems: str
-    :param local_lddt: lDDT score for residue
-    :type local_lddt: float
-    :param conserved_dist: Number of conserved distances
-    :type conserved_dist: int
-    :param total_dist: Total number of distances
-    :type total_dist: int
+    Total number of conserved distances.
+
+    :type: :class:`int`
 
   .. method:: ToString(structural_checks)
 
-    String representation of the lDDTLocalScore object.
+    :return: String representation of the lDDTLocalScore object.
+    :rtype:  :class:`str`
 
     :param structural_checks: Where structural checks applied during calculations?
     :type structural_checks: bool
-    :returns: String representation of the lDDTLocalScore.
 
   .. method:: GetHeader(structural_checks, cutoffs_length)
 
@@ -470,85 +467,91 @@ Local Distance Test scores (lDDT, DRMSD)
     :type cutoffs_length: int
 
 
-.. class:: lDDTSettings
+.. class:: lDDTSettings(bond_tolerance=12, \
+                        angle_tolerance=12, \
+                        radius=15, \
+                        sequence_separation=0, \
+                        sel="", \
+                        parameter_file_path="", \
+                        structural_checks=True, \
+                        consistency_checks=True, \
+                        cutoffs=(0.5, 1.0, 2.0, 4.0), \
+                        label="locallddt")
 
   Object containing the settings used for lDDT calculations.
 
+  :param bond_tolerance: Sets :attr:`bond_tolerance`.
+  :param angle_tolerance: Sets :attr:`angle_tolerance`.
+  :param radius: Sets :attr:`radius`.
+  :param sequence_separation: Sets :attr:`sequence_separation`.
+  :param sel: Sets :attr:`sel`.
+  :param parameter_file_path: Sets :attr:`parameter_file_path`.
+  :param structural_checks: Sets :attr:`structural_checks`.
+  :param consistency_checks: Sets :attr:`consistency_checks`.
+  :param cutoffs: Sets :attr:`cutoffs`.
+  :param label: Sets :attr:`label`.
+
   .. attribute:: bond_tolerance
 
-    Tolerance in stddevs for bonds
+    Tolerance in stddevs for bonds.
+
+    :type: :class:`float`
 
   .. attribute:: angle_tolerance
 
-    Tolerance in stddevs for angles
+    Tolerance in stddevs for angles.
+
+    :type: :class:`float`
 
   .. attribute:: radius
 
-    Distance inclusion radius
+    Distance inclusion radius.
+
+    :type: :class:`float`
 
   .. attribute:: sequence_separation
 
-    Sequence separation
+    Sequence separation.
+
+    :type: :class:`int`
 
   .. attribute:: sel
 
-    Selection performed on reference(s)
+    Selection performed on reference(s).
+
+    :type: :class:`str`
 
   .. attribute:: parameter_file_path
 
-    Path to the stereochemical parameter file
+    Path to the stereochemical parameter file. If set to "", it the default file
+    shipped with OpenStructure is used (see 
+    :class:`~ost.io.StereoChemicalParamsReader`).
+
+    :type: :class:`str`
 
   .. attribute:: structural_checks
 
     Are structural checks and filter input data on?
 
+    :type: :class:`bool`
+
   .. attribute:: consistency_checks
 
     Are consistency checks on?
 
+    :type: :class:`bool`
+
   .. attribute:: cutoffs
 
-    List of thresholds used to determine distance
+    List of thresholds used to determine distance conservation.
+
+    :type: :class:`list` of :class:`float`
 
   .. attribute:: label
 
-    the base name for the ResidueHandle properties that store the local scores
-
-  .. method:: lDDTSettings(bond_tolerance=12, \
-                           angle_tolerance=12, \
-                           radius=15, \
-                           sequence_separation=0, \
-                           sel=="", \
-                           parameter_file_path="", \
-                           structural_checks=True, \
-                           consistency_checks=True, \
-                           cutoffs=(0.5, 1.0, 2.0, 4.0), \
-                           label="locallddt")
-
-    Initializes lDDTSettings object.
-
-    :param bond_tolerance: tolerance in stddevs for bonds - default 12.0
-    :type bond_tolerance: float
-    :param angle_tolerance: tolerance in stddevs for angles - default 12.0
-    :type angle_tolerance: float
-    :param radius: distance inclusion radius - default 15.0
-    :type radius: float
-    :param sequence_separation: sequence separation - default 0
-    :type sequence_separation: int
-    :param sel: selection performed on reference(s) - default ""
-    :type sel: str
-    :param parameter_file_path: use specified parmeter file - default ""
-    :type parameter_file_path: str
-    :param structural_checks: perform structural checks and filter input data - default True
-    :type structural_checks: bool
-    :param consistency_checks: perform consistency checks - default True
-    :type consistency_checks: bool
-    :param cutoffs: a list of thresholds used to determine distance
-      conservation - default [0.5, 1.0, 2.0, 4.0]
-    :type cutoffs: list of floats
-    :param label: the base name for the ResidueHandle properties that store
-      the local scores- default "locallddt"
-    :type label: str
+    The base name for the ResidueHandle properties that store the local scores.
+
+    :type: :class:`str`
 
   .. method:: SetStereoChemicalParamsPath(path)
 
@@ -563,26 +566,22 @@ Local Distance Test scores (lDDT, DRMSD)
 
   .. method:: ToString()
 
-    String representation of the lDDTSettings object.
+    :return: String representation of the lDDTSettings object.
+    :rtype:  :class:`str`
 
-  :returns: str
 
+.. class:: UniqueAtomIdentifier(chain, residue_number, residue_name, atom_name)
 
-.. class:: UniqueAtomIdentifier
-
-  Object containing enough information to uniquely identify an atom in a structure
-
-  .. method:: UniqueAtomIdentifier(chain,residue_number,residue_name,atom_name)
-    
-    Creates an UniqueAtomIdentifier object starting from relevant atom information
+  Object containing enough information to uniquely identify an atom in a
+  structure.
 
-    :param chain: a string containing the name of the chain to which the atom
-                  belongs
-    :param residue_number: the number of the residue to which the atom belongs
-    :type residue_number:  :class:`~ost.mol.ResNum`
-    :param residue_name: a string containing the name of the residue to which
-                         the atom belongs
-    :param atom_name: a string containing the name of the atom
+  :param chain: A string containing the name of the chain to which the atom
+                belongs
+  :param residue_number: The number of the residue to which the atom belongs
+  :type residue_number:  :class:`~ost.mol.ResNum`
+  :param residue_name: A string containing the name of the residue to which
+                       the atom belongs
+  :param atom_name: A string containing the name of the atom
 
   .. method:: GetChainName() 
 
@@ -1473,6 +1472,8 @@ used to skip frames in the analysis.
 Mapping functions
 --------------------------------------------------------------------------------
 
+.. currentmodule:: ost.mol.alg
+
 The following functions help to convert one residue into another by reusing as
 much as possible from the present atoms. They are mainly meant to map from
 standard amino acid to other standard amino acids or from modified amino acids
@@ -1573,7 +1574,7 @@ function:
                      map_nonstd_res=False,
                      assign_elem=True)
   Molck(ent, lib, ms)
-  SavePDB(ent, "<OUTPUT PATH>", profile="SLOPPY")
+  SavePDB(ent, "<OUTPUT PATH>")
 
 It can also be split into subsequent commands for greater controll:
 
@@ -1617,42 +1618,86 @@ It can also be split into subsequent commands for greater controll:
               colored=False)
 
   CleanUpElementColumn(lib=lib, ent=ent)
-  SavePDB(ent, "<OUTPUT PATH>", profile="SLOPPY")
+  SavePDB(ent, "<OUTPUT PATH>")
 
 API
 ###
 
-
-.. class:: MolckSettings
+.. class:: MolckSettings(rm_unk_atoms=False, rm_non_std=False, \
+                         rm_hyd_atoms=True, rm_oxt_atoms=False, \
+                         rm_zero_occ_atoms=False, colored=False, \
+                         map_nonstd_res=True, assign_elem=True)
 
   Stores settings used for Molecular Checker.
 
-  .. method:: __init__(rm_unk_atoms=False,rm_non_std=False,rm_hyd_atoms=True,rm_oxt_atoms=False, rm_zero_occ_atoms=False,colored=False,map_nonstd_res=True, assign_elem=True)
+  :param rm_unk_atoms: Sets :attr:`rm_unk_atoms`.
+  :param rm_non_std: Sets :attr:`rm_non_std`.
+  :param rm_hyd_atoms: Sets :attr:`rm_hyd_atoms`.
+  :param rm_oxt_atoms: Sets :attr:`rm_oxt_atoms`.
+  :param rm_zero_occ_atoms: Sets :attr:`rm_zero_occ_atoms`.
+  :param colored: Sets :attr:`colored`.
+  :param map_nonstd_res: Sets :attr:`map_nonstd_res`.
+  :param assign_elem: Sets :attr:`assign_elem`.
+
+  .. attribute:: rm_unk_atoms
+
+    Remove unknown and atoms not following the nomenclature.
+    
+    :type: :class:`bool`
+
+  .. attribute:: rm_non_std
+
+    Remove all residues not one of the 20 standard amino acids
+    
+    :type: :class:`bool`
+
+  .. attribute:: rm_hyd_atoms
+
+    Remove hydrogen atoms
+    
+    :type: :class:`bool`
+
+  .. attribute:: rm_oxt_atoms
+
+    Remove terminal oxygens
     
-    Initializes MolckSettings.
-
-    :param rm_unk_atoms: Remove unknown and atoms not following the nomenclature
-    :type rm_unk_atoms: :class:`bool`
-    :param rm_non_std: Remove all residues not one of the 20 standard amino acids
-    :type rm_non_std: :class:`bool`
-    :param rm_hyd_atoms: Remove hydrogen atoms
-    :type rm_hyd_atoms: :class:`bool`
-    :param rm_oxt_atoms: Remove terminal oxygens
-    :type rm_oxt_atoms: :class:`bool`
-    :param rm_zero_occ_atoms: Remove atoms with zero occupancy
-    :type rm_zero_occ_atoms: :class:`bool`
-    :param colored: Whether output should be colored
-    :type colored: :class:`bool`
-    :param map_nonstd_res: Maps modified residues back to the parent amino acid, for example
-        MSE -> MET, SEP -> SER
-    :type map_nonstd_res: :class:`bool`
-    :param assign_elem: Clean up element column
-    :type assign_elem: :class:`bool`
+    :type: :class:`bool`
+
+  .. attribute:: rm_zero_occ_atoms
+
+    Remove atoms with zero occupancy
+    
+    :type: :class:`bool`
+
+  .. attribute:: colored
+
+    Whether output should be colored
+    
+    :type: :class:`bool`
+
+  .. attribute:: map_nonstd_res
+
+    Maps modified residues back to the parent amino acid, for example
+    MSE -> MET, SEP -> SER
+    
+    :type: :class:`bool`
+
+  .. attribute:: assign_elem
+
+    Clean up element column
+    
+    :type: :class:`bool`
+
 
   .. method:: ToString()
 
-    String representation of the MolckSettings.
+    :return: String representation of the MolckSettings.
+    :rtype:  :class:`str`
+
+.. warning::
 
+  The API here is set such that the functions modify the passed structure *ent*
+  in-place. If this is not ok, please work on a copy of the structure.
 
 .. function:: Molck(ent, lib, settings)
 
@@ -1675,7 +1720,9 @@ API
   :param lib: Compound library
   :type lib: :class:`~ost.conop.CompoundLib`
 
-.. function:: RemoveAtoms(ent,lib,rm_unk_atoms=False,rm_non_std=False,rm_hyd_atoms=True,rm_oxt_atoms=False,rm_zero_occ_atoms=False,colored=False)
+.. function:: RemoveAtoms(ent, lib, rm_unk_atoms=False, rm_non_std=False, \
+                          rm_hyd_atoms=True, rm_oxt_atoms=False, \
+                          rm_zero_occ_atoms=False, colored=False)
 
   Removes atoms and residues according to some criteria.
 
@@ -1683,18 +1730,12 @@ API
   :type ent: :class:`~ost.mol.EntityHandle`
   :param lib: Compound library
   :type lib: :class:`~ost.conop.CompoundLib`
-  :param rm_unk_atoms: Remove unknown and atoms not following the nomenclature
-  :type rm_unk_atoms: :class:`bool`
-  :param rm_non_std: Remove all residues not one of the 20 standard amino acids
-  :type rm_non_std: :class:`bool`
-  :param rm_hyd_atoms: Remove hydrogen atoms
-  :type rm_hyd_atoms: :class:`bool`
-  :param rm_oxt_atoms: Remove terminal oxygens
-  :type rm_oxt_atoms: :class:`bool`
-  :param rm_zero_occ_atoms: Remove atoms with zero occupancy
-  :type rm_zero_occ_atoms: :class:`bool`
-  :param colored: Whether output should be colored
-  :type colored: :class:`bool`
+  :param rm_unk_atoms: See :attr:`MolckSettings.rm_unk_atoms`
+  :param rm_non_std: See :attr:`MolckSettings.rm_non_std`
+  :param rm_hyd_atoms: See :attr:`MolckSettings.rm_hyd_atoms`
+  :param rm_oxt_atoms: See :attr:`MolckSettings.rm_oxt_atoms`
+  :param rm_zero_occ_atoms: See :attr:`MolckSettings.rm_zero_occ_atoms`
+  :param colored: See :attr:`MolckSettings.colored`
 
 .. function:: CleanUpElementColumn(ent, lib)
 

modules/mol/alg/doc/molck.rst

@@ -56,4 +56,11 @@ please find them following:
                            Default: %-molcked.pdb 
       --color=auto|on|off  whether output should be colored
       --map-nonstd         maps modified residues back to the parent amino acid, for example
-                           MSE -> MET, SEP -> SER.
\ No newline at end of file
+                           MSE -> MET, SEP -> SER.
+
+================
+Molck Python API
+================
+
+Within OST, one can also call the :func:`~ost.mol.alg.Molck` function directly
+on entities to get the same effect as with the binary.