NMR_Plotter: A Python GUI for Generating Figures from NMR Spectra

Introduction

The preparation of high-quality, consistently styled figures is often an oddly tedious step for researchers presenting nuclear magnetic resonance (NMR) spectroscopy data. While many NMR software packages support built-in plotting and vector graphic export, producing figures with consistent styling and precise layout typically requires navigating complex interfaces in these programs, or even may not be possible at all, as these tools are not designed with figure creation as a primary goal. As a result, researchers often develop their own ad hoc methods to shuttle spectra from data processing environments into illustration tools such as Adobe Illustrator or Inkscape [1, 2], where axis conventions, offsets, fonts, and line weights are then manually reapplied across related datasets, which is time-consuming and prone to error.

Bruker TopSpin, the dominant platform for NMR data acquisition and processing, offers some plotting features [3], but researchers frequently need a finer degree of control in the transition from processed spectra to publication-ready vector figures, especially for overlay and stackplots containing data that may span many experiments and directories. Several software platforms aim to bridge the gap between data processing and presentation. Commercial packages such as Mnova (Mestrelab) and Spectrus (ACD/Labs) offer rich layout editors and reusable templates, but their cost and licensing restrictions limit accessibility [4, 5]. Within the open-source community, code-centric tools such as nmrglue paired with matplotlib offer highly flexible, script-based figure generation, and have become foundational in many NMR workflows [6, 7]. Likewise, ssNake provides an impressive open-source environment that integrates interactive and script-driven approaches to NMR data processing and plotting [8]. These projects demonstrate the power and versatility of community-developed software, but their reliance on scripting or advanced user input can still present a barrier for students or collaborators without programming experience. As a result, while many useful NMR processing tools exist, none offer a solution that is both accessible and purpose-built for creating precise, reproducible NMR figures.

NMR_Plotter addresses this gap through a lightweight graphical interface for generating consistent, publication-quality figures from NMR spectral data. Currently optimized for Bruker data/directory structures and for 1D plotting, the software provides a streamlined workflow from spectrum to figure, regardless of the user’s coding experience. Users can build overlay or stacked plots, customize axes, fonts, colors, and export sizes, and save and reuse styles via editable template files, ideal for aligning with journal guidelines or internal lab conventions. Figures are exported directly to vector formats using matplotlib, and can be used as-is or imported for further refinement in vector illustration tools. By automating the “last mile” of figure creation, NMR_Plotter enables fast, reproducible, and aesthetically consistent generation of figures, and aims to reduce the friction between data analysis and scientific communication.

Implementation and architecture

NMR_Plotter is implemented in Python using the built-in tkinter module for the graphical user interface (GUI) and Matplotlib for figure rendering. It is designed for a workflow in which users first process their raw time domain NMR data into spectra using Bruker TopSpin, then use NMR_Plotter to generate their figures from this processed data. The program encourages responsive iteration and quick testing of figure styling and layout, allowing users to move efficiently from spectra to finalized plots without writing code. The GUI is structured around five key regions (Figure 1): a Data Import browser for navigating experiments, a Plot Workspace that holds selected spectra and enables reordering in stack plots, a Templates and Preferences strip for file and state operations, a Plotting Parameters panel that binds visual controls to the plotting logic, and a matplotlib-based Plot canvas.

Figure 1

Two data import modes are supported, each tailored to a distinct workflow. The first mode provides direct access to Bruker pdata directories using the nmrglue package to read binary files directly [6]. During import, the program detects experiment folders containing both procs and 1r files, and when a particular spectrum is selected, reconstructs the frequency axis from Bruker acquisition parameters such as the spectrometer frequency, sweep width, and offset. The second mode is based on ASCII-formatted ascii-spec.txt files. In this workflow, users first export spectra from TopSpin using the AU program convbin2asc, which creates a human-readable file containing frequency and intensity columns. Only those spectra that have been explicitly converted in this way are detected, which makes this an opt-in import method. This selectivity has a useful side effect: by surfacing only the spectra the user has chosen to export, the ASCII import mode naturally declutters the Data Import panel. For users managing large project directories, this can streamline the plotting workflow by focusing attention only on key datasets.

