OAS-nano Help

About OAS-nano

The Observed VHH Space database (OAS-nano) collates over 73 million unique VHH sequences from 17 different studies. We make the data available for bulk download or you can filter the sequences with respect to certain metadata parameters using our search form, which can be found here.

OAS-nano can be filtered according to attributes such as species, isotype, primer type, and deposition date. The fields are non-exclusive, meaning that the user could choose a combination of fields that does not exist in our database (for instance searching for datasets with a defined subject but undefined age will return no results because no such datasets are present in OAS-nano.)

Data and Downloads

Data in the OAS-nano database is organized into studies that are in turn subdivided into data units. A single data unit is a set of sequences uniquely identified by its metadata. The available metadata parameters are:

  • Author – First author and date of publication.
  • Link – Link to the publication associated with the study.
  • Run – Run ID from which the sequence is derived.
  • Species – Organism of the B-cell donor.
  • Primer – Indicates the type of PCR primer used in the sequencing pathway. For more information, see the note on primer types.
  • Age – Information on the age of the B-cell donor.
  • Subject – Indicates whether the B-cells can be traced back to a particular individual.
  • Isotype – Identified isotype information.
  • Disease – Indicates whether the donor was sick at the time of B-cell extraction.
  • Vaccine – Indicates whether the B-cell donor was purposely immunized prior to B-cell extraction.
  • B-cell subset – Indicates whether a particular B-cell subset was sorted for Ig-seq.
  • B-cell source – Organ or tissue from which the B-cells were extracted.
  • Longitudinal – For longitudinal studies, indicates the time point at which B-cells were collected.
  • Total sequences – Number of redundant sequences in the data unit.
  • Unique sequences – Number of non-redundant sequences in the data unit.
  • Deposition date – Date on which the dataset was deposited in OAS-nano.
  • Last updated – Date on which the dataset was last updated.

After searching, there is an option to download all data-units that match your criteria. This is in the form of a shell script containing consecutive wget commands. To download all the data you can run the following command:

chmod u+rx bulk_download.sh
./bulk_download.sh

A series of .csv.gz files will then be downloaded to your current directory. Each .csv.gz file contains as the first line the metadata for the data-unit and the following lines each sequence and its annotations.

The contents of each data-unit file can look as below:

