LISA: Landscape In-Silico deletion Analysis

.. image:: https://raw.githubusercontent.com/liulab-dfci/lisa2/master/docs/example_clustermap.png :width: 200px

.. contents:: Table of Contents

About

LISA is a statistical test for the influence of Transcription Factors on a set of genes. We leverage integrative modeling of public chromatin accessiblity and factor binding to make predictions that go beyond simple co-expression analysis. The minimum you need to run LISA is a list of genes-of-interest, but you can also supply your own epigenetic background. For more information, see Qin et al., 2020 <https://genomebiology.biomedcentral.com/articles/10.1186/s13059-020-1934-6>_. This implementation extends the original, running faster, reducing dependencies, and adding useful CLI functions for pipeline integration.

The python package is easy to install and has a rich set of features and options. For a quick introduction to the method, check out the web interface <http://lisa.cistrome.org/>_.

The Model

The key components of the LISA test are the:

1. profile, a distribution of accessibility over regions in the genome, supplied by user or predicted from public data
2. hits, the regions where a TF is predicted to bind (through ChIP-seq or motif)
3. region-gene map, maps the influence of a region to nearby genes.

First, LISA constructs a null model of gene influence, which assumes each accessible region is occupied by its associated factors, and that all factor-bound regions exert influence on nearby genes. LISA then tests for the influence of a factor on a gene by calculating what proportion of that gene's influence could be attributed to that factor binding nearby regions. When you provide genes-of-interest, LISA finds factors that preferentially affects these genes over a sampling of background genes.

.. image:: https://raw.githubusercontent.com/liulab-dfci/lisa2/master/docs/model_diagram.png :width: 300

Refer to the User Guide <https://github.com/liulab-dfci/lisa2/blob/master/docs/user_guide.md> to see it in action. Refer to the Data Analysis Guide <https://github.com/liulab-dfci/lisa2/blob/master/docs/DataAnalysisGuide.md> to see the questions LISA can help you answer.

Requirements

• Mac or Linux OS
• Python 3.6+
• 15 GB of available storage space

Installation

LISA will install data into the virutal environment's "site_packages" directory, so ensure the env's location can store ~10GB.

PyPI

It is recommended to install lisa to a virtual environment:

.. code-block:: bash

  $ python3 -m venv .venvs/lisa_env
  $ source .venvs/lisa_env/bin/activate

Install LISA to this virtual env using this command:

.. code-block:: bash

  (lisa_env) $ pip install lisa2

Conda

First, create a virtual environment:

.. code-block:: bash

(base) $ conda create --name lisa_env (base) $ conda activate lisa_env

Then install from Conda:

.. code-block:: bash

(lisa_env) $ conda install -c liulab-dfci lisa2

Dataset Installation Issues

If you successfully install lisa but the program fails while downloading data, follow these `manual dataset installation instructions <https://github.com/liulab-dfci/lisa2/blob/master/docs/troubleshooting.md>`_.

Usage
-----

Command Line Interface

LISA's cli offers convenient methods for the most common use cases. See the API <https://github.com/liulab-dfci/lisa2/blob/master/docs/cli.rst>_, or try:

.. code-block::

(lisa_env) $ lisa {command} --help

for parameter descriptions. See the User Guide <https://github.com/liulab-dfci/lisa2/blob/master/docs/user_guide.md>_ for best practices.

Python Interface

The python module allows more control over the LISA test and more convenient data analysis. See the `Python API <https://github.com/liulab-dfci/lisa2/blob/master/docs/python_api.rst>`_ 
and the `User Guide <https://github.com/liulab-dfci/lisa2/blob/master/docs/user_guide.md>`_.

Changelog
---------

**[2.3.0] - 2022-03-15**

Removed

Removed coverage test from base LISA install because pyBigWig was causing problems with installation. Now, to install the coverage test, do

.. code-block:: bash

$ pip install lisa2[coverage]

Changed

* Loosening H5py requirements for easier install.

**[2.2.4] - 2021-03-01**

* Added "lisa deseq" interface for parsing DESeq2 output files for fast LISA tests of DE genes

**[2.2.0] - 2021-01-10**

Added

• Added "FromRegions" test, and moved all older functionalities to "FromGenes". New feature allows user to run LISA test with their own regions-of-interest
• Added "query_reg_score" and "background_reg_score" matrices to output metadata of "FromRegions" test, which allows user to see which genes are likely regulated by each factor.
• New backend interface for faster file transfers
• Added ability to append more data to backend for future updates, including ATAC-seq epigenetic backgrounds
• Added more documentation and user guide
• Appended new ATAC data and reprocessed motifs using JASPAR database

Removed

* Removed "cores" option from multi and oneshot tests, and removed mutliprocessing from package. 
* Removed "one-vs-rest" test because proved to provide unstable results

**[2.1.0] - 2020-12-01**

* Bugfixes in output of "lisa multi" test
* Refactored classes for future extension to user-supplied fragment files and peaks
* Added integration testing
* Added factor accessibility introspection to results printout
* Made RP maps substitutable for future tests
* Made assays modular so users can specify which statistical tests they are interested in

**[2.0.6] - 2020-11-22**

* Support for Lisa version 1 API for integration with LISA website
* Bugfixes in motif mode results
* Slight speedups in parallelization of insilico-delition computing

Support
-------

If you have questions, requests, or issues, please email alynch@ds.dfci.harvard.edu.