Updating docs and comments

README.md

@@ -4,7 +4,8 @@ pergola
 ![CircleCI status](https://circleci.com/gh/cbcrg/pergola.png?style=shield)
 
 A python library for the conversion of behavioral data into genome browser 
-compatible formats.
+compatible formats. The adoption of genomic formats enables the analysis and
+visualization of longitudinal behavioral data by genomic software tools.
 
 For more info, installation info and tutorials please visit:
 

README.rst

@@ -7,7 +7,9 @@ pergola
    CircleCI status
 
 A python library for the conversion of behavioral data into genome
-browser compatible formats.
+browser compatible formats. The adoption of genomic formats enables the
+analysis and visualization of longitudinal behavioral data by genomic
+software tools.
 
 For more info, installation info and tutorials please visit:
 

doc/source/index.rst

@@ -34,7 +34,9 @@ Documentation index:
      ready_to_use_scripts
 
      data_analysis
-
+
+     visualization
+
      tutorial
 
      reference/index

doc/source/installation.rst

@@ -3,41 +3,64 @@
 Installation
 ============
 
-Pergola can be download from `Github`_ and compiled (`Installation from github`_). 
-However, we strongly recommend to use Pergola in its containerized version 
-(`Pergola docker container`_).
+``pergola`` is a Python package that works either as a command line tool or a library. Pergola installation involves its
+compilation from the downloaded source code via `Github`_, installing a stable release via `PyPI`_ or to pull the last
+Docker image. We strongly recommend this last option (`Pergola docker image`_) since it provides a ready-to-use,
+portable version of pergola.
 
 .. _Github: https://www.github.com/
+.. _PyPI: https://pypi.python.org/pypi
 
 -------------------------
 Installation from Github
 -------------------------
 
-In this section you will find the details of how to download Pergola source code
-from Github and how to compile. Prerequisites that pergola require installed in 
+In this section you will find the details of how to download ``pergola`` source code via
+Github and how to compile it. Prerequisites that pergola require installed in
 your system are also listed in this section.
 
 .. toctree::
    :maxdepth: 2
 
-   install/installing_pergola
+   install/installing_github
 
 -------------------------
-Pergola Docker container
+Installation via PyPI
 -------------------------
 
-`Docker`_ allows to sandbox an application with all the requirements it needs to run 
-(operating system, software, libraries and dependencies) in a container. 
-Besides avoiding the tedious process of installing all dependencies, 
-the use of Pergola docker images provides the extra benefit of guarantee 
-the reproducibility of your results. Regardless your operating system 
+pergola can be installed using ``pip`` following the instructions described here.
+
+.. toctree::
+   :maxdepth: 2
+
+   install/installing_pypi
+
+-------------------------
+Pergola Docker image
+-------------------------
+
+`Docker`_ allows to sandbox an application with all the requirements it needs to run
+(operating system, software, libraries and dependencies) in a container.
+Besides avoiding the tedious process of installing all dependencies,
+the use of ``pergola`` docker images provides the extra benefit of guarantee
+the reproducibility of your results. Regardless your operating system
 and the software installed in your machine, you can always run your computation
-under the same environment and the same version of Pergola using the tag of 
-the image.  
+under the same environment and the same version of Pergola using the image tag.
+Released images are available at pergola Docker Hub `repository`_.
 
 .. _Docker: https://www.docker.com/
 
+.. _repository: https://hub.docker.com/r/pergola/pergola/
+
 .. toctree::
    :maxdepth: 2
-   
+
    install/pergola_container
+
+.. note::
+    Installation may require admin rights in some cases. In case you don't have them, it might be a good idea to
+    work under a virtual environment. Virtual environments allow you to recreate an isolated environment with all its
+    dependencies without admin rights. You can use several tools to create Python environments as for
+    instance this `one`_.
+
+.. _one: https://github.com/pyenv/pyenv

doc/source/quick_start.rst

@@ -5,79 +5,105 @@ Quick start
 
 If you have to start using Pergola in some easy steps follow this guide.
 
--------------------------
-Get your data
--------------------------
+.. note::
+
+  This quick start guide assumes Pergola has been previously installed, if this is not the case follow instructions in
+  :ref:`installation` section.
 
+.. commented
 .. _input-data:
 
 .. *****************
 .. Zenodo data
 .. *****************
 
-A data set containing motion behavior from *C.elegans* data set is available on `Zenodo <https://zenodo.org/record/582343/files/celegans_unc16_N2.tar.gz>`_.
-Two download all the files inside a folder name data you can follow these commands:
+------------
+Sample data
+------------
 
-.. code-block:: bash
+A data set containing motion behavior from *C.elegans* data set is available on
+`Zenodo <https://sandbox.zenodo.org/record/177697/files/celegans_speed_sample_data.tar.gz>`_.
 
-  mkdir data
-  wget -O- https://zenodo.org/record/582343/files/celegans_unc16_N2.tar.gz | tar xz -C data
+************************
+Sample data description
+************************
 
-.. note::
-
-  Explain in what consi
-
-********************
-Declare equivalence
-********************
+The data set contains *C. elegans* motion measures derived from video recordings originally used on this
+`work <https://www.nature.com/articles/nmeth.2560>`_.
 
-Pergola needs you to set the mappings between the information represented in your behavioral file in order to understand each piece of information inside your
-file, see :ref:`mapping-file` and :ref:`pergola-ontology` for a deeper description. You can download the mapping file for this example `here <https://gist.githubusercontent.com/JoseEspinosa/b49900521c53123108c82832da8d063c/raw/a9f05ec8f67dc19b665f788bc7b986876d1b6320/worm_speed2pergola.txt>`_.
+The sample data set consists in two folders:  One named ``worm_speeds`` containing a ``CSV`` file for each of the
+tracked worms. From the several measures that can be found in the individual files, in this example we will use mid-body
+speed. The ``mapping`` folder contains the ``worm_speed2pergola.txt``, which sets the mappings between the information
+represented in the worm_speed files and the pergola ontology. See :ref:`mapping-file` and :ref:`pergola-ontology` for a
+deeper description.
+
+*************
+Get the data
+*************
+
+Two download the data set from Zenodo you can use this commands:
 
 .. code-block:: bash
 
-  wget -O- https://gist.githubusercontent.com/JoseEspinosa/b49900521c53123108c82832da8d063c/raw/a9f05ec8f67dc19b665f788bc7b986876d1b6320/worm_speed2pergola.txt > ./data/worm_speed2pergola.txt
-    
+  mkdir data
+  wget -O- https://zenodo.org/record/1161078/files/celegans_speed_sample_data.tar.gz | tar xz -C data
+
+------------
+Run Pergola
+------------
+
 ********************
 Pull Pergola image
 ********************
 
+.. installation
+
+.. note::
+
+  If you want to install Pergola on your system instead, refer to :ref:`installation` documentation. And skip this
+  section.
+
 You can obtain last Pergola version from `Pergola Docker Hub repository <https://hub.docker.com/u/pergola/>`_.
 
 .. code-block:: bash
 
   docker pull pergola/pergola:latest 
     
-First we will launch Pergola image mounting the files we need into the container by typing:
+To launch Pergola image and mount the sample data set in the container you can type:
 
 .. code-block:: bash
   
-  docker run --rm -it -v /data:/container_data -w /container_data pergola/pergola bash
+  docker run --rm -it -v "$(pwd)":/container_wd -w /container_wd pergola/pergola:latest bash
 
-.. note::
-
-  If you want to install Pergola on your system instead, refer to :ref:`installation` documentation section.
-
 ************
-Run Pergola
+Execution
 ************
 
-You can know process the downloaded with Pergola using the following command:
+You can know process the downloaded sample data with Pergola using the following command:
 
 .. code-block:: bash
 
-  pergola -i ./data/*.csv -m ./data/worm_speed2pergola.txt -f bedGraph -w 1 -min 0 -max 29000
+  pergola -i ./data/worm_speeds/*.csv -m ./data/mapping/worm_speed2pergola.txt -f bedGraph -w 1 -min 0 -max 29000
+
+The resulting files can be uploaded on a desktop browser for its visualization as explained below.
 
-The resultings files can be uploaded on a desktop browser for its visualization as explained below.
+--------------
+Visualization
+--------------
 
-***************
-Visualize data
-***************
+*************
+Download IGV
+*************
 
-We choose the `Integrative Genomics Viewer <http://software.broadinstitute.org/software/igv/>`_ for visualizing the data. IGV can be downloaded from 
-`here <http://software.broadinstitute.org/software/igv/download>`_. 
+As an example, we choose the `Integrative Genomics Viewer <http://software.broadinstitute.org/software/igv/>`_
+to illustrate how to visualize data. IGV can be downloaded from
+`here <http://software.broadinstitute.org/software/igv/download>`_.
 
-After launching IGV, first you have to create a genome file. Go to **Genomes** menu and click on "Create .genome File..." 
+****************
+Create a genome
+****************
+
+After launching IGV, first you have to create a genome file. Go to **Genomes** menu and click on "Create .genome File..."
 Data can be visualize using a heatmap.
 
 .. image:: ./images/menu_create_genome.png
@@ -86,13 +112,21 @@ On the menu that pops up load the fasta file generated by Pergola and click on O
 
 .. image:: ./images/create_genome.png
 
-Now you can render all BedGraph files generated before by going to **File** menu and click on "Load from File..."
+********************
+Load BedGraph files
+********************
+
+Now you can render the BedGraph files generated before by going to **File** menu and click on "Load from File..."
 
 .. image:: ./images/load_files.png
 
 .. note:: 
   Stack the tracks corresponding to each group, in this manner differences will become easier to identify
-
+
+*********************************
+Set heatmap graphical parameters
+*********************************
+
 Finally to obtain a heatmap of the tracks it is necessary to set some options:
 
 * To visualize all the tracks in the screen go to **Tracks** and click on "Fit Data to Window"
@@ -107,10 +141,6 @@ Finally to obtain a heatmap of the tracks it is necessary to set some options:
 
 .. image:: ./images/heatmap_menu.png
 
-* The resulting rendering shows how overall the speeds of UNC-16 (uncoordinated strain), tracks below, are lower depicting a deficient moving behavior when compared to control (N2) strain on top.
+* The resulting rendering shows how overall the speeds of *unc-16* (uncoordinated strain), tracks below, are lower depicting a deficient moving behavior when compared to control (N2) strain on top.
 
 .. image:: ./images/final_snapshot_heatmap.png
-
-
-
-

pergola/intervals.py

@@ -154,6 +154,12 @@ def _check_delimiter (self, path, delimiter):
         return delimiter
 
     def _reader_data(self):
+        """
+        Reads input file into a generator depending on its formats
+
+        :returns: :py:func:`generator` containing data from input file
+
+        """
         ext = self.path.rpartition('.')[-1].lower()
 
         if ext == "csv":
@@ -172,7 +178,9 @@ def _reader_data(self):
     def _pandas_df_reader(self, df):
         """
         Reads pandas dataframe from excel file and returns generator
+
         :param df: pandas :py:func:`dataframe`
+
         :returns: :py:func:`generator` from excel file
 
         """

setup.py

@@ -26,7 +26,7 @@
 
 PATH = path.abspath(path.split(path.realpath(__file__))[0])
 
-VERSION = "0.1.0"
+VERSION = "0.1.1"
 
 TAGS = [
     "Development Status :: 2 - Pre-Alpha",