sequence_id sequence sequence_aa locus stop_codon vj_in_frame v_frameshift productive rev_comp complete_vdj d_frame v_call v_call_species d_call d_call_species j_call j_call_species sequence_alignment germline_alignment sequence_alignment_aa germline_alignment_aa v_alignment_start v_alignment_end d_alignment_start d_alignment_end j_alignment_start j_alignment_end v_sequence_alignment v_sequence_alignment_aa v_germline_alignment v_germline_alignment_aa d_sequence_alignment d_sequence_alignment_aa d_germline_alignment d_germline_alignment_aa j_sequence_alignment j_sequence_alignment_aa j_germline_alignment j_germline_alignment_aa fwr1 fwr1_aa cdr1 cdr1_aa fwr2 fwr2_aa cdr2 cdr2_aa fwr3 fwr3_aa fwr4 fwr4_aa cdr3 cdr3_aa junction junction_length junction_aa junction_aa_length v_score d_score j_score v_cigar d_cigar j_cigar v_support d_support j_support v_identity d_identity j_identity v_sequence_start v_sequence_end v_germline_start v_germline_end d_sequence_start d_sequence_end d_germline_start d_germline_end j_sequence_start j_sequence_end j_germline_start j_germline_end fwr1_start fwr1_end cdr1_start cdr1_end fwr2_start fwr2_end cdr2_start cdr2_end fwr3_start fwr3_end fwr4_start fwr4_end cdr3_start cdr3_end np1 np1_length np2 np2_length v_call_2 v_call_3 v_support_secondary v_support_2 v_support_3 v_score_secondary v_score_2 v_score_3 c_region _species_rank Redundancy ANARCII_numbering tetrad_residues v_call_species_matches_organism d_call_species_matches_organism j_call_species_matches_organism ANARCII_status
DRR378864.223278 CAGGTGCAGCTC... QVQLVESGGGLV... H F T F T T T 0 IGHV3S1*01 alpaca IGHD4*01 alpaca IGHJ6*01 alpaca CAGGTGCAGCTC... CAGGTGCAGCTG... QVQLVESGGGLV... QVQLVESGGGLV... 1 295 306 315 324 370 CAGGTGCAGCTC... QVQLVESGGGLV... CAGGTGCAGCTG... QVQLVESGGGLV... CTATAGGGAC YRD CTATAGCGAC YSD TGACTTTGCGTC... DFASRGQGTRVT... TGACTTTGGTTC... DFGSWGQGTQVT... CAGGTGCAGCTC... QVQLVESGGGLV... GGATTCTCCTTC... GFSFRSFW ATGTATTGGGCC... MYWARQAPGKGL... ATTAATATTAAT... ININGGLT CTCTATTCGGAC... LYSDSVKGRFTI... AGGGGCCAGGGG... RGQGTRVTVSS... GCAAAAGGAAAG... AKGKDAYRDSRG... TGTGCAAAAGGA... 54 CAKGKDAYRDSR... 18 380.457 14.146 56.445 295M87S1N 305S3N10M67S6N 323S1N47M12S 2.710000e-108 2.331 1.590000e-12 91.186 90 87.234 1 295 1 295 306 315 4 13 324 370 2 48 1 75 76 99 100 150 151 174 175 288 337 369 289 336 GAAAGGACGC 10 AGTCGAGG 8 IGHV3S25*01 IGHV3S6*01 2.710000e-108 3.390000e-102 2.210000e-99 380 360 350 AACCCAAGACAC... 0 1 {'fwh1': {'1 ': 'Q', '2 ': 'V', '3 ': 'Q... 42: A, 49: G, 50: L, 52: W True True True |Deletions: 10, 73||||
DRR378864.233899 CAGGTGCAGCTC... QVQLVESGGGLG... H F T F T T T 0 IGHV3S53*01 alpaca IGHD5*01 alpaca IGHJ4*01 alpaca CAGGTGCAGCTC... CAGGTGCAGCTG... QVQLVESGGGLG... QVQLVESGGGLV... 1 291 296 302 305 346 CAGGTGCAGCTC... QVQLVESGGGLG... CAGGTGCAGCTG... QVQLVESGGGLV... GTTGGGG WG GTTGGGG WG ATGCCTCCTGGG... ASWGHGPRVTLA... ATGACTACTGGG... DYWGQGTQVTVS... CAGGTGCAGCTC... QVQLVESGGGLG... GGGACCAGCTTC... GTSFTPES ATGGGCTGGGAC... MGWDRQVPGKER... ATCACTACTCAT... ITTHGST AATTATGCAGAC... NYADSVKDRFTI... TGGGGCCACGGG... WGHGPRVTLAS... AATGCAAAGTGT... NAKCWGNAS... TGTAATGCAAAG... 33 CNAKCWGNASW... 11 336.830 14.146 41.064 291M78S2N 295S9N7M67S3N 304S6N42M23S 3.540000e-95 2.250 6.540000e-08 86.942 100 83.333 1 291 1 291 296 302 10 16 305 346 7 48 1 75 76 99 100 150 151 171 172 285 313 345 286 312 AAGT 4 CA 2 IGHV3S55*01 IGHV3S57*01 3.540000e-95 7.380000e-85 7.380000e-85 336 302 302 AACCCCCTCCAC... 0 1 {'fwh1': {'1 ': 'Q', '2 ': 'V', '3 ': 'Q... 42: D, 49: E, 50: R, 52: V True True True |Deletions: 10, 73||||

For information on sequence notation, please refer to: Nucleic acid notation


A convenient way to parse the csv.gz files, is to use the following code to extract the metadata as a json object and the sequences as a pandas object.


Downloading using Safari: In some cases Safari automatically unzips the .csv.gz files when downloading. This automatic unzipping can cause problems with the downloaded file and it is therefore recommended to either turn off automatic unzipping or use a different browser (e.g. Firefox or Chrome).

Primer types

Before sequencing, VHH sequences are first amplified using PCR. This process uses primers that bind to specific regions of the target sequence. In VHH sequencing, two main primer strategies are commonly used:

  • Nested primers anneal to the IGHV3-specific leader sequence present in both VH and VHH sequences. VH and VHH products are subsequently separated by mass before the VHH fraction is re-amplified. Because this separation is imperfect, nested-primer datasets may contain some VH contamination. Furthermore, only IGHV3-derived sequences are recovered.
  • Hinge primers anneal to the long- or short-hinge regions unique to VHHs. They are paired with either leader primers targeting the IGHV1, IGHV3, and IGHV4 V-gene families or a general framework region 1 (FWR1) primer. Because amplification is specific to the VHH hinge region, hinge-primer datasets largely avoid VH contamination and recover a broader range of V-gene families than nested-primer datasets.

Although some studies use a FWR1 primer rather than family-specific leader primers, no sequences from V-gene families outside IGHV1, IGHV3, and IGHV4 are currently represented in OAS-nano because suitable camelid IMGT reference genes are unavailable for their identification.

Additional primer type:

  • Nested hinge primers combine the nested and hinge primer approaches by performing successive rounds of amplification with general VH/VHH and hinge-specific primers. The amplified VH and VHH products are then separated by mass which is an imperfect process and may result in VH contamination. As with nested primers, this method amplifies only IGHV3-derived sequences.
Primer diagrams
nested_primers hinge_primers nested-hinge_primers

Notes

Germline gene assignment

The V, D, and J genes predicted for each sequence are assigned using IgBLAST with camelid reference gene sets from IMGT. However, the IMGT reference gene sets are incomplete. Only alpaca reference sets are available for D and J genes, while V-gene assignment relies on incomplete reference sets from both alpaca and dromedary camel.

For germline-dependent analyses, such as analysis of somatic hypermutation, ensure that <gene>_call_species_matches_organism is TRUE.

FAQ

How do I bulk-download sequences from OAS-nano?

After filtering OAS-nano using your desired search criteria, you will be taken to a results page. At the top of this page, you'll find a link to a shell script that downloads all matching datasets.

bulk_download

Download the script, then run:

chmod +x bulk_download.sh
./bulk_download.sh

This will download every dataset returned by your search.

I'm creating a pretraining dataset for a machine learning model and want to collect as many VHH sequences as possible. How should I search?

To retrieve all datasets in OAS-nano, set every search field to *. This returns the complete database, allowing you to build a comprehensive pretraining dataset.

I want to investigate the diversity of natural camelid VHH repertoires. How should I search to maximize natural diversity?

To maximize sequence diversity, set Primer to hinge. Hinge primers amplify VHH sequences using the VHH-specific short and long hinge regions and are paired either with leader sequence primers that amplify the IGHV1, IGHV3, and IGHV4 V-gene families or with a general framework region 1 primer.

In contrast, the nested primer strategy uses a primer that binds only to the IGHV3 leader sequence, restricting amplification to IGHV3-derived sequences. No datasets in OAS-nano currently contain sequences from V-gene families outside IGHV1, IGHV3, and IGHV4, despite evidence for the existence of additional families such as IGHV5 and IGHV7, because no IMGT reference sequences are available for these families. Consequently, hinge-primer datasets provide the broadest representation of V-gene family diversity currently available in OAS-nano.

For more information, see the Primer types section.

search_hinge
I'm studying V-gene usage in camelids. How can I obtain the most reliable V-gene assignments?

After selecting your datasets, first filter for species-matched V-gene assignments by retaining only sequences where v_call_species_matches_organism = TRUE. V-gene assignments from other species are not appropriate for analyses of species-specific V-gene usage. Currently, only alpaca sequences in OAS-nano can have species-matched V-gene assignments.

You can further increase confidence by filtering on the v_support column.

To assess confidence at the V-gene family level, examine v_call_2 and v_call_3, which contain the second- and third-ranked V-gene assignments. If these belong to the same V-gene family as the top hit, you can be more confident in the assigned V-gene family.

If v_call_2 and v_call_3 are empty, only a single germline V-gene could be assigned with sufficient confidence. In these cases, the v_call assignment is unambiguous and is particularly well suited for analyses of germline V-gene usage.

Contact

If you would like to contact us about anything related to OAS-nano, please drop an email to opig@stats.ox.ac.uk.

Gillis et al. (In Progress)