gmx_MMPBSA_ana: The analyzer tool¶

Overview¶

gmx_MMPBSA_ana is a simple but powerful tool for analyzing gmx_MMPBSA results. It provides fast access to several types of plots and includes options for customizing graphs and exporting high-quality figures (Figure 1). The tool has been optimized to handle many charts (see the performance section). It retains the core design of its predecessor, gmx_MMPBSA_ana v1.4.3, but uses a substantially different back-end API and is therefore incompatible with files from earlier versions.

Fast like a rocket¶

After version 1.5.2, gmx_MMPBSA_ana experienced serious performance problems. We reworked its implementation from the ground up; the benchmark results are shown below.

To this end, we have made the following changes:

• Reimplemented multiprocessing for reading systems.
• Implemented multithreading for data processing.
• Improved the reading of output files and optimized data storage.
• Eliminated the recalculation of IE and C2 entropies before opening the GUI; values are now read from output files.
• Optimized data storage and access to subsets in pandas DataFrames.
• Prevented file processing and figure generation from freezing the GUI.
• Removed redundant steps and data.
• Removed line graphs for components in the per-wise decomposition schema.
• Data access, processing, and storage are done in the API.
• Added the option to temporarily store data on the hard disk instead of memory.
• Removed several pop-up windows.
• Added waiting indicators.
• Added multiple systems, subsystems, and component selection options.

gmx_MMPBSA_ana components¶

1. System selection window
2. Data/Correlation panel
3. Options panel
4. Plot area
5. Menus

1- System selection window¶

This dialog allows you to select the systems of interest and their components. The available options control how gmx_MMPBSA_ana processes the result files:

• Energy Options selects which complex (COM), receptor (REC), ligand (LIG), and delta data are loaded. Remove empty terms hides terms whose absolute value is below the configured threshold (the default is 0.01 kcal/mol).
• Decomposition Options selects which decomposition data are loaded. Remove non-contributing residues hides residues below the configured per-residue threshold (the default is 0.5 kcal/mol).
• The result tree lets you include normal and mutant systems, enter experimental Ki values, select systems for correlation, and choose a reference system for a ΔΔG correlation. The Chart Settings column selects the saved chart configuration for each system.
• Correlation enables between-system analysis when more than three systems are loaded and lets you choose ΔG or ΔΔG.
• Convert frames to time changes the x-axis from frame numbers to a user-defined start, scale, and time unit.
• Charts options controls whether chart toolbars are hidden and whether the current chart configuration is reset.
• Performance Options provides a simple performance preset or advanced controls for in-memory loading and the number of multiprocessing jobs.

This allows you to take advantage of the flexibility of gmx_MMPBSA to carry out several analysis types in the same run and focus on the key elements for each of these analyses.

2- Data/Correlation panel¶

This panel contains two independent subpanels, Data and Correlation, which have similar organization but slightly different functions.

Structure¶

Buttons and Actions¶

Each item represents data associated with a calculation type and component (e.g., complex, receptor, ligand, or delta). The available buttons and actions depend on the data in the item. An item can have up to seven buttons:

Button	Visual element	Description
	Result files	Open the calculation output; the decomposition output is available when decomposition data were loaded.
	Line plot	Show or hide the component by frame, with an optional Show in table action.
	Bar plot	Show or hide the aggregate component plot, with an optional Show in table action.
	Heatmap	Show or hide the per-residue or pairwise heatmap, with an optional Show in table action.
	PyMOL visualization	Open the complex per-residue energy representation in PyMOL; PyMOL must be available in PATH.
	Summary table	Show or hide the summary table for a parent item with multiple energy components.
	Multiple activation button	Toggle all available actions for the item at the same time.

The line, bar, and heatmap buttons have a drop-down menu with a Show in table action. The multiple activation button toggles all available actions for the selected item, including the result table when that action is available.

Example:

3- Options panel¶

The panel starts with a selection control and contains two tabs. Selected System applies changes to the current system; All Systems becomes available when multiple systems are loaded.

4- Plot area¶

In this area, the graphs and tables included in each system will be displayed in the form of sub-windows (multi-document interface). This format allows you to move, resize and close each sub-window, offering a clean, organized, and fluid workspace to analyze a vast number of graphs.

Types of charts¶

Line plotBar plotHeatmap plotPyMOL visualization

Represents the evolution of a component during the simulation time. In some cases, it is the value of the calculated parameter, e.g.: TOTAL DELTA, VDWAALS, etc.; and in others, it is the sum of the elements it contains, eg: TDC as the sum of all the per-residue energy contributions.

Note

The line plot can additionally contain the moving average (solid red line) or other elements such as other indicators (dash red and green lines).

Warning

Note that TDC, SDC, and BDC are calculated from the immediate items contained within themselves. This means that the results obtained for the TDC in a per-residue calculation will probably be different from the TDC of a per-wise calculation with the same residues. This is because the per-residue energy contribution is calculated taking into account the environment that surrounds each residue, so the sum of their contributions will be exactly the maximum contribution per selected residues. On the other hand, in the per-wise calculation, the TDC will be equal to the sum of each residue contribution, the difference being that the contribution of each residue is obtained from the contributions of the selected pairs and not with all the environment that surrounds it. Therefore, both calculations should be used for different purposes and care should be taken with the interpretation of the results.

Shows the aggregate contribution of a component over the simulation. Depending on the quantity, a bar represents either an average (for example, TOTAL DELTA, VDWAALS, or per-residue contributions) or a sum (for example, NMODE entropy, QH entropy, or binding free energy). Bars that represent averages can include an uncertainty line. The uncertainty representation is configurable as Block SEM, Block SD, SD, or SEM; Block SEM is the default for correlated trajectories.

Shows how several components vary across frames or residue relationships. A per-residue heatmap displays residue contributions by frame, while a per-wise heatmap displays the relationships between residue pairs. Receptor and ligand residues can be highlighted with separate colors.

Tip

The relational heatmap is usually the clearest representation for pairwise decomposition analysis.

Shows the complex per-residue energy representation in a new PyMOL instance.

5- Menus¶

This section contains three drop-down menus:

Representations¶

Functionalities¶

Binding Free Energy calculation (GB + IE)¶

Alanine scanning¶

Per-residue decomposition¶

gmx_MMPBSA_ana under pressure¶

For this experiment, the examples directory was replicated nine times to produce 99 systems; this differs from the examples available on GitHub. The analyzer loaded approximately 1.6 million items, each containing one to three graphs, for a total of roughly 1.8 million graphs. Loading took about 11 minutes, primarily because the data associated with each graph was processed serially. Typical workloads take about 25-30 seconds, depending on the hardware and data. Because each graph's data is retained in memory, RAM use reached approximately 14 GB during this stress test.

Does this mean that you will not be able to load 100 systems in gmx_MMPBSA_ana? Not at all. Consumption depends on the type of calculation you have made, and the data you want to analyze. In this experiment, several systems contained decomposition data, and the complex, receptor, and ligand components were all selected even though some are usually omitted. A single pairwise calculation involving about 40 amino acids can generate approximately 11,000 items.