Skip to content

Latest commit

 

History

History
310 lines (215 loc) · 10.3 KB

README.md

File metadata and controls

310 lines (215 loc) · 10.3 KB
Raw




Build & Test BioConda Install Latest GitHub release follow on Twitter

BioPhi is an open-source antibody design platform. It features methods for automated antibody humanization (Sapiens), humanness evaluation (OASis) and an interface for computer-assisted antibody sequence design.

BioPhi is available at: http://biophi.dichlab.org

Learn more in the BioPhi, Sapiens and OASis in our publication:

David Prihoda, Jad Maamary, Andrew Waight, Veronica Juan, Laurence Fayadat-Dilman, Daniel Svozil & Danny A. Bitton (2022) BioPhi: A platform for antibody design, humanization, and humanness evaluation based on natural antibody repertoires and deep learning, mAbs, 14:1, DOI: https://doi.org/10.1080/19420862.2021.2020203

For more information about the Sapiens antibody language model, see the Sapiens repository

The data and notebooks supporting the analysis are found in: https://github.com/Merck/BioPhi-2021-publication

Intro video

BioPhi Intro Video

Contributing

BioPhi is an open and extensible platform, contributions are welcome.

If you have ideas about what to improve or which tools could be integrated, please submit any feature requests using the Issues tab.

Running BioPhi on your machine

If you don't want to use the public BioPhi server, you can run BioPhi on your own machine.

1. Download OASis database

To run BioPhi with OASis humanness evaluation locally, you will need to download and unzip the OASis database file (22GB uncompressed).

# Download database file
wget https://zenodo.org/record/5164685/files/OASis_9mers_v1.db.gz
# Unzip
gunzip OASis_9mers_v1.db.gz

2. Install BioPhi using Conda

You can install BioPhi using Conda or one of the alternatives (Miniconda, Miniforge).

Install BioPhi using:

# Recommended: Create a separate BioPhi environment
conda create -n biophi python=3.9
conda activate biophi

# Install BioPhi 
# Using Bioconda and Conda-Forge channels
conda install biophi -c bioconda -c conda-forge --override-channels

If conda installation fails, you can try running using Docker. See Run BioPhi using provided Docker image.

3. Run simplified server

# Set up path to OASis database (downloaded and unzipped)
export OASIS_DB_PATH=/path/to/downloaded/OASis_9mers_v1.db

# Run simplified BioPhi server (not for live deployment!)
biophi web

Note: This is simplified usage for local use only. See Deploying your own BioPhi server section below to learn about deploying BioPhi properly on a server.

Run BioPhi using provided Docker image

First, download OASis DB as described above.

Then, run a simplified BioPhi server using the provided Docker image:

docker run \
    -v /your/absolute/path/to/oasis/directory/:/data \
    -e OASIS_DB_PATH=/data/OASis_9mers_v1.db \
    -p 5000:5000 \
    quay.io/biocontainers/biophi:1.0.5--pyhdfd78af_0 \
    biophi web --host 0.0.0.0

The application will be accessible at localhost:5000.

Note: This is simplified usage for local use only. See Deploying your own BioPhi server section below to learn about deploying BioPhi properly on a server.

BioPhi command-line interface

BioPhi also provides a command-line interface that enables bulk processing.

See more 
# Get humanized FASTA
# Expected input: Both chains of each antibody should have the same ID
#                 with an optional _VL/_VH or _HC/_LC suffix
biophi sapiens mabs.fa --fasta-only --output humanized.fa

# Run full humanization & humanness evaluation pipeline
biophi sapiens mabs.fa \
    --oasis-db path/to/downloaded/OASis_9mers_v1.db \
    --output humanized/

# Get the Sapiens probability matrix (score of each residue at each position)
biophi sapiens mabs.fa --scores-only --output scores.csv

# Get mean Sapiens score (one score for each sequence)
biophi sapiens mabs.fa --mean-score-only --output scores.csv

