Free use of the present code is granted under the terms of the GNU General Public License version 3 (GPLv3).

For any issue, question or bug, please write us an email.

The present code, companion of the manuscript "Probabilities of developing HIV-1 bNAb sequence features in uninfected and chronically infected individuals", is conceptually divided in two sections:

1. ig, where we process B-Cell Receptor (BCR) repertoires from either healthy or chronically infected patientes, grouped into three cohorts: "healthy_control", "hiv1", and "hcv". Sequences are firstly annotated through igBlast, then sorted and grouped by cohorts. Secondly, IGoR infers their recombination and evolution statistics, finally producing cohort-specific models.

2. bnabs, where we annotate bNAbs sequences, analyze their features and put them in relation with their probability of generation and evolution, according to the cohort-specific models inferred in the ig section above.

Test datasets of 5'000 BCR heavy- and light-chain IgG sequences for two healthy donors are provided under ig/datasets/, which allows directly running the present code and recapitulating sequence annotation and model building as it was performed in the manuscript. Under bnabs/sequences, we provide the heavy- and light-chain sequences for the bNAbs analyzed in the manuscript, together with a summary of their features relevant for the present analysis (e.g. their neutralization score). IGoR models, inferred on the whole cohort of healthy patients, are also provided under the folder templates/igor_models/inferred, again for testing purposes.

All the scripts, written in Python3, can hence be run with the attached test datasets, with an expected single-core run time of approximatively one hour. However, they rely on a local installation of igBlast and IGoR softwares. Expand the sections below for installation and configuration details (expected installation time of approximately half an hour each). V(D)J templates for igBlast and standard IGoR models are also shipped with this code, under the folder templates.

Finally, though most of the Python packages used in the scripts are quite common (e.g. numpy or pandas), some others are less frequent and could not be alredy present in standard Python3 distributions. It can be the case for the following packages:

• biopython
• PyYAML
• ATrieGC

that can be pip-installed as usual.

The complete set of FASTA files with quality-filtered and assembled IgG sequences (as described in the manuscript) can be downloaded from this link. They are grouped by chain, donor, and finally by cohort. For each sequence, the number of reads in which its UMI was initially found, is reported as Nx in the header, together with the ID of the donor and some other useful info. E.g., >BZR6_100_t0_IgG_1:UID110963:G30292:N40:IGHG:HC, specifies an IGHG isotype heavy chain consensus sequence of 40 reads that comes from healthy control donor 100. This allows to remove low-quality reads (N<3) at any desired step of the downstream analysis.

Corresponding FASTQ files with raw NGS reads for all repertoires have been deposited at the Sequence Read Archive (SRA) with accession number SAMN29624595-713 (BioProject Accession Number PRJNA857338).

igBlast is a powerful and versatile Ig annotation software. We used the following releases:

• blastn: 2.9.0
• igblastn: 1.13.0

with V,D,J templates extracted from IMGT, formatted and attached to this release (under templates).

Please go through the following of this section for the instructions on how to install igBlast and produce the templates in the desired format.

tar xvzf file_name

tar xvzf file_name

chmod -R u+rw *

After a first sequence annotation and a quality filtering through igBlast, BCR sequences are then ready to be analyzed through IGoR software, which allows to infer V(D)J recombination related processes from sequencing data, as well as hyper-mutation statistics.

The underlying methodology and some biologically relevant results are described in the following paper:

• Quentin Marcou, Thierry Mora, Aleksandra M. Walczak. "High-throughput immune repertoire analysis with IGoR". Nature Communications 9, 561 (2018).

We relied on a local installation of the 1.4.1 release.

Please go through the following of this section for the instructions on how to install and use IGoR.

./configure
make
make install

brew install gcc@7

./configure CC="gcc-7" CXX="g++-7"

There are two main scripts, launch_annotation.py and launch_igor.py, respectively for sequence annotation through igBlast and IGoR evaluation and model inference.

The analysis run by each script can be customized through a dedicated .yaml config file. Among the possible accessible parameters, please notice (and modify, if needed) the full path of both igBlast and IGoR executables.

The annotation step can be invoked as:

python3 launch_annotation.py

