mdpocket Tutorial: Pocket Volume Over a GROMACS Trajectory
Skip to content

mdpocket Tutorial: Pocket Volume Over a GROMACS Trajectory

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_pocket flag. 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.

AnalysisWhat it measuresCan it show pocket collapse or opening?Typical use
Backbone RMSD (gmx rms)Global deviation from a reference structureNo, a local pocket change barely moves the global valueIs the protein equilibrated and stable?
RMSF (gmx rmsf)Per-residue fluctuation averaged over timeIndirectly, it flags flexible loops but not their effect on volumeWhich regions move most?
fpocket on single framesPockets and volume on one structureOnly frame by frame, and pocket numbering changes between framesPocket prediction on a crystal structure or model
mdpocket mode 1Pocket frequency and density on a fixed grid across the trajectoryYes, shows persistent and transient pockets visuallyFinding cryptic or transient sites
mdpocket mode 2Volume and fpocket descriptors of one chosen region, per snapshotYes, gives a volume versus time seriesShowing 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
mdpocket

Running 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 -center

When 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+trans

Choose 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 0

Choose 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.

Join the waitlist (free) →

How do I run the first mdpocket pass (pocket detection)?

mdpocket --trajectory_file md_fit.xtc --trajectory_format xtc -f reference.pdb -o mdpout

The -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, pocketpts

Replace 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.3

Then 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 mdpout

This 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.pdb around 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.pdb to 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+trans on Backbone and rerun mode 1.
  • mdpocket stops or reports a problem reading coordinates. The reference PDB and the trajectory have different atoms. Regenerate reference.pdb from the same fitted xtc with -dump 0 and 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 -center before 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.pdb covers the wrong region or too few points. Overlay it on reference.pdb in PyMOL, and rebuild it from a lower isovalue grid.
  • Python raises KeyError: 'pock_volume'. The column has a different name in your output. Print d.columns and 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 3 for 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.

Join the waitlist (free) →

Think you know Molecular Dynamics (GROMACS)?
Take the free StemSkills assessment and earn a verifiable certificate you can download and add to your LinkedIn profile.
Start the free assessment

Keep going

Periodic Image Check in GROMACS: gmx mindist -pi Prove your protein never touched its own periodic image: run gmx mindist -pi, read the xvg against your… Dihedral Angle Analysis in GROMACS: gmx angle and gmx chi Track ligand torsions with gmx angle and side-chain rotamer flips with gmx chi, build the 4-atom index group… GROMACS MD With Two Ligands: Topology, Index, Restraints Set up a GROMACS run with two bound ligands: merge topologies, fix duplicate atomtypes, build index groups and…
See live workshops