# Get OASis humanness evaluation
biophi oasis mabs.fa \
    --oasis-db path/to/downloaded/OASis_9mers_v1.db \
    --output oasis.xlsx

Development

BioPhi is composed of three services that need to be running at the same time:

  • web: Flask web server that handles both the frontend and the backend of the web application
  • celery: Asynchronous worker service(s) that process long-running tasks
  • redis: In-memory database for storing celery queue tasks and results

Run BioPhi dev server through Docker Compose

Running through Docker Compose is easiest in terms of setup, but web server autoreload is not supported, so you will have to restart the services after each code update.

See more

1. Install Docker

See https://docs.docker.com/get-docker/

2. Clone this repository

Download or clone this repository using:

git clone https://github.com/Merck/BioPhi.git

3. Download OASis DB

Download OASis database as described above. Put it in local data/ dir inside the project folder.

4. Build all images using Docker Compose

# Open BioPhi directory
cd BioPhi    
# Build docker image using Makefile
make docker-build
# or directly using
docker-compose build

4. Run all services using Docker Compose

# Run using Makefile
make docker-run
# or directly using
docker-compose up

The application will be accessible at localhost:5000.

To build and run, you can use:

# Run using Makefile
make docker-build docker-run
# or directly using
docker-compose up --build

5. Handle code updates

After your code is updated, you will need to stop the services, run build and start again. See the next section for info on running locally with flask auto-reload.

Run BioPhi dev server using Conda

Running each service locally using Conda will enable flask auto-reload, which is useful if you are going back and forth between your IDE and the browser.

See more

1. Install Conda

Install Conda or one of the alternatives (Miniconda, Miniforge)

2. Install Redis server

Install and run Redis server. On Mac, you can install Redis using Brew.

3. Clone this repository

Download or clone this repository using:

git clone https://github.com/Merck/BioPhi.git

4. Download OASis DB

Download OASis database as described above.

5. Setup environment

# Open BioPhi directory
cd BioPhi    
# Install dependencies using the provided Makefile
make env
# Or directly using
conda env create -n biophi -f environment.yml
conda activate biophi
pip install -e . --no-deps

6. Run all services

You will have to run each service in a separate terminal (Use Cmd+T to open a new tab):

# Run Redis server (this depends on your installation, the server might already be running)
redis-server

# In a separate terminal, run celery worker queue
export OASIS_DB_PATH=/path/to/OASis_9mers_v1.db
make celery

# In a separate terminal, run flask web server
export OASIS_DB_PATH=/path/to/OASis_9mers_v1.db
make web

See the provided

7. Handle code updates

After your code is updated, the flask web service should refresh automatically. However, the celery service needs to be stopped and started manually, so you will need to do that if you update code that is executed from the workers.

Deploying your own BioPhi server

You can deploy your own internal BioPhi server. You will need to run the three separate services - the flask web server, the celery worker and the redis database.

This will depend on your platform and your cloud provider, the easiest deployment is using Docker Compose through the provided docker-compose.yml file.

For 🐧 Ubuntu deployment, feel free to copy the deployment configs used on the public university server: lich-uct/biophi.dichlab.org

Acknowledgements

BioPhi is based on antibody repertoires from the Observed Antibody Space:

Kovaltsuk, A., Leem, J., Kelm, S., Snowden, J., Deane, C. M., & Krawczyk, K. (2018). Observed Antibody Space: A Resource for Data Mining Next-Generation Sequencing of Antibody Repertoires. The Journal of Immunology, 201(8), 2502–2509. https://doi.org/10.4049/jimmunol.1800708

Antibody numbering is performed using ANARCI:

Dunbar, J., & Deane, C. M. (2016). ANARCI: Antigen receptor numbering and receptor classification. Bioinformatics, 32(2), 298–300. https://doi.org/10.1093/bioinformatics/btv552