Quick Guide
===========

Introduction
------------

``epistasis`` is a Python library that includes models to estimate statistical, high-order epistasis in genotype-phenotype maps. Using this library, you can

    1. Decompose genotype-phenotype maps into high-order epistatic interactions
    2. Find nonlinear scales in the genotype-phenotype map
    3. Calculate the contributions of different epistatic orders and
    4. Estimate the uncertainty in the epistatic coefficients and

For more information about the epistasis models in this library, see our Genetics paper:

    `Sailer, Z. R., & Harms, M. J. (2017). "Detecting High-Order Epistasis in Nonlinear Genotype-Phenotype Maps." Genetics, 205(3), 1079-1088.`_


Simple Example
--------------

Follow these five steps for all epistasis models in this library:

1. **Import a model.** There many models available in the ``epistasis.models`` module. See the full list in the next section.

.. code-block:: python

  from epistasis.models import EpistasisLinearRegression

2. **Initialize a model**. Set the order, choose the type of model (see `Anatomy of an epistasis model`_ for more info), and set any other parameters in the model.

.. _`Anatomy of an epistasis model`: anatomy.html

.. code-block:: python

  model = EpistasisLinearRegression(order=3, model_type='global')

3. **Add some data**. There are three basic ways to do this. 1. Pass data directly to the epistasis model using the ``add_data`` method. 2. Read data from a separate file using one of the ``read_`` methods. 3. (The best option.) load data into a GenotypePhenotypeMap object from the GPMap library and add it to the epistasis model.

.. code-block:: python

  from gpmap import GenotypePhenotypeMap

  datafile = 'data.csv'
  gpm = GenotypePhenotypeMap.read_csv(datafile)

  # Add the data.
  model.add_gpm(gpm)

  # model now has a `gpm` attribute.

4. **Fit the model.** Each model has a simple fit method. Call this to estimate epistatic coefficients. The results are stored the ``epistasis`` attribute.

.. code-block:: python

  # Call fit method
  model.fit()

  # model now has an ``epistasis`` attribute

5. **Plot the results.** The epistasis library has a ``pyplot`` module (powered by matplotlib) with a few builtin plotting functions.

.. code-block:: python

  from epistasis.pyplot import plot_coefs

  fig, ax = plot_coefs(model.epistasis.sites, model.epistasis.values)

.. image:: ../img/basic-example.png

Install and dependencies
------------------------

For users
~~~~~~~~~

This library is now available on PyPi, so it can be installed using pip.

.. code-block:: bash

    pip install epistasis

For developers
~~~~~~~~~~~~~~

For the latest version of the package, you can also clone from Github
and install a development version using pip.

.. code-block:: bash

    git clone https://github.com/harmslab/epistasis
    cd epistasis
    pip install -e .


Dependencies
~~~~~~~~~~~~

The following dependencies are required for the epistasis package.

* gpmap_: Module for constructing powerful genotype-phenotype map python data-structures.
* Scikit-learn_: Simple to use machine-learning API.
* Numpy_: Python's array manipulation package.
* Scipy_: Efficient scientific array manipulations and fitting.
* Pandas_: High-performance, easy-to-use data structures and data analysis tools.

There are also some additional dependencies for extra features included in
the package.

* matplotlib_: Python plotting API.
* ipython_: interactive python kernel.
* `jupyter notebook`_: interactive notebook application for running python kernels interactively.
* ipywidgets_: interactive widgets in python.

.. _gpmap: https://github.com/harmslab/gpmap
.. _Scikit-learn: http://scikit-learn.org/stable/
.. _Numpy: http://www.numpy.org/
.. _Scipy: http://www.scipy.org/
.. _Pandas: http://pandas.pydata.org/
.. _matplotlib: http://matplotlib.org/
.. _ipython: https://ipython.org/
.. _jupyter notebook: http://jupyter.org/
.. _ipywidgets: https://ipywidgets.readthedocs.io/en/latest/

Running tests
-------------

The epistasis package comes with a suite of tests. Running the tests require `pytest`,
so make sure it is installed.

.. code-block:: bash

    pip install -U pytest

Once pytest is installed, run the tests from the base directory of the epistasis package
using the following command.

.. code-block:: bash

    pytest

.. Links for this page

.. _`Sailer, Z. R., & Harms, M. J. (2017). "Detecting High-Order Epistasis in Nonlinear Genotype-Phenotype Maps." Genetics, 205(3), 1079-1088.`: http://www.genetics.org/content/205/3/1079
