BugBase Usage and Installation
Standard users can analyze their microbiome samples with the default phenotypes, as well as the KEGG pathways.
BugBase relies on R packages. When you are ready to try BugBase, the following R packages will be looked for on your computer, and installed for you if they are missing.
You can download BugBase here, and then add the paths to BugBase and the BugBase bin to your
~/.bash_profile file. This is what is in an example
~/.bash_profile modification looks like:
export BUGBASE_PATH=/Path/to/my/BugBase export PATH=$PATH:$BUGBASE_PATH/bin
Note: you will need change the paths to match your system and which directory you have downloaded BugBase into. You might need to put it in ~/.bashrc instead of ~/.bash_profile depending on your system. After adding these paths to the .bash_profile or ~/.bashrc, reopen the terminal or login again.
To check your install, type the following in the command line. It will first install any missing packages, and then it will print the options available to run BugBase.
BugBase comes with a test dataset in the bugbase/doc/data directory. To analyze this data set you would type the following:
run.bugbase.r -i $BUGBASE_PATH/doc/data/HMP_s15.txt -m $BUGBASE_PATH/doc/data/HMP_map.txt -c HMPBODYSUBSITE -o output
You can view other options with
BugBase has one main command,
run.bugbase.r, that will:
- Normalize your OTU table according to 16S copy number (WGS data will not be normalized)
- Plot the variance in phenotype possession for thresholds 0-1
- Determine which threshold to set for each microbiome phenotype
- Determine the proportion of each microbiome with a given phenotype
- Plot the proportions of the microbiome with a given phenotype
- Statistically analyze the microbiome phenotype proportions according the treatment groups specified, or by using regression for continuous data
- Plot OTU contributions for each phenotype
Required -i Input OTU table, picked against the Greengenes database (16S) or IMG (Shotgun) (.txt or .biom (json)) -o Output directory name Optional -m Mapping file (tab-delimited text file) -c Map column header to plot by (which column denotes treatment groups) -w Data is shotgun metagenomic data (picked against IMG database) -a Plot all samples (no stats will be run) -x Output prediction files only, no plots will be made -g Specify subset of groups in map column to plot (list, comma separated) -z Data is of type continuous -C Use coefficient of variance instead of variance to determine thresholds -l Centered log-ratio transform the data instead of using relative abundance -t Taxa level to plot OTU contributions by (number 1-7) -T Specify a threshold to use for all traits (number 0-1) -k Use the KEGG modules instead of default traits (Note: you must specify which modules!) -p List modules or traits to predict (comma separated list, no spaces) -u Use a user-define trait table. Absolute file path must be specified
BugBase compatible OTU tables
BugBase takes in QIIME compatible OTU tables in the classic (.txt) or json version (.biom). Below are some instructions regarding OTU table generation for downstream BugBase use.
- Closed reference OTU picking with the Greengenes 97% representative set
- Do not include taxonomy if in the classic form (.txt)
- Counts, not relative abundance
- You can use OTU tables generated from many programs, such as NINJA-OPS. or QIIME
- Closed reference OTU picking with the IMG reference sequences
To generate a BugBase compatible OTU table from shotgun data, please follow the steps below:
Download the UTree release specific to your operating system by downloading and unzipping version 0.0.1 of UTree here.
Install miniconda, if you don't already have it. Miniconda can be found here.
Download and unzip directory for the SHOGUN-BugBase database (IMG reference sequences and maps) needed for OTU picking here.
Finish installing SHOGUN for BugBase with the following commands:
# create a shogun conda environment conda create -n shogun python=3 # activate the shogun environment source activate shogun # install shogun for BugBase pip install git+https://github.com/knights-lab/SHOGUN.email@example.com --no-cache-dir --upgrade pip install git+https://github.com/knights-lab/NINJA-utils pip install git+https://github.com/knights-lab/NINJA-dojo # deactivate the environment source deactivate
- Run OTU picking with the following commands. Update the
shogun_bugbasecommand to be specific to the filepaths for your input sequences and the SHOGUN-BugBase database you downloaded. Your input sequences should be in one directory, with one .fna file per sample. The name of each .fna file should be the name of the sample it corresponds to. Once OTU picking is complete, you will have an OTU table in classic format (.txt) called 'taxa_counts.txt' within the output directory specified.
# activate the shogun environment source activate shogun # run OTU picking with shogun shogun_bugbase -i path_to_sequences -o output_path -u path_to_shogun_bugbase_db # deactivate the shogun environment source deactivate
Creating user-defined trait tables for predictions
You can create your own traits of interest for BugBase predictions using KEGG orthologies. To do so, you will need the following:
- A file for each trait that consists of the KO IDs involved in the trait/pathway, one KO ID per line
- A directory that houses the trait files mentioned about (one per trait), each trait file name will be used as the trait name (exactly) in the BugBase table created
You can create your user-defined custom BugBase input table using
make.user.table.r that will:
- create intermediate files for each trait specified
- merge all intermediate tables into one table that has each trait of interest as a column
- create a final BugBase input file will be called "Custom_BugBase_Traits.txt" and it will be located in directory you specified as the input
BugBase parameters for
Required -i path to directory housing the files that list the KO IDs per trait Optional -w traits are for shotgun metagenomic sequencing, default is 16S
To create a custom BugBase input and run the BugBase predictions:
#Example: make.user.table.r -i directory_with_trait_files run.bugbase.r -i path/to/OTU_Table.biom -m path/to/map.txt -c metadata_column -u directory_with_trait_files/Custom_BugBase_Traits.txt -o output_name