The IgAScores Package

Matthew Jackson

2020-08-26

The IgAScores package provides functions to calculate IgA binding indices from IgA-Seq data sets.

In IgA-Seq, bacteria within a sample are stained with an anti-IgA antibody and sorted into bound (IgA+) and unbound (IgA-) fractions. The taxonomy of these bacteria is then profiled using 16S rRNA gene sequencing of DNA amplified from the sorted fractions. The functions in this package generate scores of relative binding per taxon per sample from the resulting data.

We recommend using the Probability Ratio to score IgA binding but make other scoring approaches available for comparison. See the IgAScores paper for a detailed consideration of IgA scoring methods.

Input data

The different scoring approaches require different inputs these can include:

Example data

Here we generate some dummy data to demonstrate the IgAScores functions.

Calculating scores for all taxa and samples in an experiment

To calculate IgA scores across all of the taxa and samples in an experiment the igascores() function should be used. This enables calculation of all the different scores via the method argument, the requirements for each of the scores is shown below.

Score Method name Inputs required
Probability Ratio probratio IgA+ abundance, IgA- abundance, IgA+ size, IgA- size, pseudo
IgA+ Probability prob IgA+ abundance, Presort abundance, IgA+ size
Palm index palm IgA+ abundance, IgA- abundance, pseudo
Kau index kau IgA+ abundance, IgA- abundance, pseudo

For example, calculating the Probability Ratio on the example data:

#default method is probratio
prscores <- igascores(posabunds = igapos, negabunds = iganeg, 
                      possizes = possize, negsizes = negsize, 
                      pseudo = pseudo)

print(prscores)
#>           Sample1     Sample2    Sample3
#> Taxon1 -0.3505492 -0.02065829 -0.1340168
#> Taxon2         NA -0.65261507 -0.1903192
#> Taxon3 -0.5954181 -0.65482619  0.1272275
#> Taxon4 -0.4632094  0.06382045 -0.7238482
#> Taxon5 -0.1019485 -0.03272343 -0.5154269

Note the NA in Sample 1’s estimate for Taxon 2. This is because the taxa was not observed in either of the IgA+ or IgA- fractions. Adding a pseudo count to both would create an artificial estimate that might actually be higher than real observed values, thus IgAScores won’t score values absent in both fractions. This behavior can be controlled using the nazeros parameter, but it is recommended to leave this as default. Similarly, the Probability Ratio has a scaleratio parameter, this scales the values between -1 and 1 by adjusting for the size of the pseudo count, again it is recommended to leave this on by default.

An example for the IgA+ Probability

ppscores <- igascores(posabunds = igapos, possizes = possize, presortabunds = presort, method="prob")

print(ppscores)
#>            Sample1    Sample2      Sample3
#> Taxon1 0.057817109 0.07100939 0.1215962441
#> Taxon2 0.000000000 0.00000000 0.0781690141
#> Taxon3 0.001734513 0.00617473 0.0260563380
#> Taxon4 0.005781711 0.13556338 0.0007816901
#> Taxon5 0.173451327 0.32276995 0.0000000000

The IgA+ Probability is a direct estimate of the probability a bacteria will be bound to IgA and in the IgA+ fraction given that it belongs to the given taxon. Note that the opposite (the IgA- Probability) can be calculated by swapping out the IgA+ abundance and IgA+ size for the IgA- abundance and IgA- size.

Examples for the Kau and Palm indices:

kscores <- igascores(posabunds = igapos, negabunds = iganeg, pseudo=pseudo, method="kau")
print(kscores)
#>           Sample1    Sample2    Sample3
#> Taxon1  0.3905989  0.6120783  0.6321241
#> Taxon2         NA -0.6144172  0.2823114
#> Taxon3 -0.4214603 -0.7851551  0.3891377
#> Taxon4 -0.2157185  0.4519001 -0.8066183
#> Taxon5  0.2618282  0.4054535 -0.5074027

pscores <-  igascores(posabunds = igapos, negabunds = iganeg, pseudo=pseudo, method="palm")
print(pscores)
#>           Sample1     Sample2     Sample3
#> Taxon1 1.16814159  8.10798122  4.22848200
#> Taxon2         NA  0.00000000  2.71830986
#> Taxon3 0.05840708  0.07370892 46.94835681
#> Taxon4 0.23362832 15.47887324  0.02210008
#> Taxon5 5.84070796  7.37089202  0.00000000

These methods implement the scores described by Kau et al. and Palm et al. respectively.

Calculating scores for a single taxon from a single sample

For most experimental purposes the igascores() function will be more useful, and allows calculation of scores for all taxa across all samples in an experiment. But if a single taxon and sample are to be scored, such as for custom wrapping of the functions in other scripts, individual functions are available for the four methods:

igaprobabilityratio(posabund = igapos[1,1], negabund = iganeg[1,1], possize = possize[1], negsize = negsize[1], pseudo = pseudo)
#>    Sample1 
#> -0.3505492
igaprobability(withinabund = igapos[1,1], presortabund = presort[1,1], gatesize = possize[1])
#>    Sample1 
#> 0.05781711
kauindex(posabund = igapos[1,1], negabund = iganeg[1,1], pseudo = pseudo)
#> [1] 0.3905989
palmindex(posabund = igapos[1,1], negabund = iganeg[1,1], pseudo = pseudo)
#> [1] 1.168142

Simulating IgA-Seq data

Simulated IgA-Seq data is used to validate scoring approaches in the IgAScores paper. This can be replicated using the simulateigaseq() function. This has several parameters for customising the simulation, which are detailed in the functions documentation. The basic data returned by the simulation are shown below, these can then be used to calculate indices using the functions above.

#run the simulation with defaults
simdata <- simulateigaseq()

summary(simdata)
#>               Length Class      Mode   
#> presortcounts 100    -none-     numeric
#> presortabunds  10    data.frame list   
#> poscounts      10    data.frame list   
#> posabunds      10    data.frame list   
#> negcounts      10    data.frame list   
#> negabunds      10    data.frame list   
#> possizes       10    -none-     numeric
#> negsizes       10    -none-     numeric
#> igabinding      3    data.frame list   
#> igavalmeans    10    -none-     numeric
#> igavalsds      10    -none-     numeric
#> posthresh       1    -none-     numeric
#> negthresh       1    -none-     numeric
#> expgroup       10    -none-     numeric
#> expspecies      0    -none-     NULL

Additional examples

Full analysis scripts demonstrating the use of IgAScores and how to compare IgA binding scores between different experimental conditions can be found in the GitHub repository containing the analyses from the paper.