examples updated/added

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 <https://github.com/fsimkovic/conkit/issues>`_.

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.