docu updates

modules/conop/doc/connectivity.rst

@@ -48,10 +48,7 @@ compounds such as ligands the HeuristicProcessor runs a distance-based
 connectivity algorithm that connects two atoms if they are closer than a certain
 threshold. The RuleBasedProcessor uses a connectivity library containing all
 molecular components present in the PDB files on PDB.org. The library can easily
-be extended with custom  connectivity information, if required. If a
-:doc:`compound library <compoundlib>` is present, the
-:class:`RuleBasedProcessor` is enabled by default, otherwise the
-:class:`HeuristicProcessor` is used as a fallback.
+be extended with custom  connectivity information, if required.
 
 
 .. class:: Processor

modules/io/doc/profile.rst

@@ -12,40 +12,48 @@ Basic usage of IO profiles
 --------------------------------------------------------------------------------
 
 You are most certainly reading this document because you were having trouble
-loading PDB files. In that case, as a first step you will want to set the profile parameter of  :func:`LoadPDB`. The profile
-parameter can either be the name of a profile or an instance of
-:class:`IOProfile`. Both of the following two examples are equivalent:
+loading PDB files. In that case, as a first step you will want to set the
+profile parameter of  :func:`LoadPDB`. The profile parameter can either be the
+name of a profile or an instance of :class:`IOProfile`. Both of the following
+two examples are equivalent:
 
 .. code-block:: python
 
   ent = io.LoadPDB('weird.pdb', profile=io.profiles['SLOPPY'])
   ent = io.LoadPDB('weird.pdb', profile='SLOPPY')
 
-Profiles is a dictionary-like object containing all the profiles known to OpenStructure. You can add new ones by inserting them into the dictionary. If you are loading a lot of structures, you may want to set the default profile to avoid having to pass the profile every time you load a structure. This is done by assigning a different profile to ``DEFAULT``:
+Profiles is a dictionary-like object containing all the profiles known to
+OpenStructure. You can add new ones by inserting them into the dictionary.
+If you are loading a lot of structures, you may want to set the default profile
+to avoid having to pass the profile every time you load a structure.
+This is done by assigning a different profile to ``DEFAULT``:
 
 .. code-block:: python
 
   io.profiles['DEFAULT']='SLOPPY'
   ent = io.LoadPDB('weird.pdb')
 
-Again, you can either assign the name of the profile, or the profile itself. If none of the profiles available by default suits your needs, feel free to create one to your liking.
+Again, you can either assign the name of the profile, or the profile itself.
+If none of the profiles available by default suits your needs, feel free to
+create one to your liking.
 
 Available default profiles
 --------------------------------------------------------------------------------
 
-The following profiles are available by default. For a detailed description of what the different parameters mean, consult the documentation of the :class:`IOProfile` class.
+The following profiles are available by default. For a detailed description of
+what the different parameters mean, consult the documentation of
+:class:`IOProfile`.
 
 STRICT
 
-  This profile is the default and is known to work very well with PDB files
-  coming from the official PDB website. It is equivalent to the following
-  profile:
+  This profile is the default (also available as DEFAULT) and is known to
+  work very well with PDB files coming from the official PDB website. It
+  is equivalent to the following profile:
 
   .. code-block:: python
 
-    IOProfile(dialect='PDB', strict_hydrogens=False, quack_mode=False,
-              fault_tolerant=False, join_spread_atom_records=False,
-              no_hetatms=False, bond_feasibility_check=False)
+    IOProfile(dialect='PDB', fault_tolerant=False, quack_mode=False,
+              processor=conop.RuleBasedProcessor(conop.GetDefaultLib()))
 
 SLOPPY:
 
@@ -53,9 +61,8 @@ SLOPPY:
 
   .. code-block:: python
 
-    IOProfile(dialect='PDB', strict_hydrogens=False, quack_mode=True,
-              fault_tolerant=True, join_spread_atom_records=False,
-              no_hetatms=False, bond_feasibility_check=True)
+    IOProfile(dialect='PDB', fault_tolerant=True, quack_mode=True,
+              processor=conop.RuleBasedProcessor(conop.GetDefaultLib()))
 
 CHARMM:
 
@@ -64,28 +71,33 @@ CHARMM:
 
   .. code-block:: python
 
