## TF-MoDISco: Transcription-Factor Motif Discovery from Importance Scores

[![CircleCI](https://circleci.com/gh/kundajelab/tfmodisco.svg?style=shield)](https://app.circleci.com/pipelines/github/kundajelab/tfmodisco) [![license](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000)](https://github.com/kundajelab/tfmodisco/blob/master/LICENSE) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4728132.svg)](https://doi.org/10.5281/zenodo.4728132)

This repository contains the code developed for the associated manuscript, _Distilling consolidated DNA sequence motifs and cooperative motif syntax from neural-network models of in vivo transcription-factor binding profiles_. The analysis scripts and notebooks used to reproduce the results in this manuscript can be found at [this repository](https://github.com/kundajelab/neural_motif_discovery).

General users should visit the [TF-MoDISco-lite repository](https://github.com/jmschrei/tfmodisco-lite/) for a more efficient, actively maintained, and easier-to-use version of the same algorithm.

### Structure of TF-MoDISco

The TF-MoDISco algorithm starts with a set of importance scores on genomic sequences, and can perform the following tasks:

1. Identify high-importance windows of the sequences, termed "seqlets"
2. Cluster recurring similar seqlets into motifs
3. Scan through importance scores across the genome to call motif instances (AKA "hit scoring")

### Installing TF-MoDISco

`pip install modisco`

Alternatively, for a specific tagged version or commit, install from source code by cloning this repository, checking out the desired version, and running `pip install -e /path/to/cloned/repo`.

### Required inputs to run the algorithm

In order to run the TF-MoDISco algorithm, the following data is required as an input:

- An N x L x 4 NumPy array of one-hot encoded genomic sequences, where N is the number of sequences and L is the sequence length (the 4 bases are in A, C, G, T order); this denotes the identity of the sequence
- A parallel N x L x 4 NumPy array of contribution scores; each position contains the importance of the base specified in the corresponding one-hot encoded sequence (i.e. each base position should have at most one nonzero entry out of the 4, which measures importance at the base in the sequence)
- An optional parallel N x L x 4 NumPy array of _hypothetical_ contribution scores, which measures the hypothetical contribution of _every_ base (not just the one that is present in the sequence); equivalently, the element-wise product of this array with the one-hot encoded genomic sequences should be identical to the array of contribution scores

### Other resources

A technical note describing version 0.5.6.5 is available at [https://arxiv.org/abs/1811.00416](https://arxiv.org/abs/1811.00416).

[Video of talk at NeurIPS MLCB 2017](https://www.youtube.com/watch?v=fXPGVJg956E)

Example notebooks for running the algorithm:
- [TF MoDISco TAL GATA](examples/simulated_TAL_GATA_deeplearning/TF_MoDISco_TAL_GATA.ipynb): a self-contained example notebook that uses pre-computed importance scores (generated by a neural network) as input. Scores were generated using deeplift as illustated in [this notebook](examples/simulated_TAL_GATA_deeplearning/Generate%20Importance%20Scores.ipynb). If deeplift doesn't work with your architecture, you could alternatively generate scores using DeepSHAP (DeepSHAP is an extension of DeepLIFT that can work with more diverse architectures) as illustrated in [this notebook](https://github.com/AvantiShri/shap/blob/276bb8cae899a79dedab15c294cd440e57d5695e/notebooks/deep_explainer/Tensorflow%20DeepExplainer%20Genomics%20Example%20With%20Hypothetical%20Importance%20Scores.ipynb) (heads-up: that notebook uses a custom branch of the DeepSHAP repository).
- [TF MoDISco Nanog](examples/H1ESC_Nanog_gkmsvm/TF%20MoDISco%20Nanog.ipynb): a self-contained example notebook that uses pre-computed importance scores and an empirically-generated null distribution (generated by a gkm-SVM) as input. Scores were generated using gkmexplain as illustated in [this notebook](examples/H1ESC_Nanog_gkmsvm/Nanog_GkmExplain_Generate_Data.ipynb). This notebook also illustrates how to use a MEME-based initialization to potentially boost the performance of TF-MoDISco.
