Skip to content
Snippets Groups Projects
editors.html 19.38 KiB


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Editors &mdash; OpenStructure v1.0 documentation</title>
    <link rel="stylesheet" href="../../_static/sphinxdoc.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <link rel="top" title="OpenStructure v1.0 documentation" href="../../index.html" />
    <link rel="up" title="mol – Molecular structures and surfaces" href="mol.html" />
    <link rel="next" title="Queries" href="query.html" />
    <link rel="prev" title="The Molecular Entity" href="entity.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="query.html" title="Queries"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="entity.html" title="The Molecular Entity"
             accesskey="P">previous</a> |</li>
        <li><a href="../../index.html">OpenStructure v1.0 documentation</a> &raquo;</li>
          <li><a href="mol.html" accesskey="U"><tt class="docutils literal docutils literal"><span class="pre">mol</span></tt> &#8211; Molecular structures and surfaces</a> &raquo;</li> 
      </ul>
    </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Editors</a><ul>
<li><a class="reference internal" href="#edit-modes">Edit Modes</a></li>
<li><a class="reference internal" href="#basic-editing-operations">Basic Editing Operations</a></li>
<li><a class="reference internal" href="#editor-for-the-external-coordinate-system">Editor for the External Coordinate System</a></li>
<li><a class="reference internal" href="#editor-for-the-internal-coordinate-system">Editor for the Internal Coordinate System</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="entity.html"
                        title="previous chapter">The Molecular Entity</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="query.html"
                        title="next chapter">Queries</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="../../_sources/mol/base/editors.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../../search.html" method="get">
      <input type="text" name="q" size="18" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="editors">
