require(IgGeneUsage)
require(rstan)
require(knitr)
require(ggplot2)
require(ggforce)
require(ggrepel)
require(reshape2)
require(patchwork)
Decoding the properties of immune receptor repertoires (IRRs) is key to understanding how our adaptive immune system responds to challenges, such as viral infection or cancer. One important quantitative property of IRRs is their immunoglobulin (Ig) gene usage, i.e. how often are the differnt Igs that make up the immune receptors used in a given IRR. Furthermore, we may ask: is there differential gene usage (DGU) between IRRs from different biological conditions (e.g. healthy vs tumor).
Both of these questions can be answered quantitatively by are answered by IgGeneUsage.
The main input of IgGeneUsage is a data.frame that has the following columns:
IgGeneUsage transforms the input data as follows.
First, given \(R\) repertoires with \(G\) genes each, IgGeneUsage generates a gene usage matrix \(Y^{R \times G}\). Row sums in \(Y\) define the total usage (\(N\)) in each repertoire.
Second, for the analysis of DGU between biological conditions, we use a Bayesian model (\(M\)) for zero-inflated beta-binomial regression. Empirically, we know that Ig gene usage data can be noisy also not exhaustive, i.e. some Ig genes that are systematically rearranged at low probability might not be sampled, and certain Ig genes are not encoded (or dysfunctional) in some individuals. \(M\) can fit over-dispersed and zero-inflated Ig gene usage data.
In the output of IgGeneUsage, we report the mean effect size (es or \(\gamma\)) and its 95% highest density interval (HDI). Genes with \(\gamma \neq 0\) (e.g. if 95% HDI of \(\gamma\) excludes 0) are most likely to experience differential usage. Additionally, we report the probability of differential gene usage (\(\pi\)): \[\begin{align} \pi = 2 \cdot \max\left(\int_{\gamma = -\infty}^{0} p(\gamma)\mathrm{d}\gamma, \int_{\gamma = 0}^{\infty} p(\gamma)\mathrm{d}\gamma\right) - 1 \end{align}\] with \(\pi = 1\) for genes with strong differential usage, and \(\pi = 0\) for genes with negligible differential gene usage. Both metrics are computed based on the posterior distribution of \(\gamma\), and are thus related.
IgGeneUsage has a couple of built-in Ig gene usage datasets. Some were obtained from studies and others were simulated.
Lets look into the simulated dataset d_zibb_3
. This dataset was generated
by a zero-inflated beta-binomial (ZIBB) model, and IgGeneUsage
was designed to fit ZIBB-distributed data.
data("d_zibb_3", package = "IgGeneUsage")
knitr::kable(head(d_zibb_3))
individual_id | gene_name | gene_usage_count | condition |
---|---|---|---|
I_1 | G_1 | 29 | C_1 |
I_1 | G_2 | 135 | C_1 |
I_1 | G_3 | 6 | C_1 |
I_1 | G_4 | 52 | C_1 |
I_1 | G_5 | 68 | C_1 |
I_1 | G_6 | 41 | C_1 |
We can also visualize d_zibb_3
with ggplot:
ggplot(data = d_zibb_3)+
geom_point(aes(x = gene_name, y = gene_usage_count, col = condition),
position = position_dodge(width = .7), shape = 21)+
theme_bw(base_size = 11)+
ylab(label = "Gene usage [count]")+
xlab(label = '')+
theme(legend.position = "top")+
theme(axis.text.x = element_text(angle = 90, hjust = 1, vjust = 0.4))
As main input IgGeneUsage uses a data.frame formatted as e.g.
d_zibb_3
. Other input parameters allow you to configure specific settings
of the rstan sampler.
In this example, we analyze d_zibb_3
with 3 MCMC chains, 1500 iterations
each including 500 warm-ups using a single CPU core (Hint: for parallel
chain execution set parameter mcmc_cores
= 3). We report for each model
parameter its mean and 95% highest density interval (HDIs).
Important remark: you should run DGU analyses using default IgGeneUsage parameters. If warnings or errors are reported with regard to the MCMC sampling, please consult the Stan manual1 https://mc-stan.org/misc/warnings.html and adjust the inputs accordingly. If the warnings persist, please submit an issue with a reproducible script at the Bioconductor support site or on Github2 https://github.com/snaketron/IgGeneUsage/issues.
M <- DGU(ud = d_zibb_3, # input data
mcmc_warmup = 300, # how many MCMC warm-ups per chain (default: 500)
mcmc_steps = 1500, # how many MCMC steps per chain (default: 1,500)
mcmc_chains = 3, # how many MCMC chain to run (default: 4)
mcmc_cores = 1, # how many PC cores to use? (e.g. parallel chains)
hdi_lvl = 0.95, # highest density interval level (de fault: 0.95)
adapt_delta = 0.8, # MCMC target acceptance rate (default: 0.95)
max_treedepth = 10) # tree depth evaluated at each step (default: 12)
FALSE
FALSE SAMPLING FOR MODEL 'dgu' NOW (CHAIN 1).
FALSE Chain 1:
FALSE Chain 1: Gradient evaluation took 0.000172 seconds
FALSE Chain 1: 1000 transitions using 10 leapfrog steps per transition would take 1.72 seconds.
FALSE Chain 1: Adjust your expectations accordingly!
FALSE Chain 1:
FALSE Chain 1:
FALSE Chain 1: Iteration: 1 / 1500 [ 0%] (Warmup)
FALSE Chain 1: Iteration: 50 / 1500 [ 3%] (Warmup)
FALSE Chain 1: Iteration: 100 / 1500 [ 6%] (Warmup)
FALSE Chain 1: Iteration: 150 / 1500 [ 10%] (Warmup)
FALSE Chain 1: Iteration: 200 / 1500 [ 13%] (Warmup)
FALSE Chain 1: Iteration: 250 / 1500 [ 16%] (Warmup)
FALSE Chain 1: Iteration: 300 / 1500 [ 20%] (Warmup)
FALSE Chain 1: Iteration: 301 / 1500 [ 20%] (Sampling)
FALSE Chain 1: Iteration: 350 / 1500 [ 23%] (Sampling)
FALSE Chain 1: Iteration: 400 / 1500 [ 26%] (Sampling)
FALSE Chain 1: Iteration: 450 / 1500 [ 30%] (Sampling)
FALSE Chain 1: Iteration: 500 / 1500 [ 33%] (Sampling)
FALSE Chain 1: Iteration: 550 / 1500 [ 36%] (Sampling)
FALSE Chain 1: Iteration: 600 / 1500 [ 40%] (Sampling)
FALSE Chain 1: Iteration: 650 / 1500 [ 43%] (Sampling)
FALSE Chain 1: Iteration: 700 / 1500 [ 46%] (Sampling)
FALSE Chain 1: Iteration: 750 / 1500 [ 50%] (Sampling)
FALSE Chain 1: Iteration: 800 / 1500 [ 53%] (Sampling)
FALSE Chain 1: Iteration: 850 / 1500 [ 56%] (Sampling)
FALSE Chain 1: Iteration: 900 / 1500 [ 60%] (Sampling)
FALSE Chain 1: Iteration: 950 / 1500 [ 63%] (Sampling)
FALSE Chain 1: Iteration: 1000 / 1500 [ 66%] (Sampling)
FALSE Chain 1: Iteration: 1050 / 1500 [ 70%] (Sampling)
FALSE Chain 1: Iteration: 1100 / 1500 [ 73%] (Sampling)
FALSE Chain 1: Iteration: 1150 / 1500 [ 76%] (Sampling)
FALSE Chain 1: Iteration: 1200 / 1500 [ 80%] (Sampling)
FALSE Chain 1: Iteration: 1250 / 1500 [ 83%] (Sampling)
FALSE Chain 1: Iteration: 1300 / 1500 [ 86%] (Sampling)
FALSE Chain 1: Iteration: 1350 / 1500 [ 90%] (Sampling)
FALSE Chain 1: Iteration: 1400 / 1500 [ 93%] (Sampling)
FALSE Chain 1: Iteration: 1450 / 1500 [ 96%] (Sampling)
FALSE Chain 1: Iteration: 1500 / 1500 [100%] (Sampling)
FALSE Chain 1:
FALSE Chain 1: Elapsed Time: 2.49 seconds (Warm-up)
FALSE Chain 1: 8.256 seconds (Sampling)
FALSE Chain 1: 10.746 seconds (Total)
FALSE Chain 1:
FALSE
FALSE SAMPLING FOR MODEL 'dgu' NOW (CHAIN 2).
FALSE Chain 2:
FALSE Chain 2: Gradient evaluation took 0.00014 seconds
FALSE Chain 2: 1000 transitions using 10 leapfrog steps per transition would take 1.4 seconds.
FALSE Chain 2: Adjust your expectations accordingly!
FALSE Chain 2:
FALSE Chain 2:
FALSE Chain 2: Iteration: 1 / 1500 [ 0%] (Warmup)
FALSE Chain 2: Iteration: 50 / 1500 [ 3%] (Warmup)
FALSE Chain 2: Iteration: 100 / 1500 [ 6%] (Warmup)
FALSE Chain 2: Iteration: 150 / 1500 [ 10%] (Warmup)
FALSE Chain 2: Iteration: 200 / 1500 [ 13%] (Warmup)
FALSE Chain 2: Iteration: 250 / 1500 [ 16%] (Warmup)
FALSE Chain 2: Iteration: 300 / 1500 [ 20%] (Warmup)
FALSE Chain 2: Iteration: 301 / 1500 [ 20%] (Sampling)
FALSE Chain 2: Iteration: 350 / 1500 [ 23%] (Sampling)
FALSE Chain 2: Iteration: 400 / 1500 [ 26%] (Sampling)
FALSE Chain 2: Iteration: 450 / 1500 [ 30%] (Sampling)
FALSE Chain 2: Iteration: 500 / 1500 [ 33%] (Sampling)
FALSE Chain 2: Iteration: 550 / 1500 [ 36%] (Sampling)
FALSE Chain 2: Iteration: 600 / 1500 [ 40%] (Sampling)
FALSE Chain 2: Iteration: 650 / 1500 [ 43%] (Sampling)
FALSE Chain 2: Iteration: 700 / 1500 [ 46%] (Sampling)
FALSE Chain 2: Iteration: 750 / 1500 [ 50%] (Sampling)
FALSE Chain 2: Iteration: 800 / 1500 [ 53%] (Sampling)
FALSE Chain 2: Iteration: 850 / 1500 [ 56%] (Sampling)
FALSE Chain 2: Iteration: 900 / 1500 [ 60%] (Sampling)
FALSE Chain 2: Iteration: 950 / 1500 [ 63%] (Sampling)
FALSE Chain 2: Iteration: 1000 / 1500 [ 66%] (Sampling)
FALSE Chain 2: Iteration: 1050 / 1500 [ 70%] (Sampling)
FALSE Chain 2: Iteration: 1100 / 1500 [ 73%] (Sampling)
FALSE Chain 2: Iteration: 1150 / 1500 [ 76%] (Sampling)
FALSE Chain 2: Iteration: 1200 / 1500 [ 80%] (Sampling)
FALSE Chain 2: Iteration: 1250 / 1500 [ 83%] (Sampling)
FALSE Chain 2: Iteration: 1300 / 1500 [ 86%] (Sampling)
FALSE Chain 2: Iteration: 1350 / 1500 [ 90%] (Sampling)
FALSE Chain 2: Iteration: 1400 / 1500 [ 93%] (Sampling)
FALSE Chain 2: Iteration: 1450 / 1500 [ 96%] (Sampling)
FALSE Chain 2: Iteration: 1500 / 1500 [100%] (Sampling)
FALSE Chain 2:
FALSE Chain 2: Elapsed Time: 1.913 seconds (Warm-up)
FALSE Chain 2: 5.488 seconds (Sampling)
FALSE Chain 2: 7.401 seconds (Total)
FALSE Chain 2:
FALSE
FALSE SAMPLING FOR MODEL 'dgu' NOW (CHAIN 3).
FALSE Chain 3:
FALSE Chain 3: Gradient evaluation took 0.000147 seconds
FALSE Chain 3: 1000 transitions using 10 leapfrog steps per transition would take 1.47 seconds.
FALSE Chain 3: Adjust your expectations accordingly!
FALSE Chain 3:
FALSE Chain 3:
FALSE Chain 3: Iteration: 1 / 1500 [ 0%] (Warmup)
FALSE Chain 3: Iteration: 50 / 1500 [ 3%] (Warmup)
FALSE Chain 3: Iteration: 100 / 1500 [ 6%] (Warmup)
FALSE Chain 3: Iteration: 150 / 1500 [ 10%] (Warmup)
FALSE Chain 3: Iteration: 200 / 1500 [ 13%] (Warmup)
FALSE Chain 3: Iteration: 250 / 1500 [ 16%] (Warmup)
FALSE Chain 3: Iteration: 300 / 1500 [ 20%] (Warmup)
FALSE Chain 3: Iteration: 301 / 1500 [ 20%] (Sampling)
FALSE Chain 3: Iteration: 350 / 1500 [ 23%] (Sampling)
FALSE Chain 3: Iteration: 400 / 1500 [ 26%] (Sampling)
FALSE Chain 3: Iteration: 450 / 1500 [ 30%] (Sampling)
FALSE Chain 3: Iteration: 500 / 1500 [ 33%] (Sampling)
FALSE Chain 3: Iteration: 550 / 1500 [ 36%] (Sampling)
FALSE Chain 3: Iteration: 600 / 1500 [ 40%] (Sampling)
FALSE Chain 3: Iteration: 650 / 1500 [ 43%] (Sampling)
FALSE Chain 3: Iteration: 700 / 1500 [ 46%] (Sampling)
FALSE Chain 3: Iteration: 750 / 1500 [ 50%] (Sampling)
FALSE Chain 3: Iteration: 800 / 1500 [ 53%] (Sampling)
FALSE Chain 3: Iteration: 850 / 1500 [ 56%] (Sampling)
FALSE Chain 3: Iteration: 900 / 1500 [ 60%] (Sampling)
FALSE Chain 3: Iteration: 950 / 1500 [ 63%] (Sampling)
FALSE Chain 3: Iteration: 1000 / 1500 [ 66%] (Sampling)
FALSE Chain 3: Iteration: 1050 / 1500 [ 70%] (Sampling)
FALSE Chain 3: Iteration: 1100 / 1500 [ 73%] (Sampling)
FALSE Chain 3: Iteration: 1150 / 1500 [ 76%] (Sampling)
FALSE Chain 3: Iteration: 1200 / 1500 [ 80%] (Sampling)
FALSE Chain 3: Iteration: 1250 / 1500 [ 83%] (Sampling)
FALSE Chain 3: Iteration: 1300 / 1500 [ 86%] (Sampling)
FALSE Chain 3: Iteration: 1350 / 1500 [ 90%] (Sampling)
FALSE Chain 3: Iteration: 1400 / 1500 [ 93%] (Sampling)
FALSE Chain 3: Iteration: 1450 / 1500 [ 96%] (Sampling)
FALSE Chain 3: Iteration: 1500 / 1500 [100%] (Sampling)
FALSE Chain 3:
FALSE Chain 3: Elapsed Time: 2.13 seconds (Warm-up)
FALSE Chain 3: 10.511 seconds (Sampling)
FALSE Chain 3: 12.641 seconds (Total)
FALSE Chain 3:
In the output of DGU, we provide the following objects:
dgu
and dgu_prob
(main results of IgGeneUsage):
quantitative DGU summary on a log- and probability-scale, respectively.gu
: condition-specific relative gene usage (GU) of each genetheta
: probabilities of gene usage in each sampleppc
: posterior predictive checks data (see section ‘Model checking’)ud
: processed Ig gene usage datafit
: rstan (‘stanfit’) object of the fitted model \(\rightarrow\) used
for model checks (see section ‘Model checking’)summary(M)
FALSE Length Class Mode
FALSE dgu 9 data.frame list
FALSE dgu_prob 9 data.frame list
FALSE gu 8 data.frame list
FALSE theta 12 data.frame list
FALSE ppc 2 -none- list
FALSE ud 24 -none- list
FALSE fit 1 stanfit S4
Check your model fit. For this, you can use the object glm.
rstan::check_hmc_diagnostics(M$fit)
FALSE
FALSE Divergences:
FALSE
FALSE Tree depth:
FALSE
FALSE Energy:
rstan::stan_rhat(object = M$fit)|rstan::stan_ess(object = M$fit)
The model used by IgGeneUsage is generative, i.e. with the model we can generate usage of each Ig gene in a given repertoire (y-axis). Error bars show 95% HDI of mean posterior prediction. The predictions can be compared with the observed data (x-axis). For points near the diagonal \(\rightarrow\) accurate prediction.
ggplot(data = M$ppc$ppc_rep)+
facet_wrap(facets = ~individual_id, ncol = 5)+
geom_abline(intercept = 0, slope = 1, linetype = "dashed", col = "darkgray")+
geom_errorbar(aes(x = observed_count, y = ppc_mean_count,
ymin = ppc_L_count, ymax = ppc_H_count), col = "darkgray")+
geom_point(aes(x = observed_count, y = ppc_mean_count), size = 1)+
theme_bw(base_size = 11)+
theme(legend.position = "top")+
xlab(label = "Observed usage [counts]")+
ylab(label = "PPC usage [counts]")
Prediction of generalized gene usage within a biological condition is also possible. We show the predictions (y-axis) of the model, and compare them against the observed mean usage (x-axis). If the points are near the diagonal \(\rightarrow\) accurate prediction. Errors are 95% HDIs of the mean.
ggplot(data = M$ppc$ppc_condition)+
geom_errorbar(aes(x = gene_name, ymin = ppc_L_prop*100,
ymax = ppc_H_prop*100, col = condition),
position = position_dodge(width = 0.65), width = 0.1)+
geom_point(aes(x = gene_name, y = ppc_mean_prop*100,col = condition),
position = position_dodge(width = 0.65))+
theme_bw(base_size = 11)+
theme(legend.position = "top")+
xlab(label = "Observed usage [%]")+
ylab(label = "PPC usage [%]")+
theme(axis.text.x = element_text(angle = 90, hjust = 1, vjust = 0.4))
Each row of glm
summarizes the degree of DGU observed for specific
Igs. Two metrics are reported:
es
(also referred to as \(\gamma\)): effect size on DGU, where contrast
gives the direction of the effect (e.g. tumor - healthy or healthy - tumor)pmax
(also referred to as \(\pi\)): probability of DGU (parameter \(\pi\)
from model \(M\))For es
we also have the mean, median standard error (se), standard
deviation (sd), L (low bound of 95% HDI), H (high bound of 95% HDI)
kable(x = head(M$dgu), row.names = FALSE, digits = 2)
es_mean | es_mean_se | es_sd | es_median | es_L | es_H | contrast | gene_name | pmax |
---|---|---|---|---|---|---|---|---|
0.18 | 0.01 | 0.29 | 0.12 | -0.24 | 0.92 | C_1-vs-C_2 | G_1 | 0.47 |
-0.01 | 0.00 | 0.21 | -0.01 | -0.45 | 0.40 | C_1-vs-C_2 | G_4 | 0.04 |
-0.08 | 0.00 | 0.22 | -0.06 | -0.58 | 0.31 | C_1-vs-C_2 | G_3 | 0.28 |
-0.06 | 0.00 | 0.18 | -0.04 | -0.45 | 0.27 | C_1-vs-C_2 | G_2 | 0.25 |
0.06 | 0.00 | 0.18 | 0.04 | -0.28 | 0.46 | C_1-vs-C_2 | G_5 | 0.25 |
-0.02 | 0.00 | 0.19 | -0.02 | -0.45 | 0.36 | C_1-vs-C_2 | G_8 | 0.09 |
We know that the values of \gamma
and \pi
are related to each other.
Lets visualize them for all genes (shown as a point). Names are shown for
genes associated with \(\pi \geq 0.95\). Dashed horizontal line represents
null-effect (\(\gamma = 0\)).
Notice that the gene with \(\pi \approx 1\) also has an effect size whose 95% HDI (error bar) does not overlap the null-effect. The genes with high degree of differential usage are easy to detect with this figure.
# format data
stats <- M$dgu
stats <- stats[order(abs(stats$es_mean), decreasing = FALSE), ]
stats$gene_fac <- factor(x = stats$gene_name, levels = unique(stats$gene_name))
ggplot(data = stats)+
geom_hline(yintercept = 0, linetype = "dashed", col = "gray")+
geom_errorbar(aes(x = pmax, y = es_mean, ymin = es_L, ymax = es_H),
col = "darkgray")+
geom_point(aes(x = pmax, y = es_mean, col = contrast))+
geom_text_repel(data = stats[stats$pmax >= 0.95, ],
aes(x = pmax, y = es_mean, label = gene_fac),
min.segment.length = 0, size = 2.75)+
theme_bw(base_size = 11)+
theme(legend.position = "top")+
xlab(label = expression(pi))+
xlim(c(0, 1))+
ylab(expression(gamma))
Lets visualize the observed data of the genes with high probability of differential gene usage (\(\pi \geq 0.95\)). Here we show the gene usage in %.
promising_genes <- stats$gene_name[stats$pmax >= 0.95]
ppc_gene <- M$ppc$ppc_condition
ppc_gene <- ppc_gene[ppc_gene$gene_name %in% promising_genes, ]
ppc_rep <- M$ppc$ppc_rep
ppc_rep <- ppc_rep[ppc_rep$gene_name %in% promising_genes, ]
ggplot()+
geom_point(data = ppc_rep,
aes(x = gene_name, y = observed_prop*100, col = condition),
size = 1, fill = "black",
position = position_jitterdodge(jitter.width = 0.1,
jitter.height = 0,
dodge.width = 0.35))+
geom_errorbar(data = ppc_gene,
aes(x = gene_name, ymin = ppc_L_prop*100,
ymax = ppc_H_prop*100, group = condition),
position = position_dodge(width = 0.35), width = 0.15)+
theme_bw(base_size = 11)+
theme(legend.position = "top")+
theme(axis.text.x = element_text(angle = 90, hjust = 1, vjust = 0.4))+
ylab(label = "PPC usage [%]")+
xlab(label = '')
Lets also visualize the predicted gene usage counts in each repertoire.
ggplot()+
geom_point(data = ppc_rep,
aes(x = gene_name, y = observed_count, col = condition),
size = 1, fill = "black",
position = position_jitterdodge(jitter.width = 0.1,
jitter.height = 0,
dodge.width = 0.5))+
theme_bw(base_size = 11)+
theme(legend.position = "top")+
ylab(label = "PPC usage [count]")+
xlab(label = '')+
theme(axis.text.x = element_text(angle = 90, hjust = 1, vjust = 0.4))
IgGeneUsage also reports the inferred gene usage (GU)
probability of individual genes in each condition. For a given gene we
report its mean GU (prob_mean
) and the 95% (for instance) HDI (prob_L
and prob_H
).
ggplot(data = M$gu)+
geom_errorbar(aes(x = gene_name, y = prob_mean, ymin = prob_L,
ymax = prob_H, col = condition),
width = 0.1, position = position_dodge(width = 0.4))+
geom_point(aes(x = gene_name, y = prob_mean, col = condition), size = 1,
position = position_dodge(width = 0.4))+
theme_bw(base_size = 11)+
theme(legend.position = "top")+
ylab(label = "GU [probability]")+
theme(axis.text.x = element_text(angle = 90, hjust = 1, vjust = 0.4))