mdpocket Tutorial: Pocket Volume Over a GROMACS Trajectory

To track binding pocket volume during an MD simulation, first make the GROMACS trajectory whole and fit it onto a reference with gmx trjconv, keeping only the protein. Run mdpocket once to detect pockets across all frames, select your pocket’s grid points in PyMOL, then run it again with --selected_pocket. The file mdpout_descriptors.txt gives the pocket volume for every snapshot.
A docking pose followed by a 100 ns MD run is now a standard package in student theses and papers, and reviewers have learned to ask a sharper question than “was the RMSD stable?” They ask whether the pocket itself stayed open. A protein backbone can sit at a flat, low RMSD while a loop folds over the site and squeezes the ligand out, or while a cryptic sub-pocket opens next to it. RMSD cannot see either event. Pocket volume over time can.
This tutorial from the StemSkills Lab team (10+ years in structural bioinformatics, drug design and molecular modelling) shows the full mdpocket workflow on a GROMACS trajectory: preparing the input, the two mdpocket runs, choosing the pocket, reading the grids, plotting the volume, and the mistakes that give an empty or noisy result. Every mdpocket flag and output file name below comes from the official fpocket documentation for the current release, fpocket 4.2.3.
What is mdpocket and how is it different from fpocket?
mdpocket is the trajectory tool inside the fpocket package. fpocket finds pockets on one static structure using alpha spheres, spheres that touch four atoms and contain none inside (Le Guilloux, Schmidtke and Tuffery, BMC Bioinformatics 2009). mdpocket runs that detection on every snapshot of a trajectory and maps the alpha sphere centres onto a fixed 3D grid, so you can see which pockets persist, which open transiently, and how large a chosen pocket is in each frame. The method is described in Schmidtke, Bidon-Chanal, Luque and Barril, Bioinformatics 2011, 27(23):3276-3285.
mdpocket works in two running modes, and it picks the mode from your input:
- Mode 1, pocket detection: no
--selected_pocketflag. It writes frequency and density grids for the whole trajectory. - Mode 2, pocket characterisation: with
--selected_pocket my_pocket.pdb. It writes per-snapshot descriptors (volume, alpha sphere count, surface areas and more) for that one region.
Because the grid is fixed in space, the documentation is blunt about one requirement: “It is VERY IMPORTANT to first align (superimpose) all snapshots onto each other” (fpocket Getting Started guide). If the protein drifts or rotates, the same pocket lands on different grid points in each frame and the result is meaningless.
Which tool answers “did my pocket stay open”?
Students often reach for the analyses they already know. This table shows what each one can and cannot tell you about a binding site.
| Analysis | What it measures | Can it show pocket collapse or opening? | Typical use |
|---|---|---|---|
Backbone RMSD (gmx rms) | Global deviation from a reference structure | No, a local pocket change barely moves the global value | Is the protein equilibrated and stable? |
RMSF (gmx rmsf) | Per-residue fluctuation averaged over time | Indirectly, it flags flexible loops but not their effect on volume | Which regions move most? |
| fpocket on single frames | Pockets and volume on one structure | Only frame by frame, and pocket numbering changes between frames | Pocket prediction on a crystal structure or model |
| mdpocket mode 1 | Pocket frequency and density on a fixed grid across the trajectory | Yes, shows persistent and transient pockets visually | Finding cryptic or transient sites |
| mdpocket mode 2 | Volume and fpocket descriptors of one chosen region, per snapshot | Yes, gives a volume versus time series | Showing the binding site stayed open |
How do I install mdpocket?
mdpocket ships with fpocket, so installing fpocket gives you both programs. The fpocket README lists a conda-forge package, which is the easiest route on Linux and macOS:
conda config --add channels conda-forge
conda install fpocket
mdpocketRunning mdpocket with no arguments should print its usage text. If you compile from source instead, the installation guide notes that since version 3.0 you need the netcdf development library (for example sudo apt-get install libnetcdf-dev on Ubuntu) before running make and sudo make install.
How do I prepare a GROMACS trajectory for mdpocket?
mdpocket reads GROMACS xtc and trr files directly, along with dcd, netcdf, crd, crdbox and dtr. Trajectory formats store coordinates only, so you must also pass a PDB file with the same atoms in the same order, which mdpocket uses as the topology. Three gmx trjconv passes produce everything you need.
Step 1: make molecules whole and centre the protein
gmx trjconv -s md.tpr -f md.xtc -o md_whole.xtc -pbc mol -centerWhen prompted, choose Protein for centring and Protein for output. Writing protein only removes water and ions, which shrinks the file and stops mdpocket spending time on solvent. If your ligand is not part of the Protein group, it is left out too, which is usually what you want: you are measuring the cavity the protein forms.
Step 2: fit every frame onto the first
gmx trjconv -s md.tpr -f md_whole.xtc -o md_fit.xtc -fit rot+transChoose Backbone as the fit group and Protein as the output group. This is the superposition step the fpocket documentation insists on. Doing PBC repair and fitting as two separate passes is common GROMACS practice and avoids molecules being split across the box after the fit.
One subtlety: md.tpr describes the full system, while md_whole.xtc now contains protein only. If GROMACS complains that the atom counts do not match, make a protein-only run input with gmx convert-tpr -s md.tpr -o protein.tpr (select Protein when prompted) and pass -s protein.tpr in steps 2 and 3.
Step 3: write the matching reference PDB
gmx trjconv -s md.tpr -f md_fit.xtc -o reference.pdb -dump 0Choose Protein again. -dump 0 writes the frame at time 0, so the reference and the trajectory now contain identical atoms.
For a long run, subsample to keep the calculation manageable. Adding -dt 100 to step 2 keeps one frame every 100 ps. For scale, the fpocket guide reports about 0.4 seconds per snapshot for a 4,000-snapshot trajectory of 3,258 atoms on a single 2.66 GHz core. Your system is likely larger and your CPU newer, so time a short test first.
Want the guided, hands-on version?
Our live Molecular Modeling & MD Simulations cohort bootcamp takes you from zero to running real docking and MD workflows, with a portfolio project for your grad-school applications.
How do I run the first mdpocket pass (pocket detection)?
mdpocket --trajectory_file md_fit.xtc --trajectory_format xtc -f reference.pdb -o mdpoutThe -o flag sets the output prefix. When it finishes you get four files:
mdpout_freq_grid.dx: how often each grid point was inside a pocket, averaged over snapshots, so values run from 0 to 1. The documentation calls this grid “usually much easier to interpret”.mdpout_dens_grid.dx: the number of Voronoi vertices (alpha sphere centres) near each grid point per snapshot. Higher values mean more conserved, denser cavities.mdpout_freq_iso_0_5.pdb: dummy atoms at every grid point that was in a pocket for at least 50% of the trajectory.mdpout_dens_iso_8.pdb: dummy atoms at grid points with a density of 8 or more.
Load reference.pdb and mdpout_freq_grid.dx in VMD, display the grid as an Isosurface, and move the isovalue slider. A high value shows only pockets open most of the time. Lower it and transient pockets appear. This view alone answers a useful question: is my docked site among the persistent pockets, or is a different pocket more stable?
If you want mdpocket to weight the grid by druggability, add -S to this first run. The documentation recommends reading the frequency grid in that case and warns that the drug score was trained on default detection parameters, so do not combine -S with custom -m, -M or -i values.
How do I select the pocket I want to measure?
Mode 2 needs a PDB of grid points that defines your region. The quick way uses the iso file from the first run. In PyMOL:
load reference.pdb
load mdpout_freq_iso_0_5.pdb
select pocketpts, mdpout_freq_iso_0_5 within 6 of (reference and resi 45+67+112)
save my_pocket.pdb, pocketptsReplace 45+67+112 with the binding-site residues from your own docking pose (the residues that contact the ligand), and inspect the selection before saving. Remove points that belong to a neighbouring pocket. This choice drives your result more than any other step, so record which residues and which distance you used for your methods section. If you still need to define the site, our guide on how to find the protein binding site for docking covers it.
The documentation’s better way is to extract grid points at your own isovalue, as low as possible while pockets stay distinguishable, using the extractISOPdb.py script in the fpocket scripts folder (it needs numpy). Its usage line is the dx file, the output name, then the isovalue:
python extractISOPdb.py mdpout_freq_grid.dx freq_iso_0_3.pdb 0.3Then repeat the PyMOL selection on freq_iso_0_3.pdb.
How do I run the second pass and get pocket volume per frame?
mdpocket --trajectory_file md_fit.xtc --trajectory_format xtc -f reference.pdb --selected_pocket my_pocket.pdb -o mdpoutThis writes three files:
mdpout_descriptors.txt: one row per snapshot with the pocket volume, number of alpha spheres, mean alpha sphere radius, surface areas and the other fpocket descriptors.mdpout_mdpocket.pdb: the Voronoi vertices inside your region, one model per snapshot. View it in PyMOL as a movie of the pocket opening and closing (the guide notes VMD does not read this file, because the vertex count changes between models).mdpout_mdpocket_atoms.pdb: the protein atoms lining the region, one model per snapshot.
Check the column header before you plot: head -1 mdpout_descriptors.txt. The fpocket guide’s own example uses pock_volume, while its abbreviation list writes pock_vol, so read the name from your file rather than trusting either.
How do I plot pocket volume against time in Python?
import pandas as pd
import matplotlib.pyplot as plt
d = pd.read_csv("mdpout_descriptors.txt", sep=r"\s+")
vol = d["pock_volume"] # use the name from your header
dt_ns = 0.1 # time between saved frames, in ns
t = d["snapshot"] * dt_ns
plt.plot(t, vol, lw=0.6, alpha=0.5, label="per frame")
plt.plot(t, vol.rolling(50, center=True).mean(), lw=2, label="50-frame mean")
plt.xlabel("Time (ns)")
plt.ylabel("Pocket volume (ų)")
plt.legend()
plt.tight_layout()
plt.savefig("pocket_volume.png", dpi=300)Set dt_ns to match your saved interval (0.1 ns if you used -dt 100). fpocket reports volumes in cubic ångströms. Single frames are noisy, so judge the trend from the running mean, and compare against a reference such as the apo protein or a replicate run rather than reading meaning into one absolute number. Our guide to plotting GROMACS output in Python covers figure styling in more depth.
How should I interpret the result?
- Volume steady around its starting value: the site stayed open. Pair this with ligand RMSD to show the ligand also stayed in place.
- Volume drops and stays low: the pocket closed. Open
mdpout_mdpocket_atoms.pdbaround that time and find which loop or side chain moved in. Cross-check with RMSF for that region. - Volume jumps up: the pocket opened further or merged with a neighbour. Check
mdpout_mdpocket.pdbto see whether the vertices spill outside your intended region. - Large swings throughout: a flexible, shallow site, or a selection that is too generous. Tighten the region and rerun mode 2.
What goes wrong with mdpocket and how do I fix it?
- Empty or smeared grids, no clear pockets. The trajectory was not fitted. Redo step 2 with
-fit rot+transon Backbone and rerun mode 1. - mdpocket stops or reports a problem reading coordinates. The reference PDB and the trajectory have different atoms. Regenerate
reference.pdbfrom the same fitted xtc with-dump 0and the same output group. - Pockets look torn, half on each side of the box. PBC was not repaired before fitting. Run step 1 with
-pbc mol -centerbefore step 2, as two passes. Our common GROMACS errors guide covers related trjconv problems. - Mode 1 takes hours. You kept water, or you analysed every frame. Output Protein only, and subsample with
-dt. - Volume is zero or near zero for most frames. Your
my_pocket.pdbcovers the wrong region or too few points. Overlay it onreference.pdbin PyMOL, and rebuild it from a lower isovalue grid. - Python raises
KeyError: 'pock_volume'. The column has a different name in your output. Printd.columnsand use the exact name. - The pocket you care about never shows up in mode 1. It may be transient or channel-like. Lower the isovalue first. The guide also lists alternative detection settings, for example
-m 2.8 -M 5.5 -i 3for putative channels and small cavities.
How does this fit into a full docking and MD study?
Pocket volume belongs in the analysis set after a protein-ligand MD simulation in GROMACS, next to RMSD, RMSF, ligand RMSD and contact analysis. Run it on every replicate, and if you have an apo simulation, apply the same pocket selection to it: comparing holo and apo volume shows whether the ligand holds the site open. For the wider sequence of MD skills, see our guide to learning molecular dynamics with GROMACS and the computational biology skills roadmap.
Frequently asked questions
Can mdpocket read a GROMACS xtc file directly?
Yes. Pass --trajectory_file md_fit.xtc --trajectory_format xtc together with -f reference.pdb. The PDB supplies atom and residue names, because xtc files store coordinates only. Both files must contain the same atoms in the same order.
Do I need to remove water before running mdpocket?
You should. Keeping only the protein makes the run much faster and keeps detection focused on the protein surface. Use gmx trjconv and choose the Protein group as output in every pass, including the reference PDB.
What units is the mdpocket pocket volume in?
Cubic ångströms, the same as fpocket. Treat absolute values with caution, since they depend on your pocket selection. Compare trends over time, across replicates, or between apo and holo runs.
What is the difference between the frequency grid and the density grid?
The frequency grid records the fraction of snapshots in which each grid point was inside a pocket, from 0 to 1. The density grid counts nearby alpha sphere centres per snapshot. The fpocket authors describe the frequency grid as easier to interpret.
How should I cite mdpocket?
Cite Schmidtke P, Bidon-Chanal A, Luque FJ, Barril X. MDpocket: open-source cavity detection and characterization on molecular dynamics trajectories. Bioinformatics 2011;27(23):3276-3285. Many authors also cite the fpocket paper, Le Guilloux V, Schmidtke P, Tuffery P, BMC Bioinformatics 2009;10:168.
Written by the StemSkills Lab team, who have spent 10+ years in structural bioinformatics, drug discovery and multiscale molecular modelling. mdpocket commands checked against the fpocket 4.2.3 documentation.
Want the guided, hands-on version?
Our live Molecular Modeling & MD Simulations cohort bootcamp takes you from zero to running real docking and MD workflows, with a portfolio project for your grad-school applications.
