README.txt

.. image:: https://raw.githubusercontent.com/meuleman/epilogos/main/data/logo.png
  :width: 840
  :alt: Epilogos

------


Information-theoretic navigation of multi-tissue functional genomic annotations
===============================================================================

Epilogos is an approach for analyzing, visualizing, and navigating multi-biosample functional genomic annotations, with an emphasis on chromatin state maps generated with e.g. ChromHMM or Segway.

The software provided in this repository implements the methods underlying Epilogos using Python 3.9. We provide a proof-of-principle dataset based on chromatin state calls from the EpiMap dataset (`Boix et al., Nature 2021 <https://www.nature.com/articles/s41586-020-03145-z>`_).

Created by: Wouter Meuleman, Jacob Quon, Alex Reynolds, and Eric Rynes

------


Installation
============

Although not required, it is good practice to create a virtual environment in which
specific versions of Python and its libraries are installed.
This can be done using ``conda``, for instance as such:

.. code-block:: bash

    $ conda init bash  ## only needed upon first use of conda. Restart shell after this.
    $ conda create -n epilogos python=3.9
    $ conda activate epilogos

To install Epilogos simply run the following two commands

.. code-block:: bash

    $ pip install epilogos

Alternatively, install Epilogos directly from the Git repositority using

.. code-block:: bash

    $ pip install git+https://github.com/meuleman/epilogos


Prerequisites
=============

To compute epilogos, you will need to have the following python libraries installed: `statsmodels <https://www.statsmodels.org/stable/index.html>`_, `click <https://click.palletsprojects.com/en/7.x/>`_, `numpy <https://numpy.org/>`_, `scipy <https://www.scipy.org/>`_, `matplotlib <https://matplotlib.org/stable/index.html>`_, `pandas <https://pandas.pydata.org/>`_, `pysam <https://pysam.readthedocs.io/en/latest/api.html>`_, `scikit-learn <https://scikit-learn.org/stable/>`_, `natsort <https://natsort.readthedocs.io/en/stable/>`_, `pyranges <https://pyranges.readthedocs.io/en/latest/autoapi/pyranges/index.html>`_, and `rich <https://rich.readthedocs.io/en/stable/index.html>`_.
These can be installed with one of the following commands

.. code-block:: bash

    $ pip install 'click==8.1.3' 'numpy==1.23.4' 'pandas==1.5.1' 'scipy==1.9.3' 'matplotlib==3.6.1' 'statsmodels==0.13.2' 'scikit-learn==1.1.3' 'pysam==0.19.1' 'natsort==8.2.0' 'pyranges==0.0.117' 'rich==12.6.0'

or while in the epilogos directory

.. code-block:: bash

    $ pip install -r requirements.txt


Additionally, it is recommended that python is updated to version 3.9 or later. We cannot guarantee the validity of results generated by earlier verions of python.


Running Epilogos
================

To be presented with basic documentation of arguments needed to run epilogos, simply run the command ``epilogos --help`` or ``python -m epilogos --help`` (More in-depth explanation is given on the `github README <https://github.com/meuleman/epilogos)>`_).

By default, Epilogos assumes access to a computational cluster managed by `SLURM <https://slurm.schedmd.com/>`_.
A version of epilogos has been created for those without access to a SLURM cluster and can be run by using the ``-l`` flag to your command (e.g. ``epilogos -l``).

--------------

For a more extensive set of documentation, please refer to `our github <https://github.com/meuleman/epilogos>`_.