-    IOProfile(dialect='CHARMM', strict_hydrogens=False, quack_mode=True,
-              fault_tolerant=True, join_spread_atom_records=True,
-              no_hetatms=False, bond_feasibility_check=True)
+    IOProfile(dialect='CHARMM', fault_tolerant=True, quack_mode=False,
+              processor=conop.RuleBasedProcessor(conop.GetDefaultLib()))
+
+.. note:: 
+
+  The profiles are setup at the first import of the io module, i.e. something
+  like  ``from ost import io`` or ``from ost.io import LoadPDB``. The processor
+  parameter is set as stated above IF :func:`ost.conop.GetDefaultLib()` returns
+  a valid compound library at that point in time. If not, the processor is set
+  to :class:`ost.conop.HeuristicProcessor()`. Calling
+  :func:`ost.conop.SetDefaultLib()` has thus no immediate effect on the default
+  profiles! Two exceptions: :func:`ost.io.LoadPDB` and
+  :class:`ost.io.LoadMMCIF()` have a logic in place to override the processor of
+  the default profiles with :func:`ost.conop.GetDefaultLib`, using
+  :class:`HeuristicProcessor` respectively. This logic does not apply to user
+  defined profiles. 
 
 
 The IOProfile Class
 --------------------------------------------------------------------------------
 
-.. class:: IOProfile(dialect='PDB', strict_hydrogens=False, quack_mode=False, join_spread_atom_records=False, no_hetatms=False, calpha_only=False, fault_tolerant=False, bond_feasibility_check=True)
+.. class:: IOProfile(dialect='PDB', quack_mode=False, fault_tolerant=False,\
+                     join_spread_atom_records=False, no_hetatms=False,\
+                     calpha_only=False, processor=None)
 
   Aggregates flags that control the import of molecular structures.
 
-  .. attribute:: quack_mode
-
-    :type: bool
-
-    Read/write property. When quack_mode is enabled, the chemical class for
-    unknown residues is guessed based on its atoms and connectivity. Turn this
-    on if you are working with non-standard conforming PDB files and are
-    experiencing problems with the rendering of the backbone trace and/or see
-    peptidic residues with unknown chemical classes.
-
   .. attribute:: dialect
 
     :type: str
@@ -96,21 +108,16 @@ The IOProfile Class
     support for chain names with length up to 4 characters (column 72-76) and
     increase the size of the residue name to 4 residues.
 
-  .. attribute:: strict_hydrogens
+  .. attribute:: quack_mode
 
     :type: bool
 
-    Whether hydrogen names should be strictly checked. It is very common for
-    PDB files to not follow the correct naming conventions for hydrogen atoms.
-    That's why by default the names of the hydrogens are not required to be
-    correct. Rather, the connectivity is inferred with distance-based checks. By
-    turning this flag on, the names of the hydrogen atoms are checked against
-    the names in the database like all other atom types.
-    
-  .. attribute:: no_hetatms
-  
-    If set to true, HETATM records are ignored during import.
-    
+    Read/write property. When quack_mode is enabled, the chemical class for
+    unknown residues is guessed based on its atoms and connectivity. Turn this
+    on if you are working with non-standard conforming PDB files and are
+    experiencing problems with the rendering of the backbone trace and/or see
+    peptidic residues with unknown chemical classes.
+
   .. attribute:: fault_tolerant
 
     :type: bool
@@ -118,23 +125,31 @@ The IOProfile Class
     If true, the import will succeed, even if the PDB contains faulty records.
     The faulty records will be ignored and import continues as if the records
     are not present.
-    
+
   .. attribute::   join_spread_atom_records
+
+    :type: bool
   
     If set to true, atom records belonging to the same residue are joined, even 
     if they do not appear sequentially in the PDB file.
 
+  .. attribute:: no_hetatms
+
+    :type: bool
+  
+    If set to true, HETATM records are ignored during import.
+
   .. attribute:: calpha_only
 
+    :type: bool
+
     When set to true, forces the importer to only load atoms named CA. This is
     most useful in combination with protein-only PDB files to speed up
     subsequent processing and importing.
 
-  .. attribute:: bond_feasibility_check
+  .. attribute:: processor
+
+    :type: :class:`ost.conop.HeuristicProcessor`/:class:`ost.conop.RuleBasedProcessor`
 