On startup, the program reads a preferences.txt file that stores persistent settings. These include paths for selecting data directories, loading templates, and saving exported figures, along with the name of a default template that auto-loads styling settings into the GUI. Several behavioral toggles are also stored in this file, such as the import mode (ASCII or pdata), whether to normalize intensities, whether to couple the data mask to the x-axis limits, and whether to use fixed dimensions during export. These settings can be modified within the Preferences dialog, which writes changes back to the preferences.txt file for future sessions.

The behavior of the import browser upon addition of a new directory depends on the chosen mode. In pdata mode, the program determines whether the selected top-level directory has subfolders at the correct levels containing both procs and 1r files, and then adds them to the import tree. Any folders missing these files are skipped. In ASCII mode, the scan proceeds recursively and returns only directories that contain a valid ascii-spec.txt file, typically located at <sample>/<expno>/pdata/<procno>/ascii-spec.txt. To avoid redundant filesystem traversal and speed up repeated use, the results of each scan are saved in mode-specific cache files: cache_ascii.txt for ASCII scans and cache_pdata.txt for pdata scans. These caches can be reloaded during future sessions to repopulate the import list without rescanning the filesystem. If a user creates a new processed dataset in TopSpin, the cache will not include it until the parent directory is re-added, which triggers a rescan. Users may also delete the cache files directly to reset the scan state.

After directories are added to the Data Import browser, the user can then select desired spectra to add to the Plot Workspace. Multiple spectra may be added simultaneously, and these spectra can then be reorganized or removed using the Plot Workspace controls. Everything in the plot workspace will be plotted to the Plot canvas upon clicking the “Plot Spectrum” button. After pressing this button, each spectrum in the workspace undergoes a series of deterministic transformations that prepare it for plotting. For every selected trace, NMR_Plotter can restrict the visible x range (optionally coupled to the x limits), normalize intensities to unity with a user scaling factor, and lay out the figure in overlay or stacked mode.

All plotting parameters—including axis limits, unit selection (ppm, Hz, kHz), tick controls, color schemes, trace offsets, nucleus type (used for axis labeling), line widths, vertical padding, and export size—are managed through the Plotting Parameters panel. These parameters are bound to internal variables and changes can be immediately applied to the Plot canvas upon pressing the “Plot Spectrum” button. The y-axis is hidden by default for cleaner 1D figure presentation, while x-axis labels inherit the specified font and size. A formatted label combining the selected nucleus and units (e.g., “¹³C Chemical Shift (ppm)”) is generated automatically.

NMR_Plotter takes an intentionally hands-on approach to figure construction. Rather than relying on automated heuristics, users explicitly define parameters such as axis limits, scaling factors, and nucleus labels. The intention behind this philosophy is that figures can be recreated exactly, with identical ranges and styling across projects or manuscripts, without the software making hidden adjustments. It also provides flexibility for unusual use cases, since the program makes no assumptions about which spectra “should” be combined. For example, a user could overlay both ¹H and ¹³C spectra in a single figure, though in this case the axis label and range would need to be updated manually to remain meaningful. The same principle applies to stacked plots, where unadjusted scaling may push traces beyond the visible region, or to unit changes, where axis limits need to be reset. This flexibility also enables less conventional representations such as “pseudo-3D” plots, created by applying both y- and x-offsets between spectra (Figure 2A). Because the alignment and spacing are already handled within NMR_Plotter, finalizing the figure requires only minor adjustments to the plot borders in a vector graphics program (Figure 2B). Taken together, these behaviors highlight both the strength and the trade-off of the design: the software offers full control and transparency, which is valuable for careful figure preparation, but requires users to be attentive when defining parameters.

Figure 2

To maintain consistent styling across projects and save time when formatting figures, NMR_Plotter supports plot parameter templates. These are plain text files that map each plotting control to a saved value. Templates can be loaded to instantly apply a set of styling choices, or saved to disk for later reuse. If a default template is specified in preferences.txt, it will be applied automatically on startup. Because template files mirror the structure of the Plotting Parameters panel, they are fully portable and editable by hand if needed. This makes it easy for research groups to define and share house styles, or to conform to specific journal requirements.

