diff --git a/docs/examples.rst b/docs/examples.rst index df7eef0b..44e79f28 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -38,12 +38,15 @@ Examples | :ref:`example_analyse_msa` | | An example to illustrate how to analyse a Multiple Sequence Alignment using ConKit | +-------------------------------------------------------------------------------------------------+ +| :ref:`example_plotting_a_map` | +| An example to illustrate how to produce a contact map using ConKit | ++-------------------------------------------------------------------------------------------------+ | :ref:`example_predict_pipeline` | | An example to illustrate how to predict contacts using ConKit | +-------------------------------------------------------------------------------------------------+ - - - +| :ref:`example_construct_hierarchy` | +| An example to illustrate how to manually construct a ConKit hierarchy | ++-------------------------------------------------------------------------------------------------+ .. note:: If you would like an example for a different aspect of ConKit, please let us know in the `GitHub Issue Tracker `_. diff --git a/docs/examples/construct_hierarchy.rst b/docs/examples/construct_hierarchy.rst new file mode 100644 index 00000000..5389aded --- /dev/null +++ b/docs/examples/construct_hierarchy.rst @@ -0,0 +1,65 @@ +.. _example_construct_hierarchy: + +Constructing a ConKit ContactFile Hierarchy +------------------------------------------- + +.. warning:: + This example is kept brief, if you are unable to follow the process or want to know more, check out the source code. + +If you wish to construct it as part of a new development to store your contact information, you might find the following helpful. + +Entities +++++++++ + +1. How to create a Contact? + +.. code-block:: python + + >>> import conkit + >>> contact = conkit.core.Contact(1, 10, 1.0) + +The example above creates a contact between residues ``1`` and ``10`` and assigns a ``raw_score`` of ``1.0`` to it. By default, this contact has many more default attributes assigned, such as the distance value often seen in columns 3 and 4 in the Casp RR format. + +2. How to create a ContactMap? + +.. code-block:: python + + >>> import conkit + >>> cmap = conkit.core.ContactMap('example') + +This example shows you how to create a :obj:`conkit.core.ContactMap` which can store a :obj:`conkit.core.Contact`. + +3. How to create a ContactFile? + +.. code-block:: python + + >>> import conkit + >>> cmap = conkit.core.ContactFile('example') + +This example shows you how to create a :obj:`conkit.core.ContactFile` which can store a :obj:`conkit.core.ContactMap`. + +.. note:: + + In general terms the entities for sequence-related objects are identical, except that they are :obj:`conkit.core.Sequence` and :obj:`conkit.core.SequenceFile`. + +Hierarchy ++++++++++ + +Above is an outline for the different contact-related entities. Each higher entity allows you to store one or more lower-level ones, i.e. you can store one or more :obj:`conkit.core.ContactMap` entities in a single :obj:`conkit.core.ContactFile`. Similarly, you could many :obj:`conkit.core.Contact` entities in a :obj:`conkit.core.ContactMap`; however, be aware that all **must** have unique IDs. + +To illustrate how you can combine the entities, look at the following: + +.. code-block:: python + + >>> import conkit + >>> cfile = conkit.core.ContactFile('example_file') + >>> cmap = conkit.core.ContactMap('example_map') + >>> contact = conkit.core.Contact(1, 10, 1.0) + >>> # Add the contact to the contact map + >>> cmap.add(contact) + >>> # Add the contact map to the contact file + >>> cfile.add(cmap) + +Note, the order in which you add entities does not matter. We could also add the ``cmap`` to the ``cfile`` before adding the ``contact`` to the ``cmap``. + +Once you have constructed your hierarchy, all related functions are available to you. diff --git a/docs/examples/hierarchy.rst b/docs/examples/hierarchy.rst deleted file mode 100644 index f9c1e52c..00000000 --- a/docs/examples/hierarchy.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. _example_constructing_a_hierarchy: - -Hierarchy Construction ----------------------- - -.. note:: - The easiest way to construct a contact file hierarchy is to choose the corresponding parser. - -.. warning:: - This example is kept brief, if you are unable to follow the process or want to know more, check out the source code. - -If you wish to construct it as part of a new development to store your contact information, you might find the following helpful. - -1. Constructing instances -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following blocks of code are purely an outline on how each instance can be created. - -1.1 ContactFile -............... - -.. code-block:: python - - >>> from conkit.core import ContactFile - >>> contact_file = ContactFile('') - -1.2 ContactMap -.............. - -.. code-block:: python - - >>> from conkit.core import ContactMap - >>> contact_map = ContactMap('>> from conkit.core import Contact - >>> contact = Contact('res1_seq', 'res2_seq', 'raw_score') - -.. note:: - The :obj:`conkit.core.Contact` ID is automatically assigned based on ``res1_seq`` and ``res2_seq`` attributes. - -2. Assembling the hierarchy -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To assemble a hierarchy, you want to add :obj:`conkit.core.Contact` instances to a :obj:`conkit.core.ContactMap` instance. Then, you can add one or more :obj:`conkit.core.ContactMap` instances to a single :obj:`conkit.core.ContactFile`. - -Be aware, the IDs for all instances need to be unique at their level, but can be repeated across multiple instances in higher levels. I.e. a ``Contact(1, 2, 0.1)`` can be added only once to ``ContactMap('map_1')`` but added to ``ContactMap('map_2')`` if desired. - -.. code-block:: python - - >>> from conkit.core import Contact, ContactMap, ContactFile - >>> contact_file = ContactFile('example') - >>> for i in range(1, 4): - ... contact_map = ContactMap('map_{0}'.format(i)) - ... - ... for j in range(1, 11): - ... contact = Contact(i, j, 0.1) - ... contact_map.add(contact) - ... - ... contact_file.add(contact_map) - -In the example above we create a single contact file hierarchy that will contain three contact maps with each 10 contacts. Can you see it? -