README.md

Basenji

Sequential regulatory activity predictions with deep convolutional neural networks.

Basenji provides researchers with tools to:

1. Train deep convolutional neural networks to predict regulatory activity along very long chromosome-scale DNA sequences
2. Score variants according to their predicted influence on regulatory activity across the sequence and/or for specific genes.
3. Annotate the distal regulatory elements that influence gene activity.
4. Annotate the specific nucleotides that drive regulatory element function.

---

Basset successor

This codebase offers numerous improvements and generalizations to its predecessor Basset, and I'll be using it for all of my ongoing work. Here are the salient changes.

1. Basenji makes predictions in bins across the sequences you provide. You could replicate Basset's peak classification by simply providing smaller sequences and binning the target for the entire sequence.
2. Basenji intends to predict quantitative signal using regression loss functions, rather than binary signal using classification loss functions.
3. Basenji is built on TensorFlow, which offers myriad benefits, including distributed computing and a large and adaptive developer community.

However, this codebase is general enough to implement the Basset model, too. I have instructions for how to do that here.

---

Akita

3D genome folding predictions with deep convolutional neural networks.

Akita provides researchers with tools to:

1. Train deep convolutional neural networks to predict 2D contact maps along very long chromosome-scale DNA sequences
2. Score variants according to their predicted influence on contact maps across the sequence and/or for specific genes.
3. Annotate the specific nucleotides that drive genome folding.

---

Saluki

mRNA half-life predictions with a hybrid convolutional and recurrent deep neural network.

Saluki provides researchers with tools to:

1. Train deep convolutional and recurrent neural networks to predict mRNA half-life from an mRNA sequence annotated with the first frame of each codon and splice site positions.
2. Score variants according to their predicted influence on mRNA half-life, on full-length mRNAs or for a set of pre-defined variants.

A full reproduction of the results presented in the paper, involving variant prediction, motif discovery, and insertional motif anlaysis, can be found here.

---

Installation

Basenji/Akita were developed with Python3 and a variety of scientific computing dependencies, which you can see and install via requirements.txt for pip and environment.yml for Anaconda. For each case, we kept TensorFlow separate to allow you to choose the install method that works best for you. The codebase is compatible with the latest TensorFlow 2, but should also work with 1.15.

Run the following to install dependencies and Basenji with Anaconda.

    conda env create -f environment.yml
    conda install tensorflow (or tensorflow-gpu)
    python setup.py develop --no-deps

Alternatively, if you want to guarantee working versions of each dependency, you can install via a fully pre-specified environment.

    conda env create -f prespecified.yml
    conda install tensorflow (or tensorflow-gpu)
    python setup.py develop --no-deps

Or the following to install dependencies and Basenji with pip and setuptools.

    python setup.py develop
    pip install tensorflow (or tensorflow-gpu)

Then we recommend setting the following environmental variables.

  export BASENJIDIR=~/code/Basenji
  export PATH=$BASENJIDIR/bin:$PATH
  export PYTHONPATH=$BASENJIDIR/bin:$PYTHONPATH

To verify the install, launch python and run

    import basenji

---

Manuscripts

Models and (links to) data studied in various manuscripts are available in the manuscripts directory.

---

Documentation

At this stage, Basenji is something in between personal research code and accessible software for wide use. The primary challenge is uncertainty in what the best role for this type of toolkit is going to be in functional genomics and statistical genetics. The computational requirements don't make it easy either. Thus, this package is under active development, and I encourage anyone to get in touch to relate your experience and request clarifications or additional features, documentation, or tutorials.

• Preprocess
  • bam_cov.py
  • basenji_hdf5_single.py
  • basenji_hdf5_cluster.py
  • basenji_hdf5_genes.py
• Train
  • basenji_train.py
• Accuracy
  • basenji_test.py
  • basenji_test_genes.py
• Regulatory element analysis
  • basenji_motifs.py
  • basenji_sat.py
  • basenji_map.py
• Variant analysis
  • basenji_sad.py
  • basenji_sed.py
  • basenji_sat_vcf.py

---

Tutorials

These are a work in progress, so forgive incompleteness for the moment. If there's a task that you're interested in that I haven't included, feel free to post it as an Issue at the top.

• Preprocess
  • Preprocess new datasets for training.
• Train/test
  • Train and test a model.
• Gene expression
  • Test gene expression predictions.
• Study
  • Execute an in silico saturated mutagenesis
  • Compute SNP Activity Difference (SAD) and Expression Difference (SED) scores.