Substitution Profiles Using Related Families (SPURF)

This code repository contains a command line implementation of SPURF, that takes a single antibody heavy chain DNA sequence and returns its inferred substitution profile and a logo plot of this. SPURF uses cached data from a large-scale Rep-Seq dataset as input to a statistical model made to determine a detailed clonal family specific substitution profile for a single input sequence. Source code to fit the SPURF model from scratch using another dataset is also provided. Results and methods are described in our preprint. The dataset used in the paper is available in our Zenodo bucket.

Cloning this repo

Clone this GitHub repo recursively to get the necessary submodules:

git clone --recursive https://github.com/krdav/SPURF.git
cd SPURF
git pull --recurse-submodules https://github.com/krdav/SPURF.git

Installation

There are two supported ways of installing the command line implementation of SPURF: 1) using Conda on Linux and 2) using Docker and the provided Dockerfile. The Conda installation has been tested on our own servers and a fresh Ubuntu installation on a VirtualBox. Using VirtualBox, SPURF can be installed on both Mac and Windows. Alternatively, Docker can also be used on any platform that supports it.

Using Conda

First, install Conda for Python 2. Miniconda is sufficient and much faster at installing. Remember to source ~/.bashrc if continuing installing in the same terminal window.

Install dependencies with apt-get:

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y libz-dev cmake scons libgsl0-dev libncurses5-dev libxml2-dev libxslt1-dev mafft hmmer

Use the INSTALL executable to install the required python environment and partis (via ./INSTALL). After installation, the Conda environment needs to be loaded every time before use, like this:

source activate SPURF

Using Docker

First install Docker.

We have a Docker image on Docker Hub that is automatically kept up to date with the master branch of this repository. It can be pulled and used directly:

sudo docker pull krdav/spurf

Alternatively you can build the container yourself from inside the main repository directory:

sudo docker build -t spurf .

To run this container, use a command such as (see modifications below)

sudo docker run -it -v host-dir:/host krdav/spurf /bin/bash

• replace host-dir with the local directory to which you would like access inside your container
• replace /host with the place you would like this directory to be mounted
• if you built your own container, use spurf in place of krdav/spurf

Detach using ctrl-p ctrl-q.

Running SPURF

SPURF is wrapped into an Rscript named run_SPURF.R that takes three inputs:

1. an antibody heavy chain DNA sequence
2. (optional) the basename for the two output files which are a substitution profile and a logo plot
3. the model type (i.e. l2 or jaccard).

Example run:

Rscript --vanilla run_SPURF.R <input_sequence> <output_base> <model_type>

E.g.:

Rscript --vanilla run_SPURF.R CGCAGGACTGTTGANGCCTTCGGAGACCCTGTCCCTCACCTGCGTTGTCTCTGGCGGGTCCTTCAGTGATTACTACTGGAGCTGGATCCATCAGCCCCCAGGGAAGGGGCTGGAGTGGATTGGGGAAATCAATCATAGTGGGAGCACCAACTACAACCCGTCCCTCGAAAGTCGAGCCACCATATCAGTAGACACGTCCCAGAACAACCTCTCCCTGAAGCTGAGCTCTGTGACCGCCGCGGACTCGGCTGTGTATTACTGTGCGAGAGGCCCGACTACAATGGCTCACGACTTTGACTACTGGGGCCAGGGAACCCTGGTCACC seqXYZ_SPURF_output l2

By default, the model type l2 is used.

Output example

Zooming in on CDR2 and its flanking frameworks: