BATMAN workflow

Contents

1. Background
2. Tutorial
   • Step 1: Register and login
   • Step 2: Create new workflow
   • Step 3: Select BATMAN tool
   • Step 4: Upload data
   • Step 5: Modify and run BATMAN workflow
   • Step 6: Export results
3. VIDEO tutorial
4. Information about BATMAN files

1. Background

Bayesian AuTtomated Metabolite ANalyzer (BATMAN) for NMR is a protocol for automated metabolite deconvolution and quantification from complex NMR spectra. BATMAN deconvolves resonances from 1-dimensional NMR spectra and assigns them to specific metabolites from a target list and obtains concentration estimates. It applies a Markov Chain Monte Carlo (MCMC) algorithm to sample from a joint posterior distribution of the model parameters and obtains concentration estimates with reduced error compared with conventional numerical integration and comparable to manual deconvolution by experienced spectroscopists. BATMAN is available for PhenoMeNal galaxy users.

The following publications provide detailed information of several aspects of BATMAN tool:

Hao, J., Astle, W., De Iorio, M., & Ebbels, T. M. (2012). BATMAN—an R package for the automated quantification of metabolites from nuclear magnetic resonance spectra using a Bayesian model. Bioinformatics, 28(15), 2088-2090. [Link]

Hao, J., Liebeke, M., Astle, W., De Iorio, M., Bundy, J. G., & Ebbels, T. M. (2014). Bayesian deconvolution and quantification of metabolites in complex 1D NMR spectra using BATMAN. Nature protocols, 9(6), 1416. [Link]

2. Tutorial

The purpose of this tutorial is to show you how to use and run BATMAN for your own analyses.

The workflow has been created for the PhenoMeNal and it is available at our public instance and on deployed PhenoMeNal Cloud Research Environments (CRE).

More detailed, in this tutorial will be demonstrated how to:

• login
• create a workflow
• import the necessary files for BATMAN modification
• download results
• visualize results.

Also before you run this tutorial following the instructions of the session 'STEPS', download following files:

• NMRdata.txt
• batmanoptions.txt
• multi_data_user.csv
• metabolitesList.csv

The files are available to this link.

STEPS

Step 1: Register or login

• On the welcome page of Galaxy, on the top main menu, you will find the item "Login".

Please make sure you are logged in before proceeding to step two. Without logging into your account, you will neither be able to duplicate the following steps of this tutorial nor to import the following workflow and run it. To get an account on the PhenoMeNal public instance please check this link.

Figure 1. Login to "PhenoMeNal galaxy"

Step 2: Create new workflow

• In the top main menu, select the menu item "Workflow".
• Create an new workflow pressing the "plus" symbol.
• Add name and annotation to the workflow filling the fields and press "Create".

Now, the "WorkFlow Canvas" has been displayed in the middle panel of the page.

Figure 2. Create a new workflow

Step 3: Select BATMAN tool

• On the left side menu, in "Tools", find the tool category "NMR DATA ANALYSIS TOOLS" and press "NMR".
• Press to "BATMAN" and the BATMAN tool will appear in the "Workflow Canvas".
• Press the cogwheel symbol, in the right top corner of the "WorkFlow Canvas".
• Press save.
• Press close.

Figure 3. View of interface after BATMAN tool has been imported to the workflow.

Step 4: Upload data

Before you start applying step 4, make sure that you have already downloaded the necessary files for running BATMAN. The demo files for this tutorial are available to this link.

• In the left side menu, in "Tools", press "Get Data".
• Press "Upload File".
• To the pop-up window, "Download from web or upload from disk", select the tab "Regular".
• Press "Choose local file".
• Find the directory that contains the 4 downloaded demo files.
• Select the demo files.
• Press "open".

The 4 files will be appear in the rectangular of the pop up window.

• Press "Start" on the bottom of the window

Figure 4. Import your experimental data and BATMAN modification files.

Step 5: Modify and run BATMAN workflow

• At top main menu, select the menu item "Workflow".
• Find the workflow that you have created on step 2 and press on it.
• Press run.

In the middle of the page, it will be available the workflow steps of the created workflow.

The 4 white fields must be filled to run the workflow.

• Press on the white fields and select the right file.
• Press the "pencil button" at the end of the workflow and fill the numbers of the CPUs**.
• Press the button "Run workflow" in the top menu.

** By default is one. Before you run the workflow, please be sure about the maximum number of CPUs that you can use.

Figure 5. Workflow task menu.

Figure 6. Workflow has been successfully submitted and the tasks are in the queue in the history menu (right menu).

On the right side menu, in 'History', you can see the progress of the workflow. Please note, depending on the queue, sometimes it takes several minutes before the history is visible. It is worth mentioning that BATMAN is a Bayesian deconvolution method has high computational needs. When the tasks in the history queue will be all colored in green means that the analysis will have been finished and successfully completed.

Step 6: Export results

• In right side menu, in "History", click on tags of green tabs.
• Press download icon.
• To the pop up window, give a name for the exported file.
• Press save.

If all went well you should see something that looks like the screenshot below. Galaxy will automatically try to map the available data from the history on the right to the required input parameters by the workflow tools.

Figure 7. BATMAN Workflow results.

Comment

Important! If we want to run a BATMAN workflow for our data, we have to modified the input files using suitable parameters. The provided files has been modified for this tutorial and they cannot be used as default setup files for other analysis.

VIDEO tutorial

The presented BATMAN tutorial can be viewed in action by watching the following video tutorial:

Information about BATMAN files

It is suggested that the parameters of BATMAN files be setup by experts.

The structure of the provided files by this tutorial can be used as templates.

• NMRdata.txt: This file contains information regarding the ppm value and real part of the NMR spectrum.

• batmanoptions.txt: This file contains the necessary parameters for BATMAN function (e.g. ppm range, truncation threshold for negative intensities, intensity scale factor, number of burn-in iterations, thinning factor for MCMC state, etc).

• multi_data_user.csv: The user can modify the parameters in the template file and specify ppm positions, and normal distribution truncation of ppm shift parameters. More detailed, this file contains information related to the ppm position of the center of the multiplets, the J constant that contains the offsets in Hz for peaks of a mutiplet positioned at "pos_in_ppm", the relative intensity that corresponds to the number of protons in each multiple etc.

• metabolitesList.csv: This file contains the metabolite names that are fitted to analysis.

BATMAN modification files are extensively described to [this link ]

Additional material

See webinar by Tim Ebbels on Metabolomics in the cloud: scaling computational tools to big data