Package 'BRACoD.R'

Perform convergence tests on the p and beta variables

Description

You may get errors are divergence of some variables after pymc3 samples the posterior. We are not overly concerned about some of the variables, such as the variance, rather we are really interested in the inclusion probabilities (p) and contribution coefficients (beta). The convergence tests that are included here focus on evaluating those two variables.

Usage

convergence_tests(trace, df_relab)

Arguments

trace	the output of run_bracod()
df_relab	the microbiome relative abundance

Value

no return value

---

Install BRACoD in python

Description

Uses pip to install the latest BRACoD release in python. You might need to specify a python environment with either reticulate::use_virtualenv or reticulate::use_condaenv.

Usage

install_bracod(method = "auto", conda = "auto")

Arguments

method	passed to reticulate::py_install
conda	passed to reticulate::py_install

Value

no return value

---

Example microbiome data

Description

This data is mouse stool microbiome data from a study of obesity.

Usage

data(obesity)

df_scfa

Format

a DataFrame of 16S microbiome counts, and a dataframe with corresponding butyrate measurements

An object of class data.frame with 119 rows and 1 columns.

---

Remove NULL values in your OTU and environmental variable

Description

This will remove samples that are NULL in the environmental variable, as well as the corresponding samples in your relative abundance data.

Usage

remove_null(df_relab, Y)

Arguments

df_relab	microbiome relative abundance data in a dataframe
Y	values of the environmental variable

Value

a list containing 1) the relative abundance data and 2) the Y values

---

Run the main BRACoD algorithm

Description

Uses pymc3 to sample the posterior of the model to determine bacteria that are associated with your environmental variable.

Usage

run_bracod(df_relab, env_var, n_sample = 1000, n_burn = 1000, njobs = 4)

Arguments

df_relab	A dataframe of relative microbiome abundances. Samples are rows and bacteria are columns.
env_var	the environmental variable you are evaluating. You need 1 measurement associated with each sample.
n_sample	number of posterior samples.
n_burn	number of burn-in steps before actual sampling stops.
njobs	number of parallel MCMC chains to run.

Value

the pymc trace object which holds the samples of the posterior distribution

Examples

## Not run: 
data(obesity)
r <- simulate_microbiome_counts(obesity)
sim_counts <- r[[1]]
sim_y <- r[[2]]
contributions <- r[[3]]
sim_relab <- scale_counts(sim_counts)
trace <- run_bracod(sim_relab, sim_y, n_sample = 1000, n_burn=1000, njobs=4)

## End(Not run)

---

Normalize OTU counts and add a pseudo count

Description

BRACoD requires relative abundance and cannot handle zeros, so this function adds a small pseudo count (1/10th the smallest non-zero value).

Usage

scale_counts(df_counts)

Arguments

df_counts

A dataframe of OTU counts. Samples are rows and bacteria are columns.

Value

a dataframe of relative abundance data

---

Score the results of BRACoD

Description

This calculate the precision, recall and F1 of your BRACoD results if you know the ground truth, ie. if this is simulated data.

Usage

score(taxon_identified, taxon_actual)

Arguments

taxon_identified	a list of integers corresponding to the indicies of the taxon you identified with BRACoD
taxon_actual	a list of integers corresponding to the indicies of the taxon that truely contribute to butyrate levels

Value

a list containing 1) the precision 2) the recall 3) the f1 metric

Examples

## Not run: 
df_summary <- summarize_trace(trace, colnames(sim_relab))
taxon_identified <- df_summary$taxon
taxon_actual <- which(contributions != 0)

r <- score(taxon_identified, taxon_actual)

precision <- r[[1]]
recall <- r[[2]]
f1 <- r[[3]]

print(sprintf("Precision: %.2f, Recall: %.2f, F1: %.2f",precision, recall, f1))

## End(Not run)

---

Simulate microbiome counts

Description

Each bacteria's absolute abundance is simulated from a lognormal distribution. Then, convert each sample to relative abundance, and simulate sequencing counts using a multinomial distribution, based on the desired number of reads and the simulated relative abundances. This also simulates an environmental variable that is produced by some of the bacteria.

Usage

simulate_microbiome_counts(
  df,
  n_contributors = 20,
  coeff_contributor = 0,
  min_ab_contributor = -9,
  sd_Y = 1,
  n_reads = 1e+05,
  var_contributor = 5,
  use_uniform = TRUE,
  n_samples_use = NULL,
  corr_value = NULL,
  return_absolute = FALSE,
  seed = NULL
)

Arguments

df	A dataframe of OTU counts that is a model for data simulation. Samples are rows and bacteria are columns.
n_contributors	the number of bacteria that are to contribute to your environmental variable.
coeff_contributor	the average of the distribution used to simulate the contribution coefficient.
min_ab_contributor	The minimum log relative abundance, averaged across samples, to include a bacteria
sd_Y	the standard deviation of the simulated environmental variable
n_reads	the number of reads to be simulated per sample
var_contributor	If you use a uniform distribution, this is the range of the distribution, with a normal distribution it is the variance used to simulate the contribution coefficient.
use_uniform	use a uniform distribution to simulate the contribution coefficient. Alternative is the normal distribution.
n_samples_use	number of microbiome samples to simulate. If NULL, uses the same number of samples as in your dataframe
corr_value	the bacteria-bacteria correlation value you want to include in the simulation
return_absolute	returns the abosulte abundance values instead of the simulated microbiome counts
seed	random seed for reproducibility

Value

a list containing 1) the simulated count data 2) the simulated environmental variable and 3) the simulated contribution coefficients

---

Summarize the results of BRACoD

Description

This summarizes the trace object that run_bracod() returns. It returns a dataframe that contains two parameters of interest, the average inclusion (p) and the average coefficient (beta), telling you the association between that bacteria and the environmental variable

Usage

summarize_trace(trace, taxon_names = NULL, cutoff = 0.3)

Arguments

trace	the pymc3 object that is the output of run_bracod()
taxon_names	optional, a list of names of the bacteria to include in the results
cutoff	this is the cutoff on the average inclusion for inclusion. We reccomend a value of 0.3, but you can lower the value to include less confident taxon or raise the cutoff to exclude them.

Value

a dataframe with information about the bacteria that BRACoD identified

Examples

## Not run: 
trace <- run_bracod(sim_relab, sim_y, n_sample = 1000, n_burn=1000, njobs=4)
df_summary <- summarize_trace(trace, colnames(sim_relab))

## End(Not run)

---

Threshold your microbiome counts data

Description

This function removes samples below a minimum counts and bacteria below a minimum log abundance. Run this before running BRACoD because the algorithm does not perform well when there are many low abundance bacteria that are only present in a few samples.

Usage

threshold_count_data(df_counts, min_counts = 1000, min_ab = 1e-04)

Arguments

df_counts	A dataframe of OTU counts. Samples are rows and bacteria are columns.
min_counts	threshold samples with fewer than this many counts
min_ab	threshold bacteria whose average log abundance is below this

Value

a dataframe of microbiome counts

---