Dec 09, 2025
Basis Set to BATMAN Workflow
- Christopher Esselman1,
- Arthur Edison1
- 1University of Georgia
Protocol Citation: Christopher Esselman, Arthur Edison 2025. Basis Set to BATMAN Workflow. protocols.io https://dx.doi.org/10.17504/protocols.io.8epv5owmng1b/v1
License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited
Protocol status: Working
We use this protocol and it's working
Created: June 24, 2025
Last Modified: December 09, 2025
Protocol Integer ID: 220953
Keywords: BATMAN, metabolite basis set, FLAnalyzer, flanalyzer into batman input file, basis set to batman workflow, metabolite basis set, batman on nmrbox, batman input file, batman workflow, flanalyzer, nmrbox, results of batman, running batman, basis set, batman
Funders Acknowledgements:
Network for Advanced NMR/NSF
Grant ID: 1946970
NIH/NIGMS R35
Grant ID: GM145348
Disclaimer
DISCLAIMER – FOR INFORMATIONAL PURPOSES ONLY; USE AT YOUR OWN RISK
The protocol content here is for informational purposes only and does not constitute legal, medical, clinical, or safety advice, or otherwise; content added to protocols.io is not peer reviewed and may not have undergone a formal approval of any kind. Information presented in this protocol should not substitute for independent professional judgment, advice, diagnosis, or treatment. Any action you take or refrain from taking using or relying upon the information presented here is strictly at your own risk. You agree that neither the Company nor any of the authors, contributors, administrators, or anyone else associated with protocols.io, can be held responsible for your use of the information contained in or linked to this protocol or any of our Sites/Apps and Services.
Abstract
This protocol outlines the steps for exporting a metabolite basis set (mBS) created with FLAnalyzer into BATMAN input files, running BATMAN on NMRbox, and inspecting the results of BATMAN fitting.
Troubleshooting
Before start
This protocol assumes:
- You have a NMRbox account.
- You have created a basis set using FLAnalyzer.
Exporting the Basis Set from MATLAB
Open Script: Open the basis_to_batman.m script from the FLAnalyzer GitHub repository in MATLAB. The script can be found under the "workflows" section.
Generate BATMAN Input Files: Follow the directions in the comments (green text) to generate the BATMAN input files from the basis set.
Inspect Input Files: After running the basis_to_batman.m script, the folder where the BATMAN files were saved should contain the following files.
1. PureSpectraTemplate - This folder contains the spectrum of each basis set element as a ".txt" file. The file names will be metabolite1.txt, metabolite2.txt, metabolite3.txt, and so on, up to the number of basis set elements. Each file contains two columns: 1. a column of ppm values, 2. a column of intensity values for each ppm value.
2. metabolitesList.csv - This file contains a list of the names of each basis set element (metabolite1, metabolite2, etc.).
3. multi_data_user.csv - This file contains information for each multiplet in the basis set. Specifically, the file contains the chemical shift of the center, the chemical shift of each end, and the relative intensity of each multiplet.
4. NMRdata.txt - This file contains the spectra that will be fit by the basis set. The first column contains common ppm values, and all other columns contain intensity values for each spectrum.
BATMAN Parameter File
Download Parameter File: Download the batmanOptions.txt file below. This file contains adjustable parameters for the BATMAN fit.
batmanOptions.txt3KB Adjust Parameters: Download the batman.pdf file below. This file explains the parameters in batmanOptions.txt.
batman.pdf762KB The parameters and BATMAN in general are further explained in the original paper:
Organize Folders
Make a Folder for BATMAN Fitting: Create a new folder, ensuring there are no spaces in the name.
Make runBATMAN Folder: Inside the newly created folder, create a new folder named runBATMAN. The runBATMAN folder must have this exact name, case-sensitive.
Make BatmanInput and BatmanOutput Folders: Inside the runBATMAN folder, create two new folders named BatmanInput and BatmanOutput. The BatmanInput and BatmanOutput folders must have these exact names, case-sensitive.
Move Files into BatmanInput: Copy PureSpectraTemplate, metabolitesList.csv, multi_data_user.csv, NMRdata.txt, and batmanOptions.txt into the BatmanInput folder.
Pull BATMAN Container
Make a Folder to Hold the Container: Create a new folder outside of the folders created above to hold the BATMAN container.
Navigate to the Folder: Open the terminal and navigate (cd) to the folder where the BATMAN container will be stored.
Pull the Container: In the same terminal, run the command below
singularity pull docker://biocontainers/batman:phenomenal-v1.2.12.0_cv1.1.72
The container only needs to be pulled once, so if you run BATMAN in a future session, you can use the same container that was pulled here.
Run BATMAN
Execute R in the Container: Using the same terminal, execute the code below to open R from the container. By opening a new terminal and navigating (cd) to the folder where the container is stored, you can also execute R using the command below at any time.
singularity exec batman_phenomenal-v1.2.12.0_cv1.1.72.sif R
Activate BATMAN Functions: Once R is activated, run the command below to activate the BATMAN library of functions.
library('batman')
Change R Working Directory: In the code below, replace path_to_folder with the path of the folder that contains the runBATMAN folder; keep the single quotations. Running the code will change the R working directory. Do not include the runBATMAN folder itself in the path; instead, stop the path at the folder containing the runBATMAN folder.
setwd('path_to_folder')
Start BATMAN: Use the code below to start the BATMAN fitting.
bm = batman()
Inspect Fitting
Finished BATMAN Run: The BATMAN fitting will be completed once the terminal prompt (>) returns to the screen. The output will be located in the BatmanOutput folder.
Open Visualization Script: Open the inspect_batman_fitting.m script from the FLAnalyzer GitHub repository in MATLAB. The script can be found under the "workflows" section.
Visualize BATMAN Fits: Follow the directions in the comments (green text) to make plots and to calculate the percent quantified of the BATMAN fits.
Protocol references
1. Hao, J. et al. Bayesian deconvolution and quantification of metabolites in complex 1D NMR spectra using BATMAN. Nat Protoc 9, 1416–1427 (2014).