NMRbot intro
Improvements in 2D 1H-13C HSQC spectral quality due to adaptive spectral-width.

NMRbot is a fast and easy alternative interface to setting up automated NMR data acquisition for a set of samples, utilizing the latest advances in Bruker NMR spectrometer hardware and software.

This is an accordion element with a series of buttons that open and close related content panels.


To facilitate the high-throughput acquisition of NMR experimental data on large sets of samples, we have developed a simple and straightforward automated methodology that capitalizes on recent advances in Bruker BioSpin NMR spectrometer hardware and software. Given the daunting challenge for non-NMR experts to collect quality spectra, our goal was to increase user accessibility, provide customized functionality, and improve the consistency and reliability of resultant data. This methodology, NMRbot, is encoded in a set of scripts written in the Python programming language accessible within the Bruker BioSpin TopSpinTM software. NMRbot improves automated data acquisition and offers novel tools for use in optimizing experimental parameters on the fly. This automated procedure has been successfully implemented for investigations in metabolomics, small-molecule library profiling, and protein-ligand titrations on four Bruker BioSpin NMR spectrometers at the National Magnetic Resonance Facility at Madison (NMRFAM). The investigators reported benefits from ease of setup, improved spectral quality, convenient customizations, and overall time savings.


NMRbot7 NMRbot


Usage Instructions for NMRbot:

1. Download the following zip files from NMRFAM Download Page, unzip, and place the python .py files in <Topspin Home>/exp/stan/nmr/py/user/
FAM_NMRbot.zip -Contains customizable NMRbot startup script
FAM_Tools.zip -Contains source script for NMRbot operation
2. In the Topspin command line, type ‘edpy FAM_NMRbot.py‘ to open the file for editing.
3. In the editor window that opens, ‘Save as‘ a different file name. Be sure this new name has the ‘.py‘ extension.
4. Make the following edits to uniquely identify your customized NMRbot start script:
4a. Edit the title variable (NO SPACES!). This variable will be included in the setup wizard window titles and output text file names.
4b. Edit the extratxt variable. This variable will appear in the setup wizard Start dialog, uniquely identifying your custom NMRbot script.
5. To utilize the NMRbot Manual input approach, edit the following variables:
5a. The funclt list variable.
– Leave this variable empty (i.e. funclt=[]). If left empty, the setup wizard will offer an interactive choice of input methods.
– Append the funclt variable list with the input methods that are needed for entering different types of information for automated acquisition. See below for a description of each input method.
5b. The parlt variable. Fill this list variable with the names of all experiment parameter sets that will be used. The setup wizard will offer a choice between all samples using the entire parlt list, or if certain samples should run select parameter sets.
6. Save‘ the edits you have made.
7. To begin the NMRbot setup wizard, type the name of the new file in the Topspin command line.
7a. For Manual input, click the ‘Manual‘ button, then proceed to answer the prompted questions.
7b. For Text File input, click the ‘Text File‘ button, then enter the full path to the setup text file (see below). The default path to this file is …/data/<User Name>/nmr/.
8. Once all setup information has been input, a confirmation screen will appear with the details of planned automated data acquisition. This information will also appear in the terminal window started with Topspin. If setup information was input using the Manual input approach, a text file will be generated in the default path for use with the Text File input approach.
9. Click the ‘Confirm‘ button to proceed with automated data acquisition.

NMRbot methods for Manual input or Text File input:

Below is a brief description of the input methods for the Manual approach used by the NMRbot setup wizard. The names of desired methods should be appended to the funclt variable in the startup script. These methods closely correspond to the tags used to identify variables in the Text File input approach. Required methods are noted, and must be included in text file input. Manual input automatically uses required methods. Other differences are noted for Manual and Text File inputs.

