Skip to content
Snippets Groups Projects
Commit 6699d377 authored by marco's avatar marco
Browse files

added some sphinx docs

this serves as the playground to test the sphinx documentation
generator. Run make doc to generate html documentation. Of
course, requires sphinx.

git-svn-id: https://dng.biozentrum.unibas.ch/svn/openstructure/trunk@1921 5a81b35b-ba03-0410-adc8-b2c5c5119f08
parent 30aadd06
No related branches found
No related tags found
No related merge requests found
......@@ -240,3 +240,10 @@ message(STATUS
" Optimize (-DOPTIMIZE) : ${_OPT}\n"
" Double Precision (-DUSE_DOUBLE_PRECISION) : ${_DOUBLE_PREC}\n"
" Compound Lib (-DCOMPOUND_LIB) : ${_COMP_LIB}")
# doc target to create HTML documentation
set(SPHINX sphinx-build)
set(SPHINX_OPTIONS -c doc/conf -b html -d doc/html/doctrees)
add_custom_target(doc COMMAND
${SPHINX} ${SPHINX_OPTIONS} modules doc/html
VERBATIM)
\ No newline at end of file
# -*- coding: utf-8 -*-
#
# OpenStructure documentation build configuration file, created by
# sphinx-quickstart on Sat Apr 3 13:01:52 2010.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.append(os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
'sphinx.ext.coverage', 'sphinx.ext.pngmath',
'sphinx.ext.ifconfig']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'OpenStructure'
copyright = u'2010, OpenStructure authors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '1.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of documents that shouldn't be included in the build.
#unused_docs = []
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_trees = []
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
html_theme = 'sphinxdoc'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_use_modindex = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'openstructure-doc'
# -- Options for LaTeX output --------------------------------------------------
# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'OpenStructure.tex', u'OpenStructure Documentation',
u'OpenStructure authors', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_use_modindex = True
:mod:`conop` -- Connectivity and Topology of Molecules
================================================================================
.. module:: conop
:synopsis: The conop modules implement different strategies to derive
connectivity information of molecules.
The main task of the conop module is to connect atoms with bonds. While the
bond class is also part of the base module, the conop module deals with setting
up the correct bonds between atoms.
Motivation
--------------------------------------------------------------------------------
Traditionally the connectivity between atoms has not been reliably described in
a PDB file. Different programs adopted various ways of finding out if two atoms
are connected. One way chosen is to rely on proper naming of the atoms. For
example, the backbone atoms of the standard amino acids are named as N, CA, C
and O and if atoms with these name appear in the same residue they are shown
connected. Another way is to apply additional heuristics to find out if a
peptide bond between two consecutive residues is formed. Breaks in the backbone
are indicated, e.g., by introducing a discontinuity in the numbering of the residue.
Loader heuristics are great if you are the one that implemented them but are
problematic if you are just the user of a software that has them. As time goes
on, these heuristics become buried in thousands of lines of code and they are
often hard yet impossible to trace back.
Different clients of the framework have different requirements. A visualisation
software wants to read in a PDB files as is without making any changes. A
script in an automated pipeline, however, does want to either strictly reject
files that are incomplete or fill-in missing structural features. All these
aspects are implemented in the conop module, separated from the loading of the
PDB file, giving clients a fine grained control over the loading process.
The Builder interface
--------------------------------------------------------------------------------
The conop module defines a :class:`Builder` interface, to run connectivity
algorithms, that is to connect the atoms with bonds and perform basic clean up
of errorneous structures. The clients of the conop module can specify how the
Builder should treat unknown amino acids, missing atoms and chemically
infeasible bonds.
The exact behaviour for a builder is implementation-specific. So far, two
classes implement the Builder interface: A heuristic and a rule-based builder. The builders mainly differ in the source of their connectivity information. The
HeuristicBuilder uses a hard-coded heuristic connectivity table for the 20
standard amino acids as well as nucleotides.For other compounds such as ligands
the HeuristicBuilder runs a distance-based connectivity algorithm that connects
two atoms if they are closer than a certain threshold. The RuleBasedBuilder
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. By default the heuristic builder is used,
however the builder may be switched by setting the !RuleBasedBuilder as the
default. To do so, one has first to create a new instance of a RuleBasedBuilder
and register it in the builder registry of the conop module. In Python, this can
be achieved with
.. code-block:: python
from ost import conop
compound_lib=conop.CompoundLib.Load('...')
rbb=conop.RuleBasedBuilder(compound_lib)
conop.Conopology.Instance().RegisterBuilder(rbb,'rbb')
conop.Conopology.Instance().SetDefaultBuilder('rbb')
All subsequent calls to :func:`io.LoadEntity` will make use of the
RuleBasedBuilder instead of the heuristic builder. See
:ref:`here <mmcif-convert>` for more information on how to create the necessary
files to use the rule-based builder.
.. class:: Builder
.. method:: CompleteAtoms(residue)
add any missing atoms to the residue based on its key, with coordinates set
to zero.
:param residue: must be a valid residue
:type residue: mol.ResidueHandle
.. method:: CheckResidueCompleteness(residue)
verify that the given residue has all atoms it is supposed to have based on
its key.
:param residue: must be a valid residue
:type residue: mol.ResidueHandle
.. method:: IsResidueComplete(residue)
Check whether the residue has all atoms it is supposed to have. Hydrogen
atoms are not required for a residue to be complete.
:param residue: must be a valid residue
:type residue: mol.ResidueHandle
.. method:: IdentifyResidue(residue)
attempt to identify the residue based on its atoms, and return a suggestion
for the proper residue key.
:param residue: must be a valid residue
:type residue: mol.ResidueHandle
.. method:: ConnectAtomsOfResidue(residue)
Connects atoms of residue based on residue and atom name. This method does
not establish inter-residue bonds. To connect atoms that belong to
different residues, use :meth:`ConnectResidueToPrev`, or
:meth:`ConnectResidueToNext`.
:param residue: must be a valid residue
:type residue: mol.ResidueHandle
.. method:: ConnectResidueToPrev(residue, prev)
Connect atoms of residue to previous. The order of the parameters is
important. In case of a polypeptide chain, the residues are thought to be
ordered from N- to C- terminus.
:param residue: must be a valid residue
:type residue: mol.ResidueHandle
:param prev: valid or invalid residue
:type prev: mol.ResidueHandle
.. method:: DoesPeptideBondExist(n, c)
Check if peptide bond should be formed between the `n` and `c` atom. This
method is called by ConnectResidueWithNext() after making sure that
both residues participating in the peptide bond are peptide linking
components.
By default, :meth:`IsBondFeasible` is used to check whether the two atoms
form a peptide bond.
:param n: backbone nitrogen atom (IUPAC name `N`). Must be valid.
:type n: mol.AtomHandle
:param c: backbone C-atom (IUPAC name `C`). Must be valid.
:type c: mol.AtomHandle
.. method:: IsBondFeasible(atom_a, atom_b)
Overloadable hook to check if bond between to atoms is feasible. The
default implementation uses a distance-based check to check if the
two atoms should be connected. The atoms are connected if they are in
the range of 0.8 to 1.2 times their van-der-WAALS radius.
:param atom_a: a valid atom
:type atom_b: mol.AtomHandle
:param atom_a: a valid atom
:type atom_b: mol.AtomHandle
.. method:: GuessAtomElement(atom_name, hetatm)
guess element of atom based on name and hetatm flag
:param atom_name: IUPAC atom name, e.g. `CA`, `CB` or `N`.
:type atom_name: string
:param hetatm: Whether the atom is a hetatm or not
:type hetatm: bool
.. method:: AssignBackboneTorsionsToResidue(residue)
For :meth:`peptide-linking residues <mol.ResidueHandle.IsPeptideLinking>`,
residues, assigns phi, psi and omega torsions to amino acid.
:param residue: must be a valid residue
:type residue: mol.ResidueHandle
.. class:: RuleBasedBuilder
The :class:`RuleBasedBuilder` implements the :class:`Builder` interface.
Refer to its documentation for a basic description of the methods.
.. method:: CheckResidueCompleteness(residue)
By using the description of the chemical compound, the completeness of
the residue is verified. The method distinguishes between required atoms
and atoms that are optional, like `OXT` that is only present, if not
peptide bond is formed. Whenever an unknown atom is encountered,
:meth:`OnUnknownAtom` is invoked. Subclasses of the
:class:`RuleBasedBuilder` may implement some additional logic to deal with
unknown atom. Likewise, whenever a required atom is missing,
:meth:`OnMissingAtom` is invoked. Hydrogen atoms are not considered as
required by default.
:param residue: must be a valid residue
:type residue: mol.ResidueHandle
.. method:: IdentifyResidue(residue)
Looks-up the residue in the database of chemical compounds and returns
the name of the residue or "UNK" if the residue has not been found in the
library.
:param residue: must be a valid residue
:type residue: mol.ResidueHandle
.. method:: OnUnknownAtom(atom)
Invoked whenever an unkknown atom has been encountered during a residue
completeness check.
The default implementation guesses the atom properties based on the name
and returns false, meaning that it should be treated as an unknown atom.
Custom implementations of this method may delete the atom, or modify it.
:param atom: the unknown atom
:type atom: mol.AtomHandle
.. method:: OnMissingAtom(atom)
Invoked whenever an atom is missing. It is up to the overloaded method
to deal with the missing atom, either by ignoring it or by inserting a
dummy atom.
:param atom: The missing atom's name
:type atom: string
Connecting atoms
--------------------------------------------------------------------------------
The high level interface is exposed by the Conopoloy singleton instance:
.. code-block:: python
import conop
cc=conop.Conopology.Instance()
ent=BuildRawModel(...)
cc.ConnectAll(cc.GetBuilder(), ent)
For fine grained control, the builder interface may be used directly.
.. _mmcif-convert:
Convert MM CIF dictionary
--------------------------------------------------------------------------------
The CompoundLib may be created from a MM CIF dictionary. The latest dictionary
can be found on the `wwPDB site <http://www.wwpdb.org/ccd.html>`_.
After downloading the file in MM CIF use the :program:`chemdict_tool` to convert
the MM CIF dictionary into our internal format.
.. code-block:: bash
chemdict_tool create <components.cif> <compounds.chemlib>
:mod:`geom` -- vectors, matrices and geometrical objects
================================================================================
.. module:: geom
:synopsis: Functions and classes for vectors, matrices and geometrical
objects in 2, 3 and four dimensions
The geom modules contains functions and classes for vectors, matrices and other geometrical objects in 2, 3 and four dimensions.
.. toctree::
vec
\ No newline at end of file
Vectors
================================================================================
.. currentmodule:: geom
The :class:`Vec2`, :class:`Vec3`, :class:`Vec4` classes implement vectors in 2, 3 and four dimensions. They support basic arithmetic via overloaded operators. Essentially, the following basic operations are available:
* adding and subtracting two vectors
* negation
* multiplying and dividing by scalar value
This is shown in the following example:
.. code-block:: python
vec_a=geom.Vec2(1, 0)
vec_b=geom.Vec2(0, 1)
print vec_a, vec_b
print vec_a+vec_b
print vec_a*3-vec_b
The standard vector operations are implemented as :ref:`free standing functions <vector-functions>`:
.. code-block:: python
vec_a=geom.Vec3(1, 0, 0)
vec_b=geom.Vec3(0, 1, 0)
print geom.Dot(vec_a, vec_b)
print geom.Cross(vec_a, vec_b)
print geom.Normalize(geom.Vec3(1, 1, 0))
print geom.Length(geom.Vec3(1, 1, 1))
Vector Classes
--------------------------------------------------------------------------------
.. class:: Vec2([x=0.0, y=0.0, z=0.0])
Vec2(vec)
Real-valued vector in 2 dimensions.
:param x: x coordinate
:type x: float or int
:param y: y coordinate
:type y: float or int
:param vec: the coordinates are set to the coordinates of vec. If vec is a
:class:`Vec2`, the coordinates are copied directly, If vec is a
:class:`Vec3`, the x and y coordinates are set to the
coordinates of vec and z is silently swallowed. If vec is of
type :class:`Vec4`, x and y are divided by the homogenous
coordinate w, raising a DivideByZeroException when w is zero.
:type vec: Vec2, Vec3 or Vec4
.. attribute:: x
The x-coordinate of the vector.
:type: float
.. attribute:: y
The y-coordinate of the vector.
.. class:: Vec3([x=0.0, y=0.0, z=0.0])
Vec3(vec)
Real-valued vector in 3 dimensions.
:param x: x coordinate
:param y: y coordinate
:param z: z coordinate
:param vec: the coordinates are set to the coordinates of vec. If vec is a
:class:`Vec3`, the coordinates are copied directly, If vec is a
:class:`Vec2`, the x and y coordinates are set to the
coordinates of vec and z is initialized to zero. If vec is of
type :class:`Vec4`, x, y and z are divided by homogenous
coordinate w, raising a DivideByZeroException when w is zero.
:type vec: Vec2, Vec3 or Vec4
.. attribute:: x
The x-coordinate of the vector.
:type: float or int
.. attribute:: y
The y-coordinate of the vector.
:type: float or int
.. attribute:: z
The z-coordinate of the vector.
:type: float or int
.. class:: Vec4([x=0.0, y=0.0, z=0.0, w=1.0])
Vec4(vec)
Real-valued vector in 4 dimensions.
:param x: x coordinate
:type x: float or int
:param y: y coordinate
:type y: float or int
:param z: z coordinate
:type z: float or int
:param w: w (homogenous) coordinate
:type w: float or int
:param vec: the coordinates are set to the coordinates of vec. If vec is a
:class:`Vec4`, the coordinates are copied directly, If vec is a
:class:`Vec2`, the x and y coordinates are set to the
coordinates of vec and z and w are initialized to 0 and 1,
respectively. If vec is of type :class:`Vec4`, x, y and z are
divided by homogenous coordinate w, raising a
DivideByZeroException when w is zero.
.. attribute:: x
The x-coordinate of the vector.
:type: float or int
.. attribute:: y
The y-coordinate of the vector.
:type: float or int
.. attribute:: z
The z-coordinate of the vector.
:type: float or int
.. attribute:: w
The homogenous coordinate.
:type: float or int
.. _vector-functions:
Functions Operating on Vectors
--------------------------------------------------------------------------------
.. function:: Cross(vec_a, vec_b)
Cross product of `vec_a` and `vec_b`
:type vec_a: Vec3
:type vec_b: Vec3
.. function:: Dot(vec_a, vec_b)
Dot (scalar) product of `vec_a` and `vec_b`
:param vec_a: first vector
:type vec_a: Vec3
:param vec_b: second vector
:type vec_b: Vec3
.. function:: Length(vec)
Length of vector
:param vec:
:type vec: Vec2, Vec3 or Vec4
.. function:: Length2(vec)
Returns the squared length of `vec`
:param vec:
:type vec: Vec2, Vec3 or Vec4
.. function:: Normalize(vec)
Returns a normalized version of `vec`
:param vec: Vector to be normalized
:type vec: Vec2, Vec3 or Vec4
OpenStructure documentation
================================================================================
.. toctree::
geom/doc/geom
conop/doc/conop
mol/base/doc/mol
\ No newline at end of file
Editors
================================================================================
.. currentmodule:: mol
The structure, topology and connectivity of entities is edited via editors. This
includes operations such as changing atom positions, connecting atoms with bonds
as well as adding and removing chains, residues and atoms.
Edit Modes
--------------------------------------------------------------------------------
Editors support two modes: An unbuffered edit mode and a buffered edit mode. In
the unbuffered edit mode, dependent information such as the spatial organizer
and the internal coordinate system (in case of the XCSEditor) are updated after
every change. In buffered edit mode, the updates are delayed until one of the
following happens:
* The last editor goes out of scope.
* :meth:`XCSEditor.UpdateICS` or :meth:`ICSEditor.UpdateXCS` is called
explicitly.
The editors follow the RIAA (resource allocation is initialisation) principle:
Whenever an editor is requested an internal reference counter is incremented. In
the destructor, this reference count is decremented. When the count drops to
zero, the dependent infomation is updated.
In Python, one can not rely on the destructors being called. It is adviced to
always put a call to :meth:`XCSEditor.UpdateICS` or
:meth:`ICSEditor.UpdateXCS` when the editing is finished. Alternatively, starting from Python version 2.6, one can use the
`with <http://docs.python.org/reference/compound_stmts.html#with>`_ statement
to make sure the destructor are called and the dependent information is updated.
Basic Editing Operations
--------------------------------------------------------------------------------
The basic functionality of editors is implemented in the EditorBase class.
.. class:: EditorBase
Inherited by :class:`XCSEditor`, :class:`ICSEditor`.
.. method:: InsertChain(chain_name)
Add new chain to the entity
:param chain_name: The chain's name. In the scope of an entity, chain names
are unique. If a chain of the same already exists an
IntegrityError is raised.
:type chain_name: string
:returns: :class:`ChainHandle`
.. method:: AppendResidue(chain, residue_name, [res_num])
Append residue to the end of the chain. If res_num is not given, the
residue number will be set to the residue number of the last added residue
plus one. The insertion code is the same.
:param chain: Must be a valid chain
:type chain: :class:`ChainHandle`
:param residue_name: 3-letter-code of the residue, e.g. ``GLY``.
:type residue_name: string
:returns: :class:`ResidueHandle`
.. method:: InsertAtom(residue, atom_name, pos, [prop=mol.AtomProp()])
Insert new atom and add it to residue. For atoms with alternative atom
locations use :meth:`InsertAltAtom`.
:param residue: is the parent residue and must be valid
:type residue: :class:`ResidueHandle`
:param atom_name: is the atom name. While free to choose a name, it is
adviced to properly name the atoms according to IUPAC
rules as several algorithms as well as most
:class:`builders <conop.Builder>` in the :mod:`conop`
module rely on proper naming.
:type atom_name: string
:param pos: is the position of the atom in global coordinates
:type pos: :class:`geom.Vec3`
:param prop: are the atom's properties such as element, van der Waals
radius charge and so on. The default set of atom
properties is rather meaningless.
:type prop: class:`AtomProp`
:returns: :class:`AtomHandle`
Editor for the External Coordinate System
--------------------------------------------------------------------------------
The XCSEditor defines the interface for manipulating the external coordinate
system. The external coordinate system directly operates on atom positions in
euclidian space.
.. class:: XCSEditor
Inherits :class:`EditorBase`
.. method:: ApplyTransform(transform)
Apply a transformation the entity transform. The entity transform is a
global transformation applied to all atoms.
:param transform: The transformation to be applied
:type transform: :class:`geom.Mat4`
.. method:: SetTransform(transform)
Set the entity transformation. See also :meth:`ApplyTransform`
:param transform: The transformation to be applied
:type transform: :class:`geom.Mat4`
.. method:: SetAtomPos(atom, pos)
Set the (transformed) position of atom. This method will also update the
original position of the atom by applying the inverse of the entity
transform.
:param atom: must be a valid atom handle
:type atom: :class:`mol.AtomHandle`
:param pos: The new position
:type pos: :class:`geom.Vec3`
.. method:: SetOriginalAtomPos(atom, pos)
Set the origininal (untransformed) position of the atom. This method will
also update the transformed position by applying the entity transform to
the original pos.
:param atom: must be a valid atom handle
:type atom: :class:`mol.AtomHandle`
:param pos: The new untransformed position
:type pos: :class:`geom.Vec3`
Editor for the Internal Coordinate System
--------------------------------------------------------------------------------
The :class:`ICSEditor` is used to manipulate the internal coordinate system that
is defined by bond lengths and angles. By default the internal coordinate system
is not calculates. However, upon requesting an :class:`ICSEditor` for the first
time, the internal coordinate system is initialized. This involves the build-up
of a directed-graph for the bond network as well as calculating the internal
coordinate matrices.
The use :class:`XCSEditor` and :class:`ICSEditor` are mutually exclusive. This
means that whenever a :class:`XCSEditor` has pending changes, the results of
using an :class:`ICSEditor` is undefined and vice versa.
.. class:: ICSEditor
Inherits :class:`EditorBase`
The Molecular Entity
================================================================================
.. currentmodule:: mol
This document describes the :class:`EntityHandle` and related classes.
.. function:: CreateEntity()
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, create a new editor.
:returns: The newly created :class:`EntityHandle`
.. class:: EntityHandle
The entity class represents a molecular structure. Such a structure is in
general made up of one or more linear chains of residues, which in turn are
formed by one or more atoms.
The interface of entities is tailored to biological macromolecules, but this
does not prevent it to be used for molecules in general: An entity also
represent a ligand or a collection of water molecules - hence the rather
generic name.
.. method:: FindChain(chain_name)
Get chain by name. See also :meth:`GetChainList`
:param chain_name: Chain identifier, e.g. "A"
:type chain_name: string
:returns: A valid :class:`ChainHandle`, if the entity contains a
chain with the given name, an invalid
:class:`ChainHandle` otherwise.
.. method:: GetChainList()
Get list of all chains of this entity. To access a single chain, use
:meth:`FindChain`.
:returns: A list of :class:`ChainHandles<ChainHandle>`
.. method:: FindResidue(chain_name, res_num)
Get residue by chain name and residue number. See also
:meth:`GetResidueList`
:param chain_name: Chain identifier, e.g. "A"
:type chain_name: string
:param res_num: residue number
:type res_num: mol.ResNum
:returns: A valid :class:`ResidueHandle` if the chain exists and
the chain contains a residue of the given residue
number, an invalid :class:`ResidueHandle` otherwise.
.. method:: GetResidueList()
Get list of all residues of this entity. To access a single residue, use
:meth:`FindResidue`.
:returns: A list of :class:`ResidueHandles<ResidueHandle>`
.. method:: FindAtom(chain_name, res_num, atom_name)
Get atom by chain name, residue number and atom name. See also
:meth:`GetAtomList`
:param chain_name: Chain identifier, e.g. "A"
:type chain_name: string
:param res_num: residue number
:type res_num: mol.ResNum
:param atom_name: atom name, e.g. CA
:type atom_name: string
:returns: A valid :class:`AtomHandle` if an atom matching the
parameters could be found, an invalid
:class:`AtomHandle` otherwise
.. method:: GetAtomList()
Get list of all atoms of this entity. To access a single atom, use
:meth:`FindAtom`
:returns: A list of :class:`AtomHandles<AtomHandle>`
.. method:: RequestXCSEditor([edit_mode=mol.EditMode.BUFFERED_EDIT])
Request :class:`XCSEditor` for editing the external coordinate system. This
call will fail when there are pending changes of the internal coordinate
system.
:param edit_mode: Must be EditMode.BUFFERED_EDIT or
EditMode.UNBUFFERED_EDIT. For more details, see the
editor documentation.
:type edit_mode: mol.EditMode
:returns: :class:`XCSEditor`
.. method:: RequestICSEditor([edit_mode=mol.EditMode.BUFFERED_EDIT])
Request :class:`ICSEditor` for editing the internal coordinate system, such
as torsions, bond lengths and angle between two bonds. This call will fail
when there are pending changes of the external coordinate system.
:param edit_mode: Must be EditMode.BUFFERED_EDIT or
EditMode.UNBUFFERED_EDIT. For more details, see the
editor documentation.
:type edit_mode: mol.EditMode
:returns: :class:`ICSEditor`
.. method:: Select(query, flags)
Perform a selection on the entity. The result of the selection is an
:class:`EntityView` which contains usually only a subset of chains,
residues, atoms and bonds of the original entity.
:param query: The query to be executed. See :class:`Query` for details.
:type query: string or :class:`Query`
:param flags: An ORed combination of :class:`QueryFlags`.
:type flags: int
:returns: An :class:`entity view <EntityView>`.
:raises: :class:`QueryError` when the query could not be executed due
to syntactic errors.
.. method:: CreateFullView()
Creates an entity view containing all chains, residues, atoms and bonds of
this entity.
.. code-block:: python
# these two lines are identical
full=ent.Select('')
full=ent.CreateFullView()
:returns: :class:`EntityView`
.. method:: CreateEmptyView()
Creates an entity view pointing to this entity, but otherwise empty. This
method is usually the starting point for manual entity view creation, e.g.
.. code-block:: python
view=ent.CreateEmtpyView()
for atom in ent.atoms:
if ComplicatedPredicate(atom):
view.AddAtom(atom)
:returns: :class:`EntityView`
.. method:: Copy()
Creates a deep copy of the entity.
:returns: A new :class:`EntityHandle` that is an exact copy of this entity.
.. note::
alternative atom positions are not handled yet.
.. method:: GetCenterOfAtoms()
Get center of atoms, that is the average atom position of the entity. Use
:meth:`GetCenterOfMass` to calculate the mass-weighted center of the entity.
:returns: :class:`geom.Vec3`
.. method:: GetCenterOfMass()
Calculates the center of mass of the entity. Use :meth:`GetCenterOfAtoms`
to calculate the non-mass-weighted center of the entity.
:returns: :class:`geom.Vec3`
.. method:: GetGeometricCenter()
Calculates the mid-point of the axis aligned bounding box of the entity.
:returns: :class:`geom.Vec3`
.. method:: GetMass()
Calculates the total mass of the entity by summing up the masses of all
atoms.
:returns: The mass in Dalton
.. method:: Apply(visitor)
Apply EntityVisitor to the entity. In Python, you shouldn't bother using
this function. EntityVisitory are mainly used in C++ to implement
algorithms that operate are able to operate on EntityViews or
EntityHandles.
.. method:: FindWithin(pos, radius)
Find all atoms in sphere of given radius centered at *pos*. To turn the
returned list of atoms into an :class:`EntityView`, use
:func:`CreateViewFromAtomList`.
:param pos: Center of sphere
:type pos: :class:`geom.Vec3`
:param radius: The radius of the sphere
:type radius: float
:returns: A list of :class:`AtomHandles<AtomHandle>`
.. class:: ChainHandle
.. method:: FindResidue(res_num)
Get residue by residue number. See also :meth:`GetResidueList`
:param res_num: residue number
:type res_num: mol.ResNum
:returns: A valid :class:`ResidueHandle` if the chain contains
a residue with matching residue number, an invalid
:class:`ResidueHandle` otherwise.
.. method:: GetResidueList()
Get list of all residues of this chain. For peptide chains, the residues
are usually ordered from N- to C-terminus.To access a single residue, use
:meth:`FindResidue`.
:returns: A list of :class:`ResidueHandles<ResidueHandle>`
.. method:: FindAtom(res_num, atom_name)
Get atom by residue number and atom name. See also :meth:`GetAtomList`
:param res_num: residue number
:type res_num: mol.ResNum
:param atom_name: atom name, e.g. CA
:type atom_name: string
:returns: A valid :class:`AtomHandle` if an atom matching the
parameters could be found, an invalid
:class:`AtomHandle` otherwise
.. method:: GetAtomList()
Get list of all atoms of this chain. To access a single atom, use
:meth:`FindAtom`
:returns: A list of :class:`AtomHandles<AtomHandle>`
.. class:: ResidueHandle
.. method:: FindAtom(atom_name)
Get atom by atom name. See also :meth:`GetAtomList`
:param atom_name: atom name, e.g. CA
:type atom_name: string
:returns: A valid :class:`AtomHandle` if an atom with the given
name could be found, an invalid :class:`AtomHandle`
otherwise
.. method:: GetAtomList()
Get list of all atoms of this residue. To access a single atom, use
:meth:`FindAtom`.
.. class:: AtomHandle
.. class:: EntityView
Represents a subpart of an :class:`EntityHandle`.
Functions
--------------------------------------------------------------------------------
Boolean Operators
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. function:: Intersection(view_a, view_b)
Calculates and returns the intersection of `view_a` and `view_b`. `view_a`
and `view_b` must be views of the same entity.
:param view_a: first view
:type view_a: EntityView
:param view_b: second view
:type view_b: EntityView
.. function:: Difference(view_a, view_b)
Calculates and returns the difference between `view_a` and `view_b`. `view_a`
and `view_b` must be views of the same entity.The returned view will
contain atoms, residues, chains and bonds that are in `view_a` and not in
`view_b`.
:param view_a: first view
:type view_a: EntityView
:param view_b: second view
:type view_b: EntityView
.. function:: Union(view_a, view_b)
Calculates and returns the union of `view_a` and `view_b`. `view_a`
and `view_b` must be views of the same entity.The returned view will contain
all atoms, residues, chains and bonds that are either in `view_a`, `view_b`
or part of both views.
:param view_a: first view
:type view_a: EntityView
:param view_b: second view
:type view_b: EntityView
Other Entity-Related Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. function:: CreateViewFromAtomList(atom_list)
Returns a view made up of the atoms in *atom_list*. All atoms are required to
be atoms of the same entity. Duplicate atoms are only added to the view once.
:param atom_list: the atoms
:type atom_list: :class:`AtomHandleList` or :class:`AtomViewList`
:raises: :class:`IntegrityError` if atoms of different entities are
encountered
:returns: :class:`EntityView`
\ No newline at end of file
Queries
================================================================================
.. class:: Query
Blabla
It is often convenient to highlight or focus certain parts of the structure.
OpenStructure includes a powerful query system that allows you to perform custom
selections in a convenient way.
Please refer to the tutorial on the query language for an introduction.
The query language reference
--------------------------------------------------------------------------------
The query consists of one or more predicates combined with boolean
operators. A predicate takes the form *prop op value*. Operators are
one of `` =, !=, >, >=, <=`` and ``<``. A predicate has the following form:
*PROPERTY - OPERATOR - ARGUMENT*.
The following properties may be used in predicates. The supported type of the
value is given for each property.
* ``rname`` residue name. type: string
* ``rnum`` residue number. currently only numeric part is honored.
type: int
* ``rtype`` residue type as given by the DSSP code, i.e. H for helix, E
for extended. type: string
* ``aname`` atom name. type: string
* ``ele`` element of atom. type: string
* ``cname`` chain name. type: string
* ``occ`` occupancy, between 0 and 1. type: float
* ``abfac`` B (temperature) factor of atom. type: float
* ``rbfac`` average B (temperature) factor of residue. type: float.
Note that this does not work for views as expected. When running a
second selection statement on a view, all atoms of the residue handle
and not the view are considered in the calculation
* ``ishetatm`` whether the atom is a hetorogenous atom. type: bool or int
(0 for false, 1 for true)
* ``peptide`` whether the residue is peptide linking. type: bool or int
(0 for false, 1 for true)
* ``x`` X coordinate of atom. type: float
* ``y`` Y coordinate of atom. type: float
* ``z`` Z coordinate of atom. type: float
* ``rindex`` index of residue in chain. This index is the same for views
and handles
* For :ref:`generic properties in queries <genprop-in-queries>` see below.
Distance-based selections within a given atom position are supported by
the within statement. To select atoms within 5 Angstrom of the point
``{1, 2, 3}``, one would write:
``5 <> {1,2,3}``
Negation of this expression is possible with the not operator, i.e.
``not 5 <> {1,2,3}``
will select atoms that are further than five Angstrom apart from ``{1, 2 , 3}``
Abbreviations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Two abbreviations exist for convenience:
Instead of writing
``aname=CA or aname=C or aname=O or aname=N``,
one can write
``aname=CA,N,C,O``.
For integral value ranges, one can use the colon syntax: instead of
``rnum>=10 and rnum<=20``
one can write
``rnum=10:20``
.. _genprop-in-queries:
Generic Properties in Queries
--------------------------------------------------------------------------------
The query language can also be used for numeric generic properties (i.e.
float and int), 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.
.. code-block:: python
# set generic properties for atom, residue, chain
atom_handle.SetGenericFloatProperty("testpropatom", 5.2)
resid_handle.SetGenericFloatProperty("testpropres", 1.1)
chain_handle.SetGenericIntProperty("testpropchain", 10)
# query statements
sel_a=e.Select("gatestpropatom<=10.0")
sel_r=e.Select("grtestpropres=1.0")
sel_c=e.Select("gctestpropchain>5")
Since generic properties do not need to be defined for all parts of an entity
(e.g. it could be specified for one single :class:`AtomHandle`), the query
statement will throw an error unless you specify a default value in the query
statement which can be done using a ':' character:
.. code-block:: python
# if one or more atoms have no generic properties
sel=e.Select("gatestprop=5")
# this will throw an error
# you can specify a default value:
sel=e.Select("gatestprop:1.0=5")
# this will run through smoothly and use 1.0 as
# the default value for all atoms that do not
# have the generic property 'testprop'
Using this method, you will be warned if a generic property is not set for all
atoms, residues or chains unless you specify a default value. So, be careful
when you do.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment