From 6a68ee4f654c720775b64e3a5f992eef1b620404 Mon Sep 17 00:00:00 2001 From: JoseEspinosa Date: Thu, 1 Feb 2018 16:19:08 +0100 Subject: [PATCH] Updating docs and comments --- README.md | 3 +- README.rst | 4 +- doc/source/index.rst | 4 +- doc/source/installation.rst | 53 ++++++++++++----- doc/source/quick_start.rst | 114 +++++++++++++++++++++++------------- pergola/intervals.py | 8 +++ setup.py | 2 +- 7 files changed, 127 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 2541886..1a51597 100644 --- a/README.md +++ b/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: diff --git a/README.rst b/README.rst index d8544c1..f0b45ca 100644 --- a/README.rst +++ b/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: diff --git a/doc/source/index.rst b/doc/source/index.rst index 5c65e2f..81b2743 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -34,7 +34,9 @@ Documentation index: ready_to_use_scripts data_analysis - + + visualization + tutorial reference/index diff --git a/doc/source/installation.rst b/doc/source/installation.rst index fd76951..6769f33 100644 --- a/doc/source/installation.rst +++ b/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 diff --git a/doc/source/quick_start.rst b/doc/source/quick_start.rst index c648dc0..98b598c 100644 --- a/doc/source/quick_start.rst +++ b/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 `_. -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 `_. - 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 `_. -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 `_. +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 `_. .. 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 `_ for visualizing the data. IGV can be downloaded from -`here `_. +As an example, we choose the `Integrative Genomics Viewer `_ +to illustrate how to visualize data. IGV can be downloaded from +`here `_. -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 - - - - diff --git a/pergola/intervals.py b/pergola/intervals.py index d4ff626..830826e 100644 --- a/pergola/intervals.py +++ b/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 """ diff --git a/setup.py b/setup.py index 6931c6b..9f235d6 100644 --- a/setup.py +++ b/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",