1. bioBakery
  2. Untitled Project
  3. biobakery

Wiki

Clone wiki

biobakery / maaslin

MaAsLin Tutorial

MaAsLin is a multivariate statistical framework that finds associations between clinical metadata and potentially high-dimensional experimental data. MaAsLin performs boosted additive general linear models between one group of data (metadata/the predictors) and another group (in our case relative taxonomic abundances/the response).

MaAsLin is available as a Galaxy module (See Section 2 for instructions), and a bitbucket repository (See Section 3 for instructions).

For additional, please refer to the `MaAsLin paper`_(in progress).

We provide support for MaAsLin users. Please join our Google group designated specifically for MaAsLin users. Feel free to post any questions on the google group by posting directly or emailing maaslin-users@googlegroups.com.



Overview

The following figure shows the workflow for MaAsLin.

MaAsLin.png

1. MaAsLin (Galaxy module)

MaAsLin requires an input file of microbial abundance table with metadata attached (e.g.: sample input).

  • Go to the Huttenhower Galaxy server.
  • Click on the MaAsLin link on the left pane, and then on the Load data for MaAsLin link.
  • Click on the Choose File button to select the input file (microbial abundance table with metadata data attached) OR enter the URL in the URL/Text text box to upload the data. Click on the Execute button.
loadmaaslingalaxy.jpg
  • Click on the Run MaAsLin link on the left pane.
    • Select the input data from the Input file drop-down menu.
    • Specify the last metadata row in the sample, after which the microbial species are listed (this is Weight in our sample dataset).
    • Click on Execute
maaslin_run.jpg

The results will appear on the right pane. You may proceed with viewing it (by clicking on the Eye symbol) or downloading it on your computer (by clicking on the Save symbol).

2. MaAsLin (Bitbucket repository)

MaAsLin may also be downloaded as a bitbucket repository. For instructions on installation, dependencies and further details please refer to the MaAsLin documentation. This tutorial assumes the installation of MaAsLin under the Sfle environment.

Once you have obtained the microbial abundance tables through MetaPhlAn (See MetaPhlAn tutorial for details) or other tools, MaAsLin allows to determine associations between the microbial abundances and the metadata.

This requires you to attach the metadata of the samples to the microbial abundance tables resulting in a table with the format of the sample input data for an example.

2.1 Merging Metadata with Microbial abundance tables (optional)

For your support, we provide a script to do perform the function. Please follow the instructions below to attach metadata to your microbial abundance tables. If you are using a separate method to attach the metadata, you may skip to Section 3.2 to move ahead with the analysis (All that is neccessary is that the metadata needs to be on top of the microbial abundance table, in the format shown by the sample input data.

Please ensure that the format of your input files follows that of the demo files above.

  • Go to ../maaslin/ in your terminal.
  • Run the following command to create the merged file:
$ src/merge_metadata.py input/for_merge_metadata/maaslin_demo_metadata.metada < input/for_merge_metadata/maaslin_demo_measurements.pcl > input/maaslin_demo.pcl
  • The resulting file (should look like this) will be created under the /maaslin/input/ directory as specified by the above command. You may now use this file as an input for MaAsLin.

2.2 Creating a .read.config file

The .read.config file determines which rows/columns to process without modifying the input metadata-merged-microbial abundance table. A sample .read.config file for the purpose of this tutorial is shown below:

Matrix: Metadata
Read_PCL_Rows: -Weight

Matrix: Abundance
Read_PCL_Rows: Bacteria-

The text above dictates that the Metadata matrix ends when the row starts with Weight, while the Abundance matrix starts when the word Bacteria appears in the row. For more examples, please refer to the MaAsLin documentation.

2.3 Running MaAsLin

Once you have the metadata-merged-microbial abundance table, and the .read.config file (see the samples to ensure the format), you are ready to run MaAsLin.

  • Place the .read.config file (e.g. maaslin_demo2.read.config), and the metadata-merged-microbial abundance table (e.g. maaslin_demo2.pcl) under /maaslin/input
  • Go to ../sfle, (the maaslin directory should be placed as /sfle/input/maaslin/).
  • Run the following command:

$ scons output/maaslin

The above command will create a directory: /sfle/output/maaslin, which will contain the results. An example of the resulting biplot figure is shown below:

maaslin_demo2-biplot (1).jpg

Notes

For more information please refer to the MaAsLin documentation.

Updated