---
title: "_igblastr_ overview"
author:
- name: Hervé Pagès
  affiliation: Fred Hutch Cancer Center, Seattle, WA
- name: Kellie MacPhee
  affiliation: Fred Hutch Cancer Center, Seattle, WA
- name: Ollivier Hyrien
  affiliation: Fred Hutch Cancer Center, Seattle, WA
date: "Compiled `r BiocStyle::doc_date()`; Modified 22 July 2026"
package: igblastr
vignette: |
  %\VignetteIndexEntry{igblastr overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output:
  BiocStyle::html_document:
    toc_float: true
---

<style type="text/css">
p.caption {
  text-align: center;
}
</style>

```{r setup, include=FALSE}
library(BiocStyle)
library(igblastr)
reset_germline_dbs()
reset_c_region_dbs()
```


# Introduction


The Immunoglobulin Basic Local Alignment Search Tool (IgBLAST) is a
specialized bioinformatics tool developed by the National Center for
Biotechnology Information (NCBI) for the analysis of B-cell receptor (BCR)
and T-cell receptor (TCR) sequences (Ye et al., 2013). IgBLAST performs
sequence alignment and annotation, with key outputs including germline
V, D, and J gene assignments; characterization of somatic hypermutations
introduced during affinity maturation; identification of
complementarity-determining regions (CDR1–CDR3), framework
regions (FWR1–FWR4), and isotype; and both nucleotide- and amino acid-level
alignments. These outputs form the basis for many downstream analyses
of BCR and TCR repertoires, including clonotype identification, lineage
tracing, and repertoire feature characterization.

`r Biocpkg("igblastr")` is an R/Bioconductor package that provides functions
to conveniently install and use a local IgBLAST installation from within
R. In addition to performing standard IgBLAST annotation, it offers
additional BCR and TCR sequence annotation capabilities, returning all
results in AIRR-style format.

The package is designed to make it as easy as possible to run IgBLAST in R
by streamlining the installation of IgBLAST and IgBLAST-compatible _germline
databases_. In particular, these installations can be performed with a single
function call, do not require root access, and can persist across R sessions.
Furthermore, when installing IgBLAST-compatible _germline databases_, the
package will also automatically generate IgBLAST-compatible annotations
for the V and J alleles included in the database. These automatic annotations
can then be used as replacements for the _internal data_ and _auxiliary data_
provided by IgBLAST. Note that the latter can be outdated and/or incomplete,
or simply missing when installing a _germline database_ for a non-IgBLAST
organism (IgBLAST only supports human, mouse, rabbit, rat, and rhesus monkey
out of the box).

The main function in the package is `igblastn()`, a wrapper to the `igblastn`
_standalone executable_ included in IgBLAST. In addition to `igblastn()`,
the package provides several other features, including:

- The `install_igblast()` function to conveniently download and
  install a pre-compiled IgBLAST from NCBI.

- A set of built-in IgBLAST-compatible _germline databases_ from
  [OGRDB](https://ogrdb.airr-community.org/), the AIRR Community’s
  Open Germline Receptor Database.

- Functions to download and install IgBLAST-compatible _germline databases_
  from the [IMGT/V-QUEST download site](https://www.imgt.org/download/V-QUEST/),
  and to configure them for use with `igblastn()`.

- The `install_custom_germline_db()` function to install an IgBLAST-compatible
  _germline database_ from user-supplied germline gene allele sequences.

- Functions to compute, access, and manipulate IgBLAST _internal data_
  and _auxiliary data_.

- A set of built-in IgBLAST-compatible constant region (C-region) databases
  from IMGT/V-QUEST.

- Utility functions to parse the results returned by `igblastn()`.

- The `igbrowser()` function to vizualize the annotated sequences in a browser.

- The `percent_mutation()` function to compute the percent mutation in
  the V, D, J segments of a set of BCR or TCR sequences.

- Utility functions to download data from
  [OAS](https://opig.stats.ox.ac.uk/webapps/oas/), the Observed
  Antibody Space database, and prepare it for use with IgBLAST.

Useful links:

- IgBLAST is described at <https://pubmed.ncbi.nlm.nih.gov/23671333/>

- IgBLAST web interface: <https://www.ncbi.nlm.nih.gov/igblast/>

- OGRDB: <https://ogrdb.airr-community.org/>

- IMGT/V-QUEST download site: <https://www.imgt.org/download/V-QUEST/>

Please use <https://github.com/HyrienLab/igblastr/issues> to report bugs,
provide feedback, request features (etc) about `r Biocpkg("igblastr")`.


# Install and load the package


Like any Bioconductor package, `r Biocpkg("igblastr")` should be installed
with `BiocManager::install()`:
```{r, eval=FALSE}
if (!require("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install("igblastr")
```

`BiocManager::install()` will take care of installing the package dependencies
that are missing.

To load `r Biocpkg("igblastr")` into your R session, run:
```{r, message=FALSE}
library(igblastr)
```


# Install and check IgBLAST


## Install IgBLAST

If IgBLAST is already installed on your system, you can tell
`r Biocpkg("igblastr")` to use it by setting the environment variable
`IGBLAST_ROOT` to the path of your IgBLAST installation.
See `?IGBLAST_ROOT` for more information.

Otherwise, simply call `install_igblast()` to install the latest
version of IgBLAST. As of March 2025, NCBI provides pre-compiled
versions of IgBLAST for Linux, Windows, Intel Mac and Mac Silicon.
`install_igblast()` will automatically download the appropriate pre-compiled
version of IgBLAST for your platform from the NCBI FTP site, and install it
in a location that will be remembered across R sessions.
```{r}
if (!has_igblast())
    install_igblast()
```
See `?install_igblast` for more information.

Note that we use `has_igblast()` to avoid reinstalling IgBLAST if
`r Biocpkg("igblastr")` already has access to a working IgBLAST installation.

## Check IgBLAST

To display basic information about the IgBLAST installation used
by `r Biocpkg("igblastr")`, run:
```{r}
igblast_info()
```


# Install and select an IgBLAST-compatible germline database


To analyze BCR or TCR sequences, IgBLAST aligns each of them to a reference
set of germline V, D, and J gene allele sequences. Therefore, in order to
run IgBLAST, we need access to an IgBLAST-compatible _germline database_
against which the sequence to analyze will be aligned. Note that such
database actually consists of three separate BLAST databases bundled
together: the V-, D-, and J-region BLAST databases.

## Built-in germline databases

The `r Biocpkg("igblastr")` package includes a set of built-in
IgBLAST-compatible _germline databases_ for human, mouse, rainbow trout,
and rhesus monkey that were obtained from the OGRDB database (AIRR community).
To get the list of built-in _germline databases_, run:
```{r}
list_germline_dbs(builtin.only=TRUE)
```
The last part of the database name indicates the date of the download in
YYYYMM format.

The `intdata` and `auxdata` columns indicate whether a database includes
its own annotations for the germline V alleles (`intdata` column)
and germline J alleles (`auxdata` column). More on this in the
"[Internal data and auxiliary data](#internal-data-and-auxiliary-data)"
section below.

If the BCR sequences to analyze are from one of the OGRDB organisms then
we can already select the appropriate database with `use_germline_db()`
and skip the subsection below.

## Install additional IgBLAST-compatible germline databases

AIRR/OGRDB and IMGT/V-QUEST are two providers of germline datasets
that can be used to create IgBLAST-compatible _germline databases_.
If, for any reason, none of the built-in AIRR/OGRDB _germline databases_
is suitable (e.g., the sequences to analyze are not from human, mouse, rainbow
trout, or rhesus monkey), then we can use `install_IMGT_germline_db()` to
create and install additional IgBLAST-compatible _germline databases_. Below,
we show how to create and install an IgBLAST-compatible _germline database_
from germline V, D, and J gene sequences available on IMGT/V-QUEST download
site.

### Install an IgBLAST-compatible germline database from IMGT/V-QUEST

First, we list the most recent IMGT/V-QUEST releases:
```{r}
head(list_IMGT_releases())
```

The organisms included in release 202614-2 are:
```{r}
list_IMGT_organisms("202614-2")
```

Next, we create and install an IgBLAST-compatible _germline database_ from
the human germline V, D, and J gene sequences available in IMGT/V-QUEST
release 202614-2:
```{r, message=FALSE}
install_IMGT_germline_db("202614-2", organism="Homo sapiens")
```
See `?install_IMGT_germline_db` for more information.

### Install an IgBLAST-compatible germline database from user-supplied gene allele sequences

The `r Biocpkg("igblastr")` package provides the `install_custom_germline_db()`
function to create and install an IgBLAST-compatible _germline database_ from
a set of user-supplied FASTA files containing germline V/D/J gene allele
nucleotide sequences.

See `?install_custom_germline_db` for more information.

## Select the germline database to use with igblastn()

Finally, we select the newly installed database as the _germline database_
to use with `igblastn()`. For example, assuming that the sequences to
analyze are human antibody sequences:
```{r}
use_germline_db("IMGT-202614-2.Homo_sapiens.IGH+IGK+IGL")
```
See `?use_germline_db` for more information.

To see the full list of cached _germline databases_:
```{r}
list_germline_dbs()
```
Note that the asterisk (`*`) displayed at the far right of the output
from `list_germline_dbs()` indicates the currently selected _germline
database_ (you may need to scroll horizontally to see the asterisk).

See `?list_germline_dbs` for more information.


# Internal data and auxiliary data


Note that the newly installed _germline database_
(`IMGT-202614-2.Homo_sapiens.IGH+IGK+IGL`) includes
its own _internal data_ and _auxiliary data_, as reported in
the `intdata` and `auxdata` columns.

## What are the _internal data_ and _auxiliary data_?

The `intdata` and `auxdata` columns indicate whether a database
includes annotations for the germline V alleles (`intdata` column) and
germline J alleles (`auxdata` column). These annotations consist of
reporting the coding frame start position and FWR/CDR boundaries on
the V and J sequences. Note that the FWR/CDR boundaries on the V sequences
are also known as the V gene delineations. For the J sequences, the only
FWR/CDR boundary is the CDR3/FWR4 boundary.

When analyzing BCR or TCR sequences with IgBLAST, the latter needs
access to this information in order to annotate the former.
In IgBLAST's terminology, the annotations for the germline V and J
alleles are called _internal data_ and _auxiliary data_, respectively.

## IgBLAST-provided internal/auxiliary data

IgBLAST provides _internal data_ and _auxiliary data_ for 5 organisms:
human, mouse, rabbit, rat, and rhesus monkey. We'll sometimes refer to
these organisms as IgBLAST organisms.

This data can be accessed with `load_intdata()` and `load_auxdata()`:
```{r}
head(load_intdata("human"))

head(load_auxdata("human"))
```
See `?load_intdata` and `?load_auxdata` for more information.

However, this data doesn't get updated on a regular basis by the NCBI
folks, and can be incomplete or out-of-sync with the germline V and J
alleles provided by AIRR/OGRDB or IMGT/V-QUEST.

## igblastr-generated internal/auxiliary data

Unlike the _internal data_ and _auxiliary data_ provided by IgBLAST, the
_internal data_ and _auxiliary data_ included in a _germline database_ is
generated by `r Biocpkg("igblastr")`, and is guaranteed to be complete
and in sync with the germline V and J alleles in the database.

This data can also be accessed with `load_intdata()` and `load_auxdata()`:
```{r}
head(load_intdata("IMGT-202614-2.Homo_sapiens.IGH+IGK+IGL"))

head(load_auxdata("IMGT-202614-2.Homo_sapiens.IGH+IGK+IGL"))
```
See `?load_intdata` and `?load_auxdata` for more information.

### How is this data generated?

For the built-in OGRDB _germline databases_ (the `_OGRDB.*` databases),
the _internal data_ and _auxiliary data_ is provided by AIRR/OGRDB.

For a _germline database_ created with `install_IMGT_germline_db()` like
`IMGT-202614-2.Homo_sapiens.IGH+IGK+IGL`:

- _internal data_: The V gene delineations are inferred from the gaps in
  the nucleotide sequences of the V alleles provided by IMGT/V-QUEST.

- _auxiliary data_: The procedure to generate this data is described in
  the `r Biocpkg("igblastr")` Wiki
  [here](https://github.com/HyrienLab/igblastr/wiki/Auxiliary-data-in-igblastr#igblastr-generated-auxiliary-data).

### How to use the igblastr-generated internal/auxiliary data with igblastr?

This happens automatically!

More precisely, if a _germline database_ includes its own _internal data_
and _auxiliary data_, then the `igblastn()` function will use this data
instead of the _internal data_ and _auxiliary data_ provided by IgBLAST.

See documentation of the `custom_internal_data` and `auxiliary_data`
arguments in `?igblastn` for more information.


# Select a constant region database (optional)


The `igblastn` _standalone executable_ included in IgBLAST can also use
constant region (C-region) sequences for sequence annotation. As with the
germline V, D, and J gene allele sequences, the C-region sequences are
expected to originate from the same organism as the sequences to analyze,
and must likewise be formatted as a BLAST database. We will refer to this
database as the C-region database.

The `r Biocpkg("igblastr")` package includes built-in C-region databases
for human, mouse, rabbit, rat, and rhesus monkey, obtained from IMGT/V-QUEST.
The available databases can be listed using:
```{r}
list_c_region_dbs()
```
The last part of the database name indicates the date of the download in
YYYYMM format.

If the sequences to analyze are from one of the organisms listed above,
we can select the appropriate C-region database using `use_c_region_db()`.
For example, assuming that the sequences to analyze are human antibody
sequences:
```{r}
use_c_region_db("_IMGT.human.IGH+IGK+IGL.202605")
```

Calling `list_c_region_dbs()` again should display an asterisk (`*`)
at the far right of the output, indicating the currently selected
C-region database.

See `?list_c_region_dbs` for more information.


# Use igblastn()


Now that we have selected the germline and C-region databases to use
with `igblastn()`, we are almost ready to call `igblastn()` to perform
the alignment.

## Prepare the query sequences

In the context of sequence analysis with IgBLAST, we refer to the set
of sequences to analyze as the _query sequences_.

The `r Biocpkg("igblastr")` package includes a FASTA file containing
8,437 paired heavy- and light-chain human antibody sequences (16,874
individual sequences) retrieved from OAS. This BCR sequencing dataset
will serve as the _query sequences_ that we analyze in this section.

To get the path to the _query sequences_, use:
```{r}
query <- system.file(package="igblastr", "extdata",
                     "BCR", "1279067_1_Paired_sequences.fasta.gz")
```

The `r Biocpkg("igblastr")` package also includes a JSON file containing
metadata describing this BCR sequencing dataset:
```{r}
json <- system.file(package="igblastr", "extdata",
                    "BCR", "1279067_1_Paired_All.json")
query_metadata <- jsonlite::fromJSON(json)
query_metadata
```
The 8,437 paired sequences come from memory B cells isolated from
peripheral blood mononuclear cell (PBMC) samples of a single human
donor (age 38) with no known disease or vaccination history.
The source for these sequences is the Jaffe et al. (2022) study; the
DOI link to the publication is provided above.

## Call igblastn() on the query sequences

To analyze our _query sequences_, we're going to use the `igblastn()`
function. This is a wrapper to the `igblastn` _standalone executable_
included in IgBLAST.

Before calling `igblastn()`, we first check the selected databases by
calling `use_germline_db()` and `use_c_region_db()` with no arguments:
```{r}
use_germline_db()
use_c_region_db()
```

Now, let's call `igblastn()`. Since we are only interested in the best
V alignment for each _query sequence_, we set `num_alignments_V` to 1.
Analyzing this set of 16,874 BCR sequences may take up to around 3 min
on a standard laptop:
```{r}
AIRR_df <- igblastn(query, num_alignments_V=1)
```

By default, the result is an _AIRR-formatted_ tibble, that is, a tibble
with one row per _query sequence_ and many columns:
```{r}
AIRR_df
```

The columns are standard "Rearrangement Schema" fields.
These fields are defined and documented by the AIRR Community at
<https://docs.airr-community.org/en/latest/datarep/rearrangements.html#fields>

You can call `igbrowser()` on `AIRR_df` to visualize the annotated
sequences in a browser. For each sequence, the V, D, J, and C segments
will be shown as well as the FWR1-4 and CDR1-3 regions.

See `?igblastn` and `?igbrowser` for more information.


# Downstream analysis


In this section, we're going to show some examples of simple downstream
analyses that can be performed on the _AIRR-formatted_ tibble returned
by `igblastn()`.

## Distribution of percent mutation across BCR sequences

```{r, message=FALSE}
library(ggplot2)
```

One common analysis of AIRR format data is to examine the distribution of
percent mutation across BCR sequences. Here we analyze the percent mutation
in the V segments of each chain type (heavy, kappa, and lambda) at the
nucleotide level. Note that V percent mutation at the nucleotide level is
100 - `v_identity`:
```{r}
AIRR_df |>
    ggplot(aes(locus, 100 - v_identity)) +
    theme_bw(base_size=14) +
    geom_point(position = position_jitter(width = 0.3), alpha = 0.1) +
    geom_boxplot(color = "blue", fill = NA, outliers = FALSE, alpha = 0.3) +
    ggtitle("Distribution of V percent mutation by locus at the nucleotide level") +
    xlab(NULL)
```

To do the same thing at the amino acid level, we first use the
`percent_mutation()` function to compute the percent mutation in
the V, D, J segments at the amino acid level:
```{r}
perc_mut_aa <- percent_mutation(AIRR_df, for.aa=TRUE)
head(perc_mut_aa)
```
See `?percent_mutation` for more information.

Then:
```{r}
perc_mut_aa |>
    ggplot(aes(locus, v_perc_mut_aa)) +
    theme_bw(base_size=14) +
    geom_point(position = position_jitter(width = 0.3), alpha = 0.1) +
    geom_boxplot(color = "blue", fill = NA, outliers = FALSE, alpha = 0.3) +
    ggtitle("Distribution of V percent mutation by locus at the amino acid level") +
    xlab(NULL)
```

## Distribution of germline genes

```{r, message=FALSE}
library(dplyr)
library(scales)
```

Another common analysis is to investigate the distribution of germline
genes (e.g., V genes). In this case, we typically stratify the analysis
by locus or chain type.
```{r}
plot_gene_dist <- function(AIRR_df, loc) {
    df_v_gene <- AIRR_df |>
        filter(locus == loc) |>
        mutate(v_gene = allele2gene(v_call)) |>  # drop allele info
        group_by(v_gene) |>
        summarize(n = n(), .groups = "drop") |>
        mutate(frac = n / sum(n))
    df_v_gene |>
        ggplot(aes(frac, v_gene)) +
        theme_bw(base_size=13) +
        geom_col() +
        scale_x_continuous('Percent of sequences', labels = scales::percent) +
        ylab("Germline gene") +
        ggtitle(paste0(loc, "V gene prevalence"))
}
```
```{r, fig.height=8}
plot_gene_dist(AIRR_df, "IGH")
```
```{r, fig.height=5.9}
plot_gene_dist(AIRR_df, "IGK")
```
```{r, fig.height=5.3}
plot_gene_dist(AIRR_df, "IGL")
```

## Lengths and motifs of CDR3 sequences

```{r, message=FALSE}
library(ggseqlogo)
```

A third category of analysis focuses on CDR3 sequences, including their
lengths and motifs, which are often visualized using sequence logo plots.
```{r, fig.height=4.5}
AIRR_df$cdr3_aa_length <- nchar(AIRR_df$cdr3_aa)

AIRR_df |>
    group_by(locus, cdr3_aa_length) |>
    summarize(n = n(), .groups = "drop") |>
    ggplot(aes(cdr3_aa_length, n)) +
    theme_bw(base_size=14) +
    facet_wrap(~locus) +
    geom_col() +
    ggtitle("Histograms of CDR3 length by locus")
```

```{r}
AIRR_df |>
    filter(locus == "IGK", cdr3_aa_length == 9) |>
    pull(cdr3_aa) |>
    ggseqlogo(method = "probability") +
    theme_bw(base_size=14) +
    ggtitle("Logo plot of kappa chain CDR3 sequences that are 9 AA long")
```


# Advanced usage


## Passing additional arguments to igblastn()

The `igblastn` _standalone executable_ included in IgBLAST supports many
command line arguments. You can quickly list them with `igblastn_help()`
(or with `igblastn_help(TRUE)` to get an expanded list with more details --
see `?igblastn_help`):
```{r}
igblastn_help()
```

All these command line arguments can be passed to the `igblastn()`
function using the usual `argument_name=argument_value` syntax. For
example, command line argument `-num_threads` allows the user to leverage
IgBLAST built-in parallel computing capabilities. To use it in `igblastn()`,
set argument `num_threads` to the desired value e.g. by
calling `igblastn(query, num_threads=8)`.

Note that the Examples section in `?igblastn` provides more information
about using `igblastn()` in parallel.

## Restrict the search to a subset of user-supplied gene alleles

Some arguments of particular interest are the `germline_db_[VDJ]_seqidlist`
arguments. They allow restricting the search of the _germline database_
to a list of gene alleles supplied by the user. This list can be provided
as a character vector of gene allele identifiers (e.g., `IGHV3-23*01`,
`IGHV3-23*04`, etc..), or as the path to a file containing the identifiers
(one identifier per line). For example:
```{r, eval=FALSE}
V_alleles <- c("IGHV3-23*01", "IGHV3-23*04")
igblastn(query, germline_db_V_seqidlist=V_alleles)
```

If the gene alleles are stored in a file, say in
`path/to/my_V_gene_alleles.txt`, then use:
```{r, eval=FALSE}
igblastn(query, germline_db_V_seqidlist=file("path/to/my_V_gene_alleles.txt"))
```
Note that in this case, the path to the file containing the gene alleles
identifiers must be wrapped in a call to `file()`.

See `?igblastn` for more information.

## Combine germline databases from two different organisms

The `combine_germline_dbs()` function can be used to combine two existing
_germline databases_, typically (but not necessarily) from two different
organisms. This can be useful to analyze BCR sequences from a hybrid organism
like a humanized mouse.

To illustrate this, we're going to analyze BCR sequences from KyDab,
the Kymouse Antibody Database: <https://kydab.naturalantibody.com/>.
In Kymab’s Intelliselect Transgenic mouse (Kymouse), a complete set of
human variable (V), diversity (D), and junction (J) genes of the IGH locus
as well as the V and J genes of the Igλ and Igκ loci were inserted at the
sites of the endogenous mouse loci.

### Prepare the query sequences

We're going to analyze the Kymouse heavy-chain BCR sequences from
the [Influenza #1 Project](https://kydab.naturalantibody.com/influenza-01)
from KyDab. The 3,950 heavy-chain BCR sequences from this project are stored
in the `Influenza-KV7015_heavy.fasta` file included in `r Biocpkg("igblastr")`:
```{r}
fasta_file <- "Influenza-KV7015_heavy.fasta"
query <- system.file(package="igblastr", "extdata",
                     "BCR", "KyDab", fasta_file)
```

### Create the hybrid germline database

For this analysis, we create a hybrid _germline database_ by combining
_germline databases_ from human and mouse. Note that allele names are not
unique across species, so we add suffixes to the human and mouse allele names
to avoid name clashes (e.g., `IGHV2-5*01_Hs` vs. `IGHV2-5*01_Mm`):
```{r}
db_name1 <- "IMGT-202614-2.Homo_sapiens.IGH+IGK+IGL"
db_name2 <- install_IMGT_germline_db("202614-2", "Mus_musculus")

db_name <- "comb.IMGT-202614-2.human+mouse.IGH+IGK+IGL"
combine_germline_dbs(db_name, db_name1, db_name2,
                     suffix1="_Hs", suffix2="_Mm")
```

Select the new hybrid _germline database_ as the database to use
with `igblastn()`:
```{r}
use_germline_db(db_name)

list_germline_dbs()
```

Note that the Kymouse BCR sequences from KyDab project Influenza #1 are
not long enough to reach into the C regions so we're not using any
C-region database for this analysis.

### Call igblastn() on the query sequences

```{r}
AIRR_df <- igblastn(query, num_alignments_V=1,
                           num_alignments_D=1,
                           num_alignments_J=1)
```

### A quick look at columns `v_call`, `d_call`, and `j_call`

In the context of this vignette, we're only going to verify that the Kymouse
heavy-chain sequences align to human V, D, and J alleles:
```{r}
# extract_suffix() assumes suffixes of length 3, e.g. "_Hs"/"_Mm":
extract_suffix <- function(x) {nc <- nchar(x); factor(substr(x, nc-2, nc), levels=c("_Hs", "_Mm"))}

table(extract_suffix(AIRR_df$v_call))
table(extract_suffix(AIRR_df$d_call))
table(extract_suffix(AIRR_df$j_call))
```

These counts are plotted in Figure 1 below.

```{r, echo=FALSE, fig.cap="Number of human vs. mouse V/D/J allele assignments<br>for the 3,950 Kymouse heavy-chain sequences<br>in Influenza-KV7015_heavy.fasta", fig.align="center"}
library(ggplot2)
plot_human_vs_mouse_assignments <- function(AIRR_df)
{
    is_human <- function(allele_name) igblastr:::has_suffix(allele_name, "_Hs")
    is_mouse <- function(allele_name) igblastr:::has_suffix(allele_name, "_Mm")
    gene_type <- factor(rep(c("V", "D", "J"), each=2), levels=c("V", "D", "J"))
    allele_organism <- rep(c("human (_Hs)", "mouse (_Mm)"), 3)
    counts <- c(sum(is_human(AIRR_df$v_call)),
                sum(is_mouse(AIRR_df$v_call)),
                sum(is_human(AIRR_df$d_call), na.rm=TRUE),
                sum(is_mouse(AIRR_df$d_call), na.rm=TRUE),
                sum(is_human(AIRR_df$j_call)),
                sum(is_mouse(AIRR_df$j_call)))
    labs <- counts
    counts[counts == 0L] <- max(counts) * 0.003
    data <- data.frame(`gene type`=gene_type,
                       `allele organism`=allele_organism,
                       `allele assignments`=counts,
                       lab=labs, check.names=FALSE)
    ggplot(data, aes(x=`gene type`, y=`allele assignments`,
                     fill=`allele organism`)) +
        geom_bar(position="dodge", stat="identity") +
        coord_cartesian(ylim=c(0, max(counts) * 1.15)) +
        theme(axis.text=element_text(face="bold")) +
        geom_text(data=data, aes(x=`gene type`, y=`allele assignments`,
                                 label=lab),
                  position=position_dodge(width=0.9), vjust=-1)
}
plot_human_vs_mouse_assignments(AIRR_df)
```
As expected, all Kymouse heavy-chain sequences align to human V and J alleles.
Most also align to human D alleles, with only a small fraction (less than 6%)
aligning to mouse D alleles instead.

## A TCR analysis example

Even though NCBI IgBLAST primary use case is BCR analysis, it can also be used
for TCR sequence analysis, and so does the `r Biocpkg("igblastr")` package.

### Prepare the TCR query sequences

File `SRR11341217.fasta.gz` included in the package contains 10,875
human beta chain TCR transcripts running from 5' of reverse transcription
reaction to beginning of constant region.
See <https://www.ncbi.nlm.nih.gov/sra/SRX7944361> for more information
about this dataset.
```{r}
filename <- "SRR11341217.fasta.gz"
query <- system.file(package="igblastr", "extdata", "TCR", filename)
```

### Install a TCR germline database

To analyze this dataset with `igblastn()`, we need to install and select
a human TCR _germline database_. We can use `install_IMGT_germline_db()` with
the `tcr.db` argument set to `TRUE` for that. This will install a _germline
database_ made of the human TCR germline sequences provided by IMGT/V-QUEST:
```{r, warning=FALSE, message=FALSE}
db_name <- install_IMGT_germline_db("202614-2", organism="Homo sapiens",
                                    tcr.db=TRUE)
```

See the new _germline database_ in the list displayed by `list_germline_dbs()`:
```{r}
list_germline_dbs()
```

Note that:

- The name of this new _germline database_
  (`IMGT-202614-2.Homo_sapiens.TRA+TRB+TRG+TRD`) reflects the fact that
  it contains germline gene alleles from the four T-cell receptor loci:
  TRA (alpha chain), TRB (beta chain), TRG (gamma chain), and TRD (delta chain).

- This new _germline database_ also includes its own _internal data_
  and _auxiliary data_, as reported in the `intdata` and `auxdata` columns.

See `?install_IMGT_germline_db` and `?list_germline_dbs` for more information.

Let's select this new database as the _germline database_ to use
with `igblastn()`:
```{r, message=FALSE}
use_germline_db(db_name)
```
See `?use_germline_db` for more information.

### Select a TCR constant region database (optional)

Use `list_c_region_dbs()` to list the C-region databases that are available:
```{r}
list_c_region_dbs()
```

For this analysis of human TCR sequences, we'll select
`_IMGT.human.TRA+TRB+TRG+TRD.202605` as the C-region database
to use with `igblastn()`:
```{r, message=FALSE}
use_c_region_db("_IMGT.human.TRA+TRB+TRG+TRD.202605")
```
See `?use_c_region_db` for more information.

### Call igblastn() on the TCR query sequences

Check the selected databases:
```{r}
use_germline_db()
use_c_region_db()
```

Call `igblastn()`:
```{r}
AIRR_df <- igblastn(query)
AIRR_df
```

Note that, when using `igblastn()` to analyze TCR sequences, we don't need
to specify the `ig_seqtype` argument like we would have to if we were using
the `igblastn` _standalone executable_ included in IgBLAST.
`igblastn()` will automatically set `ig_seqtype` to `"TCR"` based on the
name of the selected _germline database_. See documentation of the `ig_seqtype`
argument in `?igblastn` for more information.


# Future developments and session information


## Future developments

At the moment, the `r Biocpkg("igblastr")` package does not provide
access to the full functionality of the IgBLAST software. Most notably,
the `igblastp` _standalone executable_ included in IgBLAST has no
counterpart in `r Biocpkg("igblastr")`.

Some future developments include:

- Implement `igblastp()`, a wrapper to the `igblastp` _standalone executable_
  included in IgBLAST for protein-level alignments.

- Add facilities to retrieve arbitrary _germline databases_ from OGRDB,
  the AIRR Community’s Open Germline Receptor Database.

## Session information

Here are the output of `igblast_info()` and `sessionInfo()` on the system
where this document was compiled.

**igblast_info():**
```{r}
igblast_info()
```

**sessionInfo():**
```{r}
sessionInfo()
```