with settings fully customizable from the config_annotation.yaml file. The user can modify the path of input data, choose the type of chain (heavy, kappa or lambda) and the cohort such data come from, and also if a certain step of the script has to be run or not (e.g., the user can choose to run only the core of igBlast annotation, leaving the parsing of igBlast intermediate output for later).

Its output consists in:

• a .igBlast_statistics file, csv-formatted, with annotation results for each sequence (e.g., best-scoring V template, number and position of point-mutations, and so on);
• a set of .csv and .fasta files, where annotated sequences are sorted, grouped and filtered according to customizable criterions (e.g., include sequences with indels or not, divide in-frame sequences from out-of-frame, and so on).

Both kinds of files are produced separately for each donor, and at the cohort level, by grouping together sequences from different donors belonging to the same cohort under examination.

The IGoR evaluation/inference step, launched through the command:

python3 launch_igor.py

is again fully customizable from the config_igor.yaml file (e.g., the user can choose to run only the alignment step, leaving the inference or the final evaluation for later).

The output consists into a set of folders (aligns, evaluate, inference, output) containing IGoR results, as described in its documentation. In particular, the two files under the inference folder, final_parms.txt and final_marginals.txt, are the ones containing the inferred model to be used later for bNAb evaluation. To this aim, they will also be copied automatically under the template/igor_models/inferred folder.

Also, a .IGoR_summary summary file is produced by combining for each sequence the results from igBlast annotation and IGoR evaluation, potentially useful for a deeper analysis at the single-sequence level, or also to extract summary statistics at the donor or cohort level (e.g., the distribution of the fraction of point-mutated positions) by means of the auxiliary script compute_stats.py.

The "hiv1" cohort can be further stratified by antiretroviral therapy (ART) treatment:

• "hiv1_art_off"
• "hiv1_art_on"

and by serum neutralization breadth:

• "hiv1_non_neutralizers"
• "hiv1_weak_neutralizers"
• "hiv1_intermediate_neutralizers"
• "hiv1_top_neutralizers"

Related IGoR models can be inferred on these sub-cohorts, by modifying the cohort parameter in the config_igor.yaml file.

The auxiliary script script_lineages.py can be used to infer lineages in annotated datasets. This file also contains RAxML commands used to reconstruct phylogenies and ancestral states in largest lineages, and functions to analyze phylogenies to quantify skewedness.

This section includes the bnabs_neutr.csv file, listing the 70 bNAbs analyzed, together with info about their binding site and their neutralization potency. These (and more) info can be retrieved from the CATNAP database.

In order to run this part of the analysis pipeline, one should provide the fasta files for the 70 bnabs of interest (nucleotide sequences are publicly available, e.g. on the CATNAP database linked above), sorting heavy, kappa and lambda chain sequences into three different .fasta files (respectively named as bnabs_seqs_HC.fasta, bnabs_seqs_KC.fasta, and bnabs_seqs_LC.fasta).

Though already annotated, bNAbs can be re-annotated through the command:

python3 launch_annotation.py

in order to extract annotation results in the desired format and to prepare .csv and .fasta files for the following IGoR evaluation step. Again, through the config_annotation.yaml file, the user can customize the path of the input file, choose the type of chain to be analyzed, and so on.

Output files are exactly analogous with those of the ig annotation step.

Finally, by means of IGoR, it is possible to evaluate recombination and evolution probabilities of bNAbs, and correlate them with the neutralization score. Once chosen the desired model in the config_igor.yaml file (among the default IGoR ones or those inferred in the ig step on the three cohorts), the command:

python3 launch_igor.py

allows to get the aforementioned probabilities for each bNAb. The output is of the same kind of that obtained in the ig step (apart from the inference folder, since here bNAbs are just evaluated according to some IGoR models, and not used for further model inference).

Finally, as for the ig step, a .IGoR_summary file is produced (under the bnabs/igor_bnabs_summary folder), combining for each bNAb the results from igBlast annotation and from IGoR evaluation according to a certain model, recombination and hyper-mutation probabilities, and neutralization properties. It's this set of data that is eventually used for the final bNAb analysis in the compute_scores.py auxiliary script, i.e. the assessment of the correlation between their probability of being generated and developed, and their neutralization properties, whose result is stored in a .csv file under the bnabs/neutr_score_prediction folder.