series_watstd <Optional>
Allows the option to use a 90/10%,H2O/D2O standard sample for initial 3D shimming before sample series data is acquired.
default = 0
(Manual) – Input water standard sample position. Input of 0 deselects this option.
(Text File) – Set ‘_series_watstd‘ to sample position number. Set to ‘0‘ to deselect this option.
sample_num <Required>
Sets the number of samples in the series for NMRbot automated data acquisition.
default = 10
(Manual) – Input number of samples in series.
(Text File) – This number is inferred from the number of rows of sample information (see below).
sample_names <Required>
Defines unique sample names NMRbot uses for folder names, experiment title labels, and output file names.
default = [‘sample1′,’sample2’,…] one for each sample
(Manual or Text File<_sample_name>) – Input unique sample names. NO SPACES! Use underscores instead.
sample_solvs <Required>
Defines the deuterated solvent for each sample in the series that NMRbot will use for the ‘lock‘ command.
default = [‘CDCl3′,’CDCl3’,…] one for each sample
(Manual) – Can define the same solvent for the series or, alternatively, differently for each sample.
(Text File<_sample_solvent>) – Input the solvent for each sample.
sample_positions <Required>
Defines each sample position NMRbot will use to submit to the SampleJet accessory for loading into spectrometer.
default = [101,102,…] one for each sample
(Manual or Text File<_sample_position>) – Input unique sample position number.
sample_parlts <Required>
Defines the parameter sets (experiments) NMRbot will load and run for each sample.
default = [‘standard1D’]
(Manual) – Can define the same parameter sets to be run for all samples in the series or, alternatively, differently for each sample.
(Text File <_sample_parlt>) – Input the list of parameter sets for each sample, with NO SPACES after commas (see below).
sample_folderformat <Optional>
Allows NMRbot to use input parameters to create the folder name for each sample’s set of experiments. Each parameter should be given a rank, 1-5, for the desired order to appear in the folder name. Parameters set to 0 are not used.
default =
Sample Name = 1
Sample Solvent = 2
Sample Position = 3
Sample Conditions = 0
Date = 4
(Manual or Text File<folder_format>) – Input rank number for each parameter to be used in sample folder names.
sample_conds <Optional>
Allows a text space for user notes concerning sample conditions. This text can be included in folder names, and will be included in experiment title labels.
default = [”,”,…]
(Manual or Text File<_sample_condition>) – Input unique sample condition notes. NO SPACES! Use underscores instead.
sample_NSmult <Optional>
Allows NMRbot to multiply the number of scans (NS) in all experiments performed on a specific sample by a specified factor. This is useful for low concentration samples that run the same parameter sets as other samples in the series.
default = 1
(Manual or Text File) – Input factor to multiply the number of scans performed.
sample_expadapt <Optional>
Allows NMRbot to use its adaptive spectral-width (SW) feature, with which optimum SW for each nucleus can be determined from 1D experiments, and then applied to subsequent nD experiments on the same sample.
default = [0,0,…] one entry for each parameter set in a sample’s parlt
(Manual) – Input 1 for 1D experiments to determine optimum SW. Input 2 for nD experiments to adapt SW to previously determined optimum. By definition, a 1D experiment set to 1 must be run before any experiments set to 2.
(Text File) – Set ‘_sample_adaptlt‘ list entries according to rules for manual input and index of parlt.
series_getprosol <Optional>
Allows NMRbot to retrieve prosol parameters for pulse power and lengths.
default = 1
(Manual) – Input ‘y‘ to retrieve prosol parameters, or input ‘n‘ to use parameter set values.
(Text File) – Set ‘_series_getprosol‘ to ‘1‘ to retrieve prosol parameters, or ‘0‘ to use parameter set values.
series_findH2Ooffset <Optional>
Allows NMRbot to automatically determine the offset of the large HDO signal in H2O or D2O containing solvents.
default = 0
(Manual) – Input ‘y‘ to determine the HDO offset, or input ‘n‘ to use the offset from the parameter set.
(Text File) – Set ‘_series_findH2Ooffset‘ to ‘1‘ to determine the HDO offset, or ‘0‘ to use the offset from the parameter set.
series_wobb <Optional>
Allows NMRbot to tune the the NMR probe after each new sample is inserted into the spectrometer.
default = 0
(Manual) – Input ‘y‘ to tune the probe for each new sample, or input ‘n‘ skip probe tuning.
(Text File) – Set ‘_series_wobb‘ to ‘1‘ to tune the probe for each new sample, or ‘0‘ to skip probe tuning.
series_shimcmd <Optional>
Sets the TopShim command to be used after each new sample is inserted into the spectrometer. The first part of this entry MUST BE ‘topshim‘, followed by any additional desired shim parameters (see Bruker manuals).
default = ‘topshim tuneb tunea’
(Manual) – Input the desired topshim command to run, or leave blank to skip shimming.
(Text File) – Set ‘_series_shimcmd‘ to the desired topshim command to run, or leave blank to skip shimming.
series_autogain <Optional>
Allows NMRbot to optimize the reciever gain (RG) for each experiment.
default = 0
(Manual) – Input ‘y‘ to determine the optimum RG for each experiment, or input ‘n‘ to use the RG from the parameter set.
(Text File) – Set ‘_series_autogain‘ to ‘1‘ to determine the optimum RG for each experiment, or ‘0‘ to use the RG from the parameter set.

Text File Input

The text below is an example of the contents of a file submitted to NMRbot for the Text File Input approach. In this case, 3 samples are submitted for automated acquisition.

U1 H2O+D2O 102 standard1D,tocsy pH_3.5 1 1,2
U2 CDCl3 103 standard1D,hsqc,tocsy 100mM 1 1,2,2
U3 Acetone 104 standard1D,13C_1D 50mM 2 0,0folder_format
_sample_name 2
_sample_solvent 3
_sample_position 1
_sample_condition 0
_date_tag 0series_params
_series_watstd 101
_series_getprosol 1
_series_findH2Ooffset 1
_series_wobb 1
_series_shimcmd topshim ls tuneb tunea
_series_autogain 1end_

The ‘sample_info‘ loop first contains the names of the sample specific inputs (see above) in the order they appear for each sample info row that immediately follow the input names.
-Their names (1st column for sample info) are U1, U2, and U3.
-Their solvents (2nd column) are H2O+D2O, CDCl3, and Acetone.
-Their positions (3rd column) are 102, 103, and 104.
-Their experimental parameters (4th column) are denoted, separated by commas (NO SPACES!).
-Their condition notes (5th column) are included (NO SPACES!).
-Their NS multiplier factor (6th column) are denoted.
-Their adaptive SW values (7th column) are denoted, separated by commas (NO SPACES!). Notice that the number of values in this column match the number of parameter sets (4th column).

For example, the U2 sample will use the standard1D experiment to determine the optimum SW for the proton dimension. This value will be used to adapt the proton SW parameters for the hsqc and tocsy experiments of U2.

The folder_format variables given will create sample folder names using the sample_position, sample_name, and sample_solventvariables. For example, data for the third sample will be collected in a folder named ‘104.U3.Acetone‘.

The series_params variables give the functions performed across the series of samples. For example: a water standard for 3D shimming is found at position 101, each experiment will retrieve prosol parameters,
samples containing H2O or D2O will have their offset automatically determined, the probe will be tuned for each new sample, samples will be shimmed using ‘topshim ls tuneb tunea‘, and the RG will be optimized for each experiment.


Contact Larry Clos II, Ph.D.



Clos II, L.J., Jofre, M.F., Ellinger, J.J., Westler, W.M., Markley, J.L. (2013). NMRbot: Python scripts enable high-throughput data collection on current Bruker BioSpin NMR spectrometers. Metabolomics 9(3),558-563. PMID-23678341