diff --git a/doc/conf/conf.py b/doc/conf/conf.py
index 84babeb61ce4297c6ecc845aa77712c4332c849a..9e720456c9f9cc6a11c8a6741be2e7ce5ae06d9c 100644
--- a/doc/conf/conf.py
+++ b/doc/conf/conf.py
@@ -88,7 +88,7 @@ exclude_trees = []
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
+modindex_common_prefix = ['ost.']
# -- Options for HTML output ---------------------------------------------------
diff --git a/modules/base/doc/generic.rst b/modules/base/doc/generic.rst
index c0175206df30e0b3c8632c115eb3707d6a9fde7d..6c2cd34cb6d0a29b75a8a8470c6b07a8f7e67d7d 100644
--- a/modules/base/doc/generic.rst
+++ b/modules/base/doc/generic.rst
@@ -82,12 +82,12 @@ to access a property of a different data type, e.g.:
Use of Generic Properties in Queries
--------------------------------------------------------------------------------
-The :doc:`query` can also be used for numeric generic properties (i.e. bool,
+The :doc:`../mol/base/query` can also be used for numeric generic properties (i.e. bool,
int, float), but the syntax is slightly different. To access any generic
properties, it needs to be specified that they are generic and at which level
they are defined. Therefore, all generic properties start with a 'g', followed
by an 'a', 'r' or 'c' for atom, residue or chain level respectively. For more
-details see :doc:`query`.
+details see :doc:`../mol/base/query`.
API documentation
diff --git a/modules/conop/doc/conop.rst b/modules/conop/doc/conop.rst
index fb65ee1ad4e33a27ecf0ba0b9e50851531b8be72..a7ebe2eaa24fd6cb3c6f2990e9ba939b77644544 100644
--- a/modules/conop/doc/conop.rst
+++ b/modules/conop/doc/conop.rst
@@ -1,7 +1,7 @@
-:mod:`conop` -- Connectivity and Topology of Molecules
+:mod:`~ost.conop` -- Connectivity and Topology of Molecules
================================================================================
-.. module:: conop
+.. module:: ost.conop
:synopsis: The conop modules implement different strategies to derive
connectivity information of molecules.
diff --git a/modules/doc/newmodule.rst b/modules/doc/newmodule.rst
index 76d5d96f034da5f24c17a3c98ded7786230a9d1d..a45283055f5a4e60af1f468b5846857d7c3c28c1 100644
--- a/modules/doc/newmodule.rst
+++ b/modules/doc/newmodule.rst
@@ -114,7 +114,7 @@ the module shared library, a `CMakeLists.txt` file needs to be written for the
The line containing the `DEPENDS_ON` directive lists all the modules on which
-the new module depends (in this case :mod:`mol` and :mod:`mol.alg`). The
+the new module depends (in this case :mod:`mol` and :mod:`ost.mol.alg`). The
`module` macro will take care of staging the headers, in this case into
`ost/mod` and compiling, linking and staging of a library with the name
`libost_mod.so` (`libost_gmod.dylib` on MacOS X).
@@ -243,7 +243,7 @@ Here is finally the build script skeleton that needs to be put into
In the last line the call to the 'target\_link\_libraries' function contains the
names of the modules on which the 'mod' unit test code depends (in this case,
-the :mod:`mol` and :mod:`mol.alg` modules), in addition to the `mod` module
+the :mod:`mol` and :mod:`ost.mol.alg` modules), in addition to the `mod` module
itself.
The Python Wrapper
diff --git a/modules/geom/doc/geom.rst b/modules/geom/doc/geom.rst
index 51ad8ce723d7604b49f81fb3138287053103958d..d0412a1340ae8ebf248e3193f381801f85d0b05b 100644
--- a/modules/geom/doc/geom.rst
+++ b/modules/geom/doc/geom.rst
@@ -1,4 +1,4 @@
-:mod:`ost.geom` -- vectors, matrices and geometrical objects
+:mod:`~ost.geom` -- vectors, matrices and geometrical objects
================================================================================
.. module:: ost.geom
diff --git a/modules/img/alg/doc/alg.rst b/modules/img/alg/doc/alg.rst
index 46d0e063df81071cfec50ac9077a6350ec538e6e..3e0f673dedc821d52a781f873d5d21d615f00794 100644
--- a/modules/img/alg/doc/alg.rst
+++ b/modules/img/alg/doc/alg.rst
@@ -1,13 +1,15 @@
-:mod:`img.alg` - Image Processing Algorithms
+:mod:`~ost.img.alg` - Image Processing Algorithms
================================================================================
-
+.. module:: ost.img.alg
+ :synopsis: Image processing algorithms
+
Usage of Image Algorithms
--------------------------------------------------------------------------------
Image algorithms are objects. To execute them, the algorithms are applied to an
-image by passing it to the :meth:`img.ImageHandle.Apply` or
-:meth:`img.ImageHandle.ApplyIP` method:
+image by passing it to the :meth:`ost.img.ImageHandle.Apply` or
+:meth:`ost.img.ImageHandle.ApplyIP` method:
.. code-block:: python
diff --git a/modules/img/base/doc/img.rst b/modules/img/base/doc/img.rst
index e09e24d647935adb1eca5f8df01ec00a912aa583..53243c9042291e6151667d154c4c411d3a543f8b 100644
--- a/modules/img/base/doc/img.rst
+++ b/modules/img/base/doc/img.rst
@@ -1,8 +1,8 @@
-:mod:`img` Images and Density Maps
+:mod:`~ost.img` Images and Density Maps
================================================================================
-.. module:: mol
- :synopsis: Images and Density Maps
+.. module:: ost.img
+ :synopsis: Images and density maps
Introduction : The ImageHandle
--------------------------------------------------------------------------------
diff --git a/modules/index.rst b/modules/index.rst
index 09dc2d92040d082437f85ac38f8cb2b62c3e4b69..cdb3284d5b4d8ba64311e151052d0200d4a1d66f 100644
--- a/modules/index.rst
+++ b/modules/index.rst
@@ -11,7 +11,7 @@ Introduction
:maxdepth: 2
intro
- install.rst
+ install
Modules
--------------------------------------------------------------------------------
@@ -27,6 +27,7 @@ Modules
mol/base/mol
seq/base/seq
base/base
+ io/io
Extending OpenStructure
--------------------------------------------------------------------------------
diff --git a/modules/io/doc/io.rst b/modules/io/doc/io.rst
new file mode 100644
index 0000000000000000000000000000000000000000..21c38bc4f93f2ce10b4357004c9c688f310a178a
--- /dev/null
+++ b/modules/io/doc/io.rst
@@ -0,0 +1,103 @@
+:mod:`~ost.io` - Input and Output of Sequences, Structures and Maps
+================================================================================
+
+.. module:: ost.io
+ :synopsis: Input and output of sequences, structures and density maps
+
+The io module deals with input and output of :class:`entities
+<ost.mol.EntityHandle>`, :class:`alignments <ost.seq.AlignmentHandle>`, and
+:class:`images <ost.img.ImageHandle>`. Importers for common file formats such
+as PDB, SDF, FASTA, CLUSTAL W, DX and CHARMM trajectory files are available.
+
+Molecular Structures
+--------------------------------------------------------------------------------
+
+Loading Molecular Structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :mod:`~ost.io` modules offers several ways to load molecular structures
+depending on your requirements. The most general way is offered by
+:func:`~ost.io.LoadEntity`, which will automatically detect the file format based
+on the file extension.
+
+.. function:: LoadEntity(filename, format='auto')
+
+ Load entity from disk. If format is set to 'auto', the function guesses the
+ filetype based on the extension of the file. Files ending in '.pdb', '.ent',
+ '.ent.gz', '.pdb.gz' will automatically be loaded as PDB files, for example.
+ For files without or exotic extensions, the format can be set explicitly as
+ the second parameter.
+
+ .. code-block:: python
+
+ # recognizes SDF file by file extension
+ ent=io.LoadEntity('file.sdf')
+
+ # In this case, there is no file extensions, so you have to say it's a
+ # SDF file explicitly
+ ent=io.LoadEntity('file', 'sdf')
+
+ For a list of file formats supported by :func:`LoadEntity`, see :doc:`formats`.
+
+ :raises: :exc:`~ost.io.IOUnknownFormatException` if the format string supplied
+ is not recognized or the file format can not be detected based on the
+ file extension
+
+ :exc:`~ost.io.IOException` if the import fails due to an erroneous or
+ inexistent file
+
+Some of the formats have a dedicated function that allows you to tweak many
+parameters that affect the import. PDB files can be loaded with
+:func:`~ost.io.LoadPDB`. It offers a tighter control over the exact loading
+behaviour.
+
+.. autofunction:: ost.io.LoadPDB
+
+
+Saving Molecular Structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Saving a complete entity or a view is a matter of calling
+:func:`~ost.io.SaveEntity`.
+
+.. code-block:: python
+
+ ent=io.LoadEntity('protein.pdb')
+ # save full entity
+ io.SaveEntity(ent, 'full.pdb')
+ # only save C-alpha atoms
+ io.SaveEntity(ent.Select('aname=CA and peptide=true'), 'calpha.pdb')
+
+:func:`~ost.io.SavePDB` provides a simple way to save several entities into one
+file:
+
+
+.. code-block:: python
+
+ ent=io.LoadEntity('protein.pdb')
+ # Save complete entity
+ io.SavePDB(ent, 'full.pdb')
+ # Save chain A and chain B separately
+ io.SavePDB([ent.Select('cname=A'), ent.Select('cname=B')], 'split.pdb')
+
+
+.. function:: SaveEntity(ent, filename, format='auto')
+
+ Save entity to disk. If format is set to 'auto', the function guesses the
+ filetype based on the file extension, otherwise the supplied format is checked
+ against the available export plugins.
+
+ :param ent: The entity to be saved
+ :type ent: :class:`~ost.mol.EntityHandle` or :class:`~ost.mol.EntityView`
+ :param filename: The filename
+ :type filename: string
+ :param format: Name of the format
+ :type format: string
+
+ :raises: :exc:`~ost.io.IOUnknownFormatException` if the format string supplied
+ is not recognized or the file format can not be detected based on the
+ file extension
+
+.. autofunction:: ost.io.SavePDB
+
+
\ No newline at end of file
diff --git a/modules/io/pymod/__init__.py b/modules/io/pymod/__init__.py
index 344f971292b41d79cddbb61925c71d5296d0d474..095cacb8953c011a2e37f4946b6b21eee00a5286 100644
--- a/modules/io/pymod/__init__.py
+++ b/modules/io/pymod/__init__.py
@@ -17,29 +17,35 @@
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
#------------------------------------------------------------------------------
from _io import *
-from ost import mol,conop
+from ost import mol, conop
def LoadPDB(filename, restrict_chains="", no_hetatms=False,
fault_tolerant=False, load_multi=False,
join_spread_atom_records=False, calpha_only=False):
"""
- Load PDB file from disk.
+ Load PDB file from disk and returns one or more entities. Several options
+ allow to customize the exact behaviour of the PDB import.
- If restrict_chains is not an empty string, only chains listed in the
- string will be imported.
+ :param restrict_chains: If not an empty string, only chains listed in the
+ string will be imported.
- If fault_tolerant is set to true, the import will succeed, even if the
- PDB contains faulty records. The faulty records will be ignored in that
- case.
+ :param fault_tolerant: 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 haven't been present.
- If not_hetatms is set to True, HETATM records will be ignored
+ :param no_hetatms: If set to True, HETATM records will be ignored
- If load_multi is set to true, a list of entities will be returned instead
- of only the first.
+ :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.
- If join_spread_atom_records is set to true, atom records belonging to the
- same residue are joined, even if they do not appear sequentially in the PDB
- file.
+ :param join_spread_atom_records: If set to true, atom records belonging to the
+ same residue are joined, even if they do not appear sequentially in the PDB
+ file.
+ :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
"""
conop_inst=conop.Conopology.Instance()
builder=conop_inst.GetBuilder("DEFAULT")
@@ -78,7 +84,13 @@ def LoadPDB(filename, restrict_chains="", no_hetatms=False,
def SavePDB(models, filename):
"""
- Save entity or list of entities to disk
+ Save entity or list of entities to disk. If a list of entities is supplied the
+ PDB file will be saved as a multi PDB file. Each of the entities is wrapped
+ into a MODEL/ENDMDL pair.
+
+ :param models: The entity or list of entities (handles or views) to be saved
+ :param filename: The filename
+ :type filename: string
"""
if not getattr(models, '__len__', None):
models=[models]
diff --git a/modules/mol/base/doc/editors.rst b/modules/mol/base/doc/editors.rst
index aaed57b35ea03c395926d4cf745c2483c80cf6a7..f224b2e1fd2290db8be073dda9d18fc36bf052db 100644
--- a/modules/mol/base/doc/editors.rst
+++ b/modules/mol/base/doc/editors.rst
@@ -1,7 +1,7 @@
Editors
================================================================================
-.. currentmodule:: mol
+.. currentmodule:: ost.mol
The structure, topology and connectivity of entities is edited via editors. This
includes operations such as changing atom positions, connecting atoms with bonds
@@ -118,7 +118,7 @@ euclidian space.
transform.
:param atom: must be a valid atom handle
- :type atom: :class:`mol.AtomHandle`
+ :type atom: :class:`ost.mol.AtomHandle`
:param pos: The new position
:type pos: :class:`geom.Vec3`
@@ -129,7 +129,7 @@ euclidian space.
the original pos.
:param atom: must be a valid atom handle
- :type atom: :class:`mol.AtomHandle`
+ :type atom: :class:`ost.mol.AtomHandle`
:param pos: The new untransformed position
:type pos: :class:`geom.Vec3`
diff --git a/modules/mol/base/doc/entity.rst b/modules/mol/base/doc/entity.rst
index bd6eb59f8b6a18cf184090bd2f3e3aac80c8bd9c..1adcd2de76af8d919b0928bc91b01669912a1a59 100644
--- a/modules/mol/base/doc/entity.rst
+++ b/modules/mol/base/doc/entity.rst
@@ -1,7 +1,7 @@
The Molecular Entity
================================================================================
-.. currentmodule:: mol
+.. currentmodule:: ost.mol
This document describes the :class:`EntityHandle` and related classes.
@@ -10,7 +10,7 @@ This document describes the :class:`EntityHandle` and related classes.
Creates a new entity. The created entity is empty, that is, it does not
contain any atoms, residues, chains, bonds or torsions. To populate the
- entity, use an :ref:`editor`.
+ entity, use an :doc:`editors`.
:returns: The newly created :class:`EntityHandle`
diff --git a/modules/mol/base/doc/mol.rst b/modules/mol/base/doc/mol.rst
index e4de24691c513680a2c512e652cb3085301c4d6a..a16b21f541edbec24a14ea8f96c9183adc9cf4f3 100644
--- a/modules/mol/base/doc/mol.rst
+++ b/modules/mol/base/doc/mol.rst
@@ -1,7 +1,7 @@
-:mod:`mol` -- Molecular structures and surfaces
+:mod:`~ost.mol` -- Molecular structures and surfaces
================================================================================
-.. module:: mol
+.. module:: ost.mol
:synopsis: Contains classes and functions to deal with molecular structures
and surfaces
diff --git a/modules/seq/base/doc/seq.rst b/modules/seq/base/doc/seq.rst
index dab754db025be9d24a45e865d62f0c9b023301da..7deafe22e797a6d0c4f1ab22cc041f56e5889cbc 100644
--- a/modules/seq/base/doc/seq.rst
+++ b/modules/seq/base/doc/seq.rst
@@ -1,7 +1,7 @@
-:mod:`seq` -- Sequences and Alignments
+:mod:`~ost.seq` -- Sequences and Alignments
================================================================================
-.. module:: seq
+.. module:: ost.seq
:synopsis: Contains classes and functions to deal with sequences and
alignments