This repository and the calculator it creates are now obsolete and have been replaced by a new and improved calculator. Please see:

• The new calculator at https://jbloomlab.github.io/SARS2-RBD-escape-calc/
• The new GitHub repo at https://github.com/jbloomlab/SARS2-RBD-escape-calc/

The citation for this repository is this paper.

Most data come from Cao et al (2022).

Briefly, the Bloom lab and the group of Yunlong Cao, Sunney Xie, and coworkers at Peking University have used deep mutational scanning to map how all mutations to the SARS-CoV-2 receptor binding domain (RBD) affect binding by antibodies or sera. These "escape maps" are useful for understanding the antigenic impact of viral mutations.

The escape maps for individual antibodies and sera samples have all been published across a wide variety of studies. The goal this repository is to aggregate those data, and enable it to be easily and interactively interrogated.

Specifically, this repository hosts the code for two ways to interact with the data:

• The data are used to generate an "escape calculator" that visualizes the impact of combinations of mutations at https://jbloomlab.github.io/SARS2_RBD_Ab_escape_maps/escape-calc/. The escape-calculator is described in detail in this paper.

• Some data can be visualized and individual escape maps queried using the interactive plots at https://jbloomlab.github.io/SARS2_RBD_Ab_escape_maps. This visualization is no longer being updated with new data.

• The processed data used by the escape calculator are here.

• More complete raw data are:

• Current data used by escape calculator at mutation-level and site-level.

• Old file with data displayed at level of individual maps here. This file is no longer being updated with new data.

Note in the above files, an IC50 of 10 should be taken as corresponding to non-neutralizing.

If you are performing batch analyses of SARS-CoV-2 variants or mutations, you may want to calculate the extent of escape as implemented in the "escape calculator" at https://jbloomlab.github.io/SARS2_RBD_Ab_escape_maps/escape-calc/ in batch. You can do this by downloading the Python module bindingcalculator.py, which provides a Python interface that implements the escape calculator. Here is the documentation for that module (built with pdoc) with pdoc bindingcalculator.py -o docs/_layouts/.

Note that as of Sept-19-2022, we have changed how we get data for the escape calculator. Now all those data come from Cao et al (2022) and we no longer update the antibody-specific visualizations. There are two reasons: first, the data was now too large to display in the old non-calculator format, and second we just want data from that single study.

To build the calculator, first build the conda environment in environment.yml. Then activate that conda environment with:

conda activate SARS2_RBD_Ab_escape_maps

Next open the Jupyter notebooks plot_calculator.ipynb and run it. It creates an interactive Altair chart:

• docs/_includes/escape_calc_chart.html

The interactive chart will be rendered via GitHub pages. Specifically, when updates are pushed to the main branch of the repo on GitHub, it will be rendered at https://jbloomlab.github.io/SARS2_RBD_Ab_escape_maps/escape-calc. See docs/README.md for more information on how the webpage is served via GitHub Pages The notebook also creates the following file, which has the input data for the escape calculator:

• processed_data/escape_calculator_data.csv

Less processed forms of the same data (not collapsed at site level or only for neutralizing antibodies) are here: mutation-level and site-level

The input data on how mutations affect antibody binding or neutralization are in ./data/, and is collated from Bloom lab deep mutational scanning experiments. See ./data/README.md for details on how to add new data.

To process the data to build the interactive visualizations, first build the conda environment in environment.yml. Then activate that conda environment with:

conda activate SARS2_RBD_Ab_escape_maps

Next, process the raw data by running process_data.py:

python process_data.py

This command will process the input data in ./data/ to create the processed data in ./processed_data/. Specifically, the processed data includes the following two files:

• processed_data/escape_data.csv contains the raw escape data for all antibodies / sera.
• processed_data/studies.csv contains information on the studies.

The process_data.py script also adds information about citations to the bottom of docs/index.md for rendering on the webpage.

Finally, open the Jupyter notebooks plot_calculator.ipynb and plot_escape_maps.ipynb and run them. They create two interactive Altair charts:

• docs/_includes/chart.html
• docs/_includes/escape_calc_chart.html

The interactive charts will be rendered via GitHub pages. Specifically, when updates are pushed to the main branch of the repo on GitHub, they will be rendered at https://jbloomlab.github.io/SARS2_RBD_Ab_escape_maps/escape-calc and https://jbloomlab.github.io/SARS2_RBD_Ab_escape_maps. See docs/README.md for more information on how the webpage is served via GitHub Pages

The plot_escape_maps.ipynb notebook also creates the following file, which has the input data for the escape calculator:

• processed_data/escape_calculator_data.csv