CLIPNET

CLIPNET (Convolutionally Learned, Initiation-Predicting NETwork) is an ensembled convolutional neural network that predicts transcription initiation from DNA sequence at single nucleotide resolution. We describe CLIPNET in our preprint on bioRxiv. This repository contains code for working with CLIPNET, namely for generating predictions and feature interpretations and performing in silico mutagenesis scans. To reproduce the figures in our paper, please see the clipnet_paper GitHub repo.

Model card

Model details

CLIPNET is distributed as a 9-fold ensemble of TensorFlow/Keras .h5 models. Each fold accepts a 1000 bp DNA sequence encoded as an array of shape (1000, 4) and returns two outputs:

• profile: a length 1000 vector containing predicted initiation profile for the center 500 bp on the plus strand concatenated with the center 500 bp on the minus strand.
• quantity: a scalar prediction of total PRO-cap quantity across both strands.

The Hugging Face repository contains:

• config.json: metadata describing the ensemble, input encoding, outputs, architecture, and training setup.
• fold_1.h5 through fold_9.h5: the individual model folds.

The clipnet Python package constructs the ensemble by averaging the profile and quantity outputs across all model folds.

Intended use

CLIPNET is intended for research use in regulatory genomics, including transcription initiation prediction from 1000 bp DNA sequences, variant-effect exploration, feature attribution, motif interpretation, and in silico mutagenesis experiments. Inputs may be haploid reference sequences or individualized sequences represented with IUPAC ambiguity codes for unphased heterozygous SNPs.

Training data

CLIPNET was trained on a population-scale PRO-cap dataset from human lymphoblastoid cell lines, paired with individualized 1000 Genomes Project genome sequences. The model was designed around this assay and cellular context, so performance may differ for other cell types, assays, organisms, or sequence distributions.

Limitations

CLIPNET predictions should not be interpreted as direct experimental measurements. The model is trained for the PRO-cap setting described above and may not generalize to substantially different biological contexts. The individualized-sequence workflow represents heterozygous variants with unphased two-hot encodings and considers SNPs rather than all variant classes. Attribution and epistasis analyses can be sensitive to the attribution method, input representation, background choices, and nonlinear model behavior.

Citation

If you use CLIPNET, please cite:

@article{he2024clipnet,
  title = {Personalized deep learning of transcription initiation from population-scale PRO-cap data},
  author = {He, Adam Y. and Danko, Charles G.},
  year = {2024},
  doi = {10.1101/2024.03.13.583868},
  publisher = {bioRxiv}
}

PyTorch reimplementation and port

Code to port the TensorFlow models to PyTorch is available as part of PersonalBPNet, which also includes a from-scratch reimplementation of CLIPNET in PyTorch with a context length of 2114 bp. The below instructions are for working with CLIPNET in TensorFlow.

CODE REFACTORING NOTICE

I have significantly altered the structure of this code base since its original release with the preprint. The new CLIPNET package should be significantly easier to use (pip installable, with clearer CLI and API). To access the code as it was prior to this refactoring, please check out the (unmaintained) deprecated branch.

Installation

To install CLIPNET, we recommend creating an isolated environment. For example, with conda/mamba:

mamba create -n clipnet -c conda-forge python~=3.9
mamba activate clipnet

Then install with pip:

# From PyPI
pip install clipnet
# Or from source:
pip install git+https://github.com/Danko-Lab/clipnet.git

You may need to configure your CUDA/cudatoolkit/cudnn paths to get GPU support working. See the tensorflow documentation for more information.

Download models

Pretrained CLIPNET models are available on Zenodo.

mkdir -p clipnet_models/
for fold in {1..9};
do wget https://zenodo.org/records/10408623/files/fold_${fold}.h5 -P clipnet_models/;
done

Alternatively, they can be accessed via HuggingFace.

Usage

Input data

CLIPNET was trained on a population-scale PRO-cap dataset derived from human lymphoblastoid cell lines, matched with individualized genome sequences (1kGP). CLIPNET accepts 1000 bp sequences as input and imputes PRO-cap coverage (RPM) in the center 500 bp.

CLIPNET can either work on haploid reference sequences (e.g. hg38) or on individualized sequences (e.g. 1kGP). When constructing individualized sequences, we made two major simplifications: (1) We considered only SNPs and (2) we used unphased SNP genotypes.

We encode sequences using a "two-hot" encoding. That is, we encoded each individual nucleotide at a given position using a one-hot encoding scheme, then represented the unphased diploid sequence as the sum of the two one-hot encoded nucleotides at each position. The sequence "AYCR" (= A(C/T)C(A/G)), for example, would be encoded as: [[2, 0, 0, 0], [0, 1, 0, 1], [0, 2, 0, 0], [1, 0, 1, 0]].