-    When set to true, adds an additional distance feasibility to figure out if
-    two atoms should be connected. Atoms are only connected if they are within a
-    certain distance range. Set this to false to completely disable distance
-    checks for intra-residual bonds. Peptide bonds as well as bonds between
-    nucleotides involving more than one residue still make use of the distance
-    check to figure out of if the two residues should be connected.
+    Controls connectivity processing of loaded :class:`ost.mol.EntityHandle`.
+    Even though its a keyword argument, processing will fail if not given.

modules/io/pymod/__init__.py

@@ -91,25 +91,59 @@ def LoadPDB(filename, restrict_chains="", no_hetatms=None,
   
   Residues are flagged as ligand if they are mentioned in a HET record.
 
-  :param restrict_chains: If not an empty string, only chains listed in the
-     string will be imported.
+  :param filename: File to be loaded
+  :type filename: :class:`str`
 
-  :param fault_tolerant: Enable/disable fault-tolerant import. If set, overrides 
-     the value of :attr:`IOProfile.fault_tolerant`.
+  :param restrict_chains: If not an empty string, only chains listed in the
+                          string will be imported.
+  :type restrict_chains: :class:`str`
 
   :param no_hetatms: If set to True, HETATM records will be ignored. Overrides 
-      the value of :attr:`IOProfile.no_hetatms`
+                     the value of :attr:`IOProfile.no_hetatms`
+  :type no_hetatms: :class:`bool`
+
+  :param fault_tolerant: Enable/disable fault-tolerant import. If set, overrides 
+                         the value of :attr:`IOProfile.fault_tolerant`.
+  :type fault_tolerant: :class:`bool`
 
   :param load_multi: If set to True, a list of entities will be returned instead
-      of only the first. This is useful when dealing with multi-PDB files.
+                     of only the first. This is useful when dealing with
+                     multi-PDB files.
+  :type load_multi: :class:`bool`
+
+  :param quack_mode: Guess the chemical class for unknown residues based on its
+                     atoms and connectivity. If set, overrides the value of
+                     :attr:`IOProfile.quack_mode`.
+  :type quack_mode: :class:`bool`
 
   :param join_spread_atom_records: If set, overrides the value of 
-      :attr:`IOProfile.join_spread_atom_records`.
+                                   :attr:`IOProfile.join_spread_atom_records`.
+  :type join_spread_atom_records: :class:`bool`
+
+  :param calpha_only: When set to true, forces the importer to only load atoms
+                      named CA. If set, overrides the value of
+                      :attr:`IOProfile.calpha_only`.
+  :type calpha_only: :class:`bool`
+
+  :param profile: Aggregation of flags and algorithms to control import and
+                  processing of molecular structures. Can either be a
+                  :class:`str` specifying one of the default profiles
+                  ['DEFAULT', 'SLOPPY', 'CHARMM', 'STRICT'] or an actual object
+                  of type :class:`ost.io.IOProfile`. If a :class:`str` defines
+                  a default profile, :attr:`IOProfile.processor` is set to
+                  :class:`ost.conop.RuleBasedProcessor` with the currently
+                  set :class:`ost.conop.CompoundLib` available as
+                  :func:`ost.conop.GetDefaultLib()`. If no
+                  :class:`ost.conop.CompoundLib` is available,
+                  :class:`ost.conop.HeuristicProcessor` is used instead. See
+                  :doc:`profile` for more info.
+  :type profile: :class:`str`/:class:`ost.io.IOProfile`
   
-  :param remote: If set to True, the method tries to load the pdb from the 
-     remote repository given as *remote_repo*. The filename is then 
-     interpreted as the entry id as further specified for the *remote_repo*
-     parameter.
+  :param remote: If set to True, the method tries to load the pdb from the remote
+                 repository given as *remote_repo*. The filename is then
+                 interpreted as the entry id as further specified for the
+                 *remote_repo* parameter.
+  :type remote: :class:`bool`
 
   :param remote_repo: Remote repository to fetch structure if *remote* is True. 
                       Must be one in ['pdb', 'smtl', 'pdb_redo']. In case of 
@@ -117,18 +151,27 @@ def LoadPDB(filename, restrict_chains="", no_hetatms=None,
                       case pdb id, which loads the deposited assymetric unit 
                       (e.g. '1ake'). In case of 'smtl', the entry must also 
                       specify the desired biounit (e.g. '1ake.1').
+  :type remote_repo: :class:`str`
      
-  :rtype: :class:`~ost.mol.EntityHandle` or a list thereof if `load_multi` is 
-      True.
-
   :param dialect: Specifies the particular dialect to use. If set, overrides 
-    the value of :attr:`IOProfile.dialect`
+                  the value of :attr:`IOProfile.dialect`
+  :type dialect: :class:`str`
 
   :param seqres: Whether to read SEQRES records. If set to True, the loaded 
-    entity and seqres entry will be returned as a tuple.
+                 entity and seqres entry will be returned as a tuple.
+  :type seqres: :class:`bool`
+
+  :param bond_feasibility_check: Flag for :attr:`IOProfile.processor`. If
+                                 turned on, atoms are only connected by
+                                 bonds if they are within a reasonable distance
+                                 (as defined by
+                                 :func:`ost.conop.IsBondFeasible`).
+                                 If set, overrides the value of
+                                 :attr:`ost.conop.Processor.check_bond_feasibility`
+  :type bond_feasibility_check: :class:`bool`
 
-  :type dialect: :class:`str`
-  
+  :rtype: :class:`~ost.mol.EntityHandle` or a list thereof if `load_multi` is 
+      True.  
 
   :raises: :exc:`~ost.io.IOException` if the import fails due to an erroneous or 
       inexistent file
@@ -292,7 +335,8 @@ def LoadCHARMMTraj(crd, dcd_file=None, profile='CHARMM',
       raise ValueError("No DCD filename given")
   return LoadCHARMMTraj_(crd, dcd_file, stride, lazy_load, detect_swap, swap_bytes)
 
-def LoadMMCIF(filename, fault_tolerant=None, calpha_only=None, profile='DEFAULT', remote=False, seqres=False, info=False):
+def LoadMMCIF(filename, fault_tolerant=None, calpha_only=None,
+              profile='DEFAULT', remote=False, seqres=False, info=False):
   """
   Load a mmCIF file and return one or more entities. Several options allow to
   customize the exact behaviour of the mmCIF import. For more information on
@@ -300,15 +344,30 @@ def LoadMMCIF(filename, fault_tolerant=None, calpha_only=None, profile='DEFAULT'
   
   Residues are flagged as ligand if they are mentioned in a HET record.
 
+  :param filename: File to be loaded
+  :type filename: :class:`str`
+
   :param fault_tolerant: Enable/disable fault-tolerant import. If set, overrides
-     the value of :attr:`IOProfile.fault_tolerant`.
+                         the value of :attr:`IOProfile.fault_tolerant`.
+  :type fault_tolerant: :class:`bool`
+
+  :param calpha_only: When set to true, forces the importer to only load atoms
+                      named CA. If set, overrides the value of
+                      :attr:`IOProfile.calpha_only`.
+  :type calpha_only: :class:`bool`
+
+  :param profile: Aggregation of flags and algorithms to control import and
+                  processing of molecular structures. Can either be a
+                  :class:`str` specifying one of the default profiles
+                  ['DEFAULT', 'SLOPPY', 'CHARMM', 'STRICT'] or an actual object
+                  of type :class:`ost.io.IOProfile`. See :doc:`profile` for more
+                  info.
+  :type profile: :class:`str`/:class:`ost.io.IOProfile`
 
   :param remote: If set to True, the method tries to load the pdb from the 
-     remote pdb repository www.pdb.org. The filename is then interpreted as the 
-     pdb id.
-
-  :rtype: :class:`~ost.mol.EntityHandle` (or tuple if *seqres* or *info* are
-          True).
+                 remote pdb repository www.pdb.org. The filename is then
+                 interpreted as the pdb id.
+  :type remote: :class:`bool`
 
   :param seqres: Whether to read SEQRES records. If True, a
                  :class:`~ost.seq.SequenceList` object is returned as the second
@@ -318,9 +377,14 @@ def LoadMMCIF(filename, fault_tolerant=None, calpha_only=None, profile='DEFAULT'
                  :class:`compound library <ost.conop.CompoundLib>`
                  to be defined and accessible via
                  :func:`~ost.conop.GetDefaultLib` or an empty list is returned.
+  :type seqres: :class:`bool`
 
   :param info: Whether to return an info container with the other output.
                If True, a :class:`MMCifInfo` object is returned as last item.
+  :type info: :class:`bool`
+
+  :rtype: :class:`~ost.mol.EntityHandle` (or tuple if *seqres* or *info* are
+          True).
 
   :raises: :exc:`~ost.io.IOException` if the import fails due to an erroneous
            or non-existent file.