<h1>Editors<a class="headerlink" href="#editors" title="Permalink to this headline">¶</a></h1>
<p>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.</p>
<div class="section" id="edit-modes">
<h2>Edit Modes<a class="headerlink" href="#edit-modes" title="Permalink to this headline">¶</a></h2>
<p>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:</p>
<blockquote>
<ul class="simple">
<li>The last editor goes out of scope.</li>
<li><tt class="xref py py-meth docutils literal"><span class="pre">XCSEditor.UpdateICS()</span></tt> or <tt class="xref py py-meth docutils literal"><span class="pre">ICSEditor.UpdateXCS()</span></tt> is called
explicitly.</li>
</ul>
</blockquote>
<p>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.</p>
<p>In Python, one can not rely on the destructors being called. It is adviced to
always put a call to <tt class="xref py py-meth docutils literal"><span class="pre">XCSEditor.UpdateICS()</span></tt> or
<tt class="xref py py-meth docutils literal"><span class="pre">ICSEditor.UpdateXCS()</span></tt> when the editing is finished. Alternatively, starting from Python version 2.6, one can use the
<a class="reference external" href="http://docs.python.org/reference/compound_stmts.html#with">with</a>  statement
to make sure the destructor are called and the dependent information is updated.</p>
</div>
<div class="section" id="basic-editing-operations">
<h2>Basic Editing Operations<a class="headerlink" href="#basic-editing-operations" title="Permalink to this headline">¶</a></h2>
<p>The basic functionality of editors is implemented in the EditorBase class.</p>
<dl class="class">
<dt id="ost.mol.EditorBase">
<em class="property">class </em><tt class="descclassname">ost.mol.</tt><tt class="descname">EditorBase</tt><a class="headerlink" href="#ost.mol.EditorBase" title="Permalink to this definition">¶</a></dt>
<dd><p>Inherited by <a class="reference internal" href="#ost.mol.XCSEditor" title="ost.mol.XCSEditor"><tt class="xref py py-class docutils literal"><span class="pre">XCSEditor</span></tt></a>, <a class="reference internal" href="#ost.mol.ICSEditor" title="ost.mol.ICSEditor"><tt class="xref py py-class docutils literal"><span class="pre">ICSEditor</span></tt></a>.</p>
<dl class="method">
<dt id="ost.mol.EditorBase.InsertChain">
<tt class="descname">InsertChain</tt><big>(</big><em>chain_name</em><big>)</big><a class="headerlink" href="#ost.mol.EditorBase.InsertChain" title="Permalink to this definition">¶</a></dt>
<dd><p>Add new chain to the entity</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>chain_name</strong> &#8211; The chain&#8217;s name. In the scope of an entity, chain names
are unique. If a chain of the same already exists an
IntegrityError is raised.</li>
</ul>
</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">&lt;pending_xref py:class=&#8221;EditorBase&#8221; py:module=&#8221;ost.mol&#8221; refdoc=&#8221;mol/base/editors&#8221; refdomain=&#8221;py&#8221; refexplicit=&#8221;False&#8221; reftarget=&#8221;ChainHandle&#8221; reftype=&#8221;class&#8221;&gt;&lt;literal classes=&#8221;xref py py-class&#8221;&gt;ChainHandle&lt;/literal&gt;&lt;/pending_xref&gt;</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="ost.mol.EditorBase.AppendResidue">
<tt class="descname">AppendResidue</tt><big>(</big><em>chain</em>, <em>residue_name</em><span class="optional">[</span>, <em>res_num</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#ost.mol.EditorBase.AppendResidue" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>chain</strong> (<em>ChainHandle</em>) &#8211; Must be a valid chain</li>
<li><strong>residue_name</strong> &#8211; 3-letter-code of the residue, e.g. <tt class="docutils literal"><span class="pre">GLY</span></tt>.</li>
</ul>
</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">&lt;pending_xref py:class=&#8221;EditorBase&#8221; py:module=&#8221;ost.mol&#8221; refdoc=&#8221;mol/base/editors&#8221; refdomain=&#8221;py&#8221; refexplicit=&#8221;False&#8221; reftarget=&#8221;ResidueHandle&#8221; reftype=&#8221;class&#8221;&gt;&lt;literal classes=&#8221;xref py py-class&#8221;&gt;ResidueHandle&lt;/literal&gt;&lt;/pending_xref&gt;</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="ost.mol.EditorBase.InsertAtom">
<tt class="descname">InsertAtom</tt><big>(</big><em>residue</em>, <em>atom_name</em>, <em>pos</em><span class="optional">[</span>, <em>prop=mol.AtomProp()</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#ost.mol.EditorBase.InsertAtom" title="Permalink to this definition">¶</a></dt>
<dd><p>Insert new atom and add it to residue. For atoms with alternative atom
locations use <tt class="xref py py-meth docutils literal"><span class="pre">InsertAltAtom()</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>residue</strong> (<em>ResidueHandle</em>) &#8211; is the parent residue and must be valid</li>
<li><strong>atom_name</strong> &#8211; 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
<tt class="xref py py-class docutils literal"><span class="pre">builders</span></tt> in the <tt class="xref py py-mod docutils literal"><span class="pre">conop</span></tt>
module rely on proper naming.</li>
<li><strong>pos</strong> (<em>geom.Vec3</em>) &#8211; is the position of the atom in global coordinates</li>
<li><strong>prop</strong> (<em>AtomProp</em>) &#8211; are the atom&#8217;s properties such as element, van der Waals
radius charge and so on. The default set of atom
properties is rather meaningless.</li>
</ul>
</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">&lt;pending_xref py:class=&#8221;EditorBase&#8221; py:module=&#8221;ost.mol&#8221; refdoc=&#8221;mol/base/editors&#8221; refdomain=&#8221;py&#8221; refexplicit=&#8221;False&#8221; reftarget=&#8221;AtomHandle&#8221; reftype=&#8221;class&#8221;&gt;&lt;literal classes=&#8221;xref py py-class&#8221;&gt;AtomHandle&lt;/literal&gt;&lt;/pending_xref&gt;</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="editor-for-the-external-coordinate-system">
<h2>Editor for the External Coordinate System<a class="headerlink" href="#editor-for-the-external-coordinate-system" title="Permalink to this headline">¶</a></h2>
<p>The XCSEditor defines the interface for manipulating the external coordinate
system. The external coordinate system directly operates on atom positions in
euclidian space.</p>
<dl class="class">
<dt id="ost.mol.XCSEditor">
<em class="property">class </em><tt class="descclassname">ost.mol.</tt><tt class="descname">XCSEditor</tt><a class="headerlink" href="#ost.mol.XCSEditor" title="Permalink to this definition">¶</a></dt>
<dd><p>Inherits <a class="reference internal" href="#ost.mol.EditorBase" title="ost.mol.EditorBase"><tt class="xref py py-class docutils literal"><span class="pre">EditorBase</span></tt></a></p>
<dl class="method">
<dt id="ost.mol.XCSEditor.ApplyTransform">
<tt class="descname">ApplyTransform</tt><big>(</big><em>transform</em><big>)</big><a class="headerlink" href="#ost.mol.XCSEditor.ApplyTransform" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply a transformation the entity transform. The entity transform is a
global transformation applied to all atoms.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>transform</strong> (<em>geom.Mat4</em>) &#8211; The transformation to be applied</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="ost.mol.XCSEditor.SetTransform">
<tt class="descname">SetTransform</tt><big>(</big><em>transform</em><big>)</big><a class="headerlink" href="#ost.mol.XCSEditor.SetTransform" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the entity transformation. See also <a class="reference internal" href="#ost.mol.XCSEditor.ApplyTransform" title="ost.mol.XCSEditor.ApplyTransform"><tt class="xref py py-meth docutils literal"><span class="pre">ApplyTransform()</span></tt></a></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>transform</strong> (<em>geom.Mat4</em>) &#8211; The transformation to be applied</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="ost.mol.XCSEditor.SetAtomPos">
<tt class="descname">SetAtomPos</tt><big>(</big><em>atom</em>, <em>pos</em><big>)</big><a class="headerlink" href="#ost.mol.XCSEditor.SetAtomPos" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>atom</strong> (<a class="reference internal" href="entity.html#ost.mol.AtomHandle" title="ost.mol.AtomHandle"><em>ost.mol.AtomHandle</em></a>) &#8211; must be a valid atom handle</li>
<li><strong>pos</strong> (<em>geom.Vec3</em>) &#8211; The new position</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="ost.mol.XCSEditor.SetOriginalAtomPos">
<tt class="descname">SetOriginalAtomPos</tt><big>(</big><em>atom</em>, <em>pos</em><big>)</big><a class="headerlink" href="#ost.mol.XCSEditor.SetOriginalAtomPos" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>atom</strong> (<a class="reference internal" href="entity.html#ost.mol.AtomHandle" title="ost.mol.AtomHandle"><em>ost.mol.AtomHandle</em></a>) &#8211; must be a valid atom handle</li>
<li><strong>pos</strong> (<em>geom.Vec3</em>) &#8211; The new untransformed position</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="editor-for-the-internal-coordinate-system">
<h2>Editor for the Internal Coordinate System<a class="headerlink" href="#editor-for-the-internal-coordinate-system" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="#ost.mol.ICSEditor" title="ost.mol.ICSEditor"><tt class="xref py py-class docutils literal"><span class="pre">ICSEditor</span></tt></a> 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 <a class="reference internal" href="#ost.mol.ICSEditor" title="ost.mol.ICSEditor"><tt class="xref py py-class docutils literal"><span class="pre">ICSEditor</span></tt></a> 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.</p>
<p>The use <a class="reference internal" href="#ost.mol.XCSEditor" title="ost.mol.XCSEditor"><tt class="xref py py-class docutils literal"><span class="pre">XCSEditor</span></tt></a> and <a class="reference internal" href="#ost.mol.ICSEditor" title="ost.mol.ICSEditor"><tt class="xref py py-class docutils literal"><span class="pre">ICSEditor</span></tt></a> are mutually exclusive. This
means that whenever a <a class="reference internal" href="#ost.mol.XCSEditor" title="ost.mol.XCSEditor"><tt class="xref py py-class docutils literal"><span class="pre">XCSEditor</span></tt></a> has pending changes, the results of
using an <a class="reference internal" href="#ost.mol.ICSEditor" title="ost.mol.ICSEditor"><tt class="xref py py-class docutils literal"><span class="pre">ICSEditor</span></tt></a> is undefined and vice versa.</p>
<dl class="class">
<dt id="ost.mol.ICSEditor">
<em class="property">class </em><tt class="descclassname">ost.mol.</tt><tt class="descname">ICSEditor</tt><a class="headerlink" href="#ost.mol.ICSEditor" title="Permalink to this definition">¶</a></dt>
<dd><p>Inherits <a class="reference internal" href="#ost.mol.EditorBase" title="ost.mol.EditorBase"><tt class="xref py py-class docutils literal"><span class="pre">EditorBase</span></tt></a></p>
</dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="query.html" title="Queries"
             >next</a> |</li>
        <li class="right" >
          <a href="entity.html" title="The Molecular Entity"
             >previous</a> |</li>
        <li><a href="../../index.html">OpenStructure v1.0 documentation</a> &raquo;</li>
          <li><a href="mol.html" ><tt class="docutils literal docutils literal"><span class="pre">mol</span></tt> &#8211; Molecular structures and surfaces</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2010, OpenStructure authors.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0b2.
    </div>
  </body>
</html>