Colab examples

Google Colab examples for analyzing and applying CLIPNET are available through the following links:

• Basic tutorial illustrating how to generate predictions and attributions with the models.
• Variant effect prediction and interpretation (TODO)
• MPRA optimization/design (TODO)

Command line interface

CLIPNET can be accessed via a CLI:

clipnet -h

Predictions

The predict command can be used to generate predictions:

clipnet predict -f data/test.fa -o data/test_predictions.npz -m clipnet_models/ -v

The -m flag should be used to specify either a path to the directory containing the CLIPNET models (in which case the averaged predictions across all model replicates will be returned) or a specific model path (in which case only the predictions of that model will be returned).

To input individualized sequences, heterozygous positions should be represented using the IUPAC ambiguity codes R (A/G), Y (C/T), S (C/G), W (A/T), K (G/T), M (A/C).

The output npz file will contain two arrays. The first output ("arr_0", "profile") is a length 1000 vector (500 plus strand concatenated with 500 minus strand) representing the predicted base-resolution profile/shape of initiation. The second output ("arr_1", "quantity") represents the total PRO-cap quantity on both strands.

To generate actual predicted tracks, the profile prediction should be rescaled by the quantity prediction. For example:

import numpy as np

f = np.load("data/test_predictions.npz") 
profile = f["arr_0"]
quantity = f["arr_1"]
profile_scaled = (profile / np.sum(profile, axis=1)[:, None]) * quantity

Attributions

CLIPNET uses DeepSHAP to generate attributions. To generate DeepSHAP scores, use the attribute command. This script takes a fasta file containing 1000 bp records and outputs DeepSHAP attributions and optionally one-hot encoded sequences. Please note that both attribution and ohe are saved as length last for compatibility with tfmodisco-lite.

Two different attribution modes that can be set with -a/--attribution_type: profile and quantity. The profile mode calculates interpretations for the profile node of the model (using the profile metric proposed in BPNet), while the quantity mode calculates interpretations for the quantity node of the model.

clipnet attribute \
    -f data/test.fa.gz \
    -o data/test_quantity_shap.npz \
    -m clipnet_models/ \
    -a quantity \
    -v

# -c maybe needed to avoid precision errors.

Note that while CLIPNET accepts two-hot encoded sequences to accomodate heterozygous positions, attributions are much more interpretable when using a haploid/fully homozygous genome, so we recommend avoiding heterozygous positions for attributions. Also note that these are actual contribution scores, as opposed to hypothetical contribution scores. Specifically, non-reference nucleotides are set to zero. To return attribution scores for all nucleotides, use the -y flag.

Discovering epistatic motifs

clipnet supports epistasis analyses using Deep Feature Interaction Maps (DFIM). Please note that this is a custom reimplementation of DFIM using DeepSHAP as the attribution backend, as the original DFIM package is unmaintained and difficult to install. DFIM scores can be calculated for a given fasta file using the epistasis command:

clipnet epistasis \
    -f data/test.fa \
    -o data/test_dfim_profile.npz \
    -m clipnet_models/ \
    -s 250 -e 750 \
    -a profile \
    -v

Please note DFIM scores don't properly account for things like global epistasis/nonlinearity, which can cause misleading interpretations. For a more robust (but time-consuming) method for estimating interaction effects, see SQUID.

Genomic in silico mutagenesis scans

To generate genomic in silico mutagenesis scans, use the ism_shuffle script. This script takes a fasta file containing 1000 bp records and outputs an npz file containing the ISM shuffle results (corr_ism_shuffle and logfc_ism_shuffle) for each record. For example:

clipnet ism_shuffle -f data/test.fa -o data/test_ism.npz -m clipnet_models/ -v

API usage

CLIPNET models can be directly loaded as follows. Individual models can simply be loaded using tensorflow:

import tensorflow as tf

nn = tf.keras.models.load_model("clipnet_models/fold_1.h5", compile=False)

The model ensemble is constructed by averaging track and quantity outputs across all 9 model folds. To make this easy, we've provided a simple API in the clipnet.clipnet.CLIPNET class for doing this. Moreover, to make reading fasta files into the correct format easier, we've provided the helper function clipnet.utils.get_twohot_fasta_sequences. For example:

import sys
from clipnet.clipnet import CLIPNET
from clipnet.utils import get_twohot_fasta_sequences

nn = CLIPNET()
ensemble = nn.construct_ensemble("clipnet_models/")
seqs = get_twohot_fasta_sequences("data/test.fa")

predictions = ensemble.predict(seqs)