Figures are rendered using a matplotlib figure embedded in the tkinter canvas. By default, users specify width, height, and DPI in millimeters, inches, or pixels. To help discover practical aspect ratios without resorting to guesswork, a resizable canvas mode allows interactive resizing and a capture action records the resulting dimensions back into the export fields. An optional “what you see is what you get” (WYSIWYG) preference bypasses explicit sizing to export exactly what appears on screen. Exports are written as vector graphics (SVG and PDF) and as PNG for raster use; transparency and clipping are minimized to reduce friction in downstream illustration software.

NMR_Plotter reflects how users actually prepare NMR figures and is designed to aid them in that effort: import the necessary spectra regardless of directory, arrange them in a clear order, and apply styling that carries through to the final output. The import panel shows only valid, processed datasets, which helps keep large directory trees manageable. The workspace makes it easy to assemble and reorder spectra, and the plotting system applies exactly the settings visible in the interface. This structure serves to produce clean vector graphics that require little to no subsequent modification in illustration software while also leaving room for future extension of functionality.

Quality control

Functional testing has been carried out regularly over two years of development. The software has been exercised extensively on Windows 11 and macOS Sequoia 15.4 with Python 3.12, where all GUI features, plotting behaviors, and export modes performed as expected. Graduate and undergraduate students have used NMR_Plotter extensively for figure preparation, and their feedback has driven improvements to layout control, import behavior, and the addition of features such as the directory tree cache. While broader testing on Linux is forthcoming, the reliance on standard cross-platform packages (Tkinter, Matplotlib, and optionally nmrglue) suggests strong compatibility. Exported figures have also been validated in Adobe Illustrator to confirm fidelity.

NMR_Plotter was developed with a strong emphasis on usability, stability, and anticipatory design. Because the tool targets users who may not be familiar with scripting or filesystem conventions, the graphical interface guides them toward success while preventing many common errors. For example, the directory scanning logic anticipates confusion about folder structure, particularly for users unfamiliar with the Bruker pdata hierarchy. Rather than requiring users to precisely locate 1r or ascii-spec.txt files, the program scans recursively through the top-level directory added by the user for valid matches and populates the import panel only with spectra that meet structural criteria. Invalid or incomplete folders are silently skipped, and if the top-level directory is chosen incorrectly, the program can detect this and sends a status message to the user. Changing plotting parameters is intuitive, and by modifying values and pressing the “Plot Spectrum” button, users can quickly iterate toward their preferred settings. This interactivity helps users identify issues (e.g., such as overlapping traces or unintentionally narrow x-windows) without needing to consult documentation or troubleshoot error messages. Persistent preferences and templates are stored in plain text files, which are loaded at startup. These allow for reproducibility across sessions but can be freely edited or reset. If default paths are no longer valid, or a template is malformed or missing, the program bypasses the issue and proceeds with default behavior while informing the user with a status message.

To assist new users, the GitHub repository includes a tutorial that walks through the core functionality using example data and preconfigured style templates. The tutorial mirrors a realistic plotting workflow and serves as a quick validation path for new installations: scanning the example directory, selecting spectra, assembling a plot, and exporting the result.

Operating system

Tested: Windows 11, macOS 15.4 Sequoia, expected compatibility with Linux

Programming language

requires Python 3.9+, tested on Python 3.12.

Additional system requirements

Typical laptop/desktop; no GPU required.

Enough RAM to load target spectra.

Dependencies

matplotlib

pandas

nmrglue >= 0.10 (optional; required for direct pdata/1r import)

(See requirements.txt in the repo for the canonical list and versions.)

List of contributors

Thomas Osborn Popp

Mithun Karthikeyan

Aidan Cuccaro

Konstantin Drallios

Software location

Archive (e.g. institutional repository, general repository) (required – please see instructions on journal website for depositing archive copy of software in a suitable repository)

Code repository (e.g. SourceForge, GitHub etc.) (required)

Emulation environment (if appropriate)

Not applicable

Language

The repository, software, readme, and tutorial are written in English.