RMSX and Flipbook: Simple-to-use, high-resolution mapping of molecular motions over time

Start Here: Launch RMSX + Molstar in Google Colab

No installation required. Run the bundled RMSX examples and explore interactive Molstar Flipbooks directly in your browser.

RMSX and Flipbook are described in our Scientific Reports paper, “High resolution mapping of protein motions in time and space with RMSX and Flipbook” (DOI: 10.1038/s41598-026-39869-7). RMSX combines features of RMSD and RMSF into a simple-to-understand and simple-to-implement approach for understanding how proteins move over time. It works with simulation files from common MD simulation suites, including GROMACS, NAMD, and AMBER, and is designed to generate high-resolution, publication-ready motion maps and Flipbook visualizations with minimal setup.

Run Locally

Download the Quick Start Guide Notebook, or clone this repository and run pip install -e ..

Video Walkthrough

If you'd like a guided overview of the method, watch the tutorial here:
RMSX + Flipbook Method Walkthrough

Interactive Flipbooks in Notebooks

Flipbook includes a Molstar viewer for interactive 3D visualization inside Jupyter notebooks and Google Colab. Use viewer="molstar" with run_rmsx_flipbook(...), or call write_molstar_flipbook(...) on an existing folder of slice_*_first_frame.pdb outputs. ChimeraX and VMD remain available as optional local viewers.

1. Prerequisites (click for install instructions)

• Git Installed and added to your path (likely already done if you are using macOS or Linux)
• Python If not already installed (tested with 3.8+)
• Jupyter Notebooks (Recommended)
• R installed and in your PATH (the Rscript command must be available).
• Molstar requires no separate installation and is the simplest option for notebooks and Colab.
• ChimeraX or VMD are optional local viewers.
• The RMSX code will attempt to install R packages like ggplot2, viridis, dplyr, etc., if they’re missing.

2. Installation

Once you have those installed, just download and run the Quick Start Guide Notebook It will walk you through the process and allow you to try RMSX, Trajectory Maps, and Flipbook on your own trajectories or bundled demo inputs from our publication.

The packaged notebook flow now works like this:

• Demo inputs are bundled inside the installed rmsx package.
• Demo outputs are written to ./rmsx_demo_outputs next to the notebook, not back into the packaged demo-data directory.

1. Clone this repository:

   git clone https://github.com/AntunesLab/rmsx.git

2. Install RMSX in editable mode:

   cd rmsx
   pip install -e .

   This also installs the required Python libraries (e.g., MDAnalysis).

(If installing on HPC or unusual platforms, you may need to manually install R libraries, but typically the R script handles that automatically.)

3. Single-Chain Analysis Example

Below is a minimal example showing how to analyze one chain. We add a brief comment for each parameter:

from rmsx import run_rmsx

pdb_file = "/path/to/your_structure.pdb"   # Topology file (PDB or GRO)
dcd_file = "/path/to/your_trajectory.dcd" # Trajectory file (DCD, XTC, etc.)
output_dir = "/path/to/output_directory"  # Folder where results go

run_rmsx(
    topology_file=pdb_file,        # PDB or topology file
    trajectory_file=dcd_file,      # Trajectory file
    output_dir=output_dir,         # Location for RMSX outputs
    num_slices=9,                  # Divide trajectory into 9 slices
    slice_size=None,               # (Alternately specify slice_size in frames)
    rscript_executable='Rscript',  # Path to Rscript
    verbose=True,                  # Print detailed logs
    interpolate=False,             # Disable heatmap interpolation
    triple=True,                   # Generate RMSX, RMSD, and RMSF plots
    overwrite=True,                # Overwrite existing folder
    palette="mako",                # Color palette
    chain_sele="A",                # Target chain ID
    start_frame=0,                 # First frame to analyze
    end_frame=None                 # Last frame (None = all frames)
)

You can optionally mask intrinsically disordered or unstable regions from the clipping range by passing raw MDAnalysis selections:

run_rmsx(
    ...,
    mask="segid A and resid 204:260"
)

Masked residues are clipped against the unmasked floor/ceiling, excluded from top/bottom summaries, shown with hatch overlays in heatmaps, and rendered transparently in Flipbook viewers.

What it does:

1. Reads frames from your trajectory, slices them, computes RMSX (slice-wise RMSF).
2. Also calculates RMSD and RMSF for the full simulation (if triple=True).
3. Creates raster heatmaps (.png) with the chosen palette and optionally a triple-plot figure.
4. Updates .pdb slice files in the output directory, storing RMSX values in the B-factor column.

4. Multi-Chain Analysis

If your system has multiple chains (e.g., chain A, chain B):

from rmsx import all_chain_rmsx

pdb_file_multi = "/path/to/multichain_structure.pdb"
traj_file_multi = "/path/to/multichain_trajectory.xtc"
output_dir_multi = "/path/to/multichain_output"

all_chain_rmsx(
    topology_file=pdb_file_multi,       # Multi-chain structure
    trajectory_file=traj_file_multi,    # Trajectory
    output_dir=output_dir_multi,        # Output folder
    num_slices=12,                      # Number of slices
    slice_size=None,                    # or specify frames per slice
    rscript_executable='Rscript',
    verbose=True,
    interpolate=False,
    triple=True,
    overwrite=True,
    palette="turbo",
    start_frame=0,
    end_frame=None,
    sync_color_scale=True  # Use a shared color scale across all chains
)

What it does:

1. Detects each chain ID in the topology.
2. Runs per-chain RMSX (and RMSD/RMSF) analysis.
3. If sync_color_scale=True, waits until all chains’ data is computed, finds a global min/max, and then plots each chain’s heatmap using the same color range.

5. Flipbook Visualization

To analyze your system and automatically generate an interactive 3D Flipbook, use:

from rmsx import run_rmsx_flipbook

run_rmsx_flipbook(
    topology_file=pdb_file,        # Topology (PDB/GRO)
    trajectory_file=dcd_file,      # Trajectory
    output_dir=output_dir,         # Output folder
    num_slices=9,                  # or slice_size=...
    rscript_executable='Rscript',
    verbose=True,
    interpolate=False,
    triple=True,                   # Also generate RMSD & RMSF plots
    overwrite=True,
    palette="mako",
    spacingFactor="0.6",           # Space out models for clarity
    viewer="molstar",              # "molstar", "chimerax", or "vmd"
    molstar_camera_mode="orthographic",  # or "perspective"
    start_frame=0,
    end_frame=None
)

1. Produces the RMSX heatmaps/plots just like run_rmsx.
2. Writes multiple PDB models (one per time slice) into a single file.
3. With viewer="molstar", writes a standalone HTML viewer and displays the interactive Flipbook directly in Jupyter or Colab.
4. With viewer="chimerax" or viewer="vmd", launches the external desktop viewer if installed.

If you already have a folder of slice_*_first_frame.pdb outputs, you can build the notebook viewer without rerunning RMSX:

from rmsx import write_molstar_flipbook

write_molstar_flipbook(
    "path/to/output/combined",
    palette="mako",
    camera_mode="orthographic",     # or "perspective"
)

6. Additional Notes

• First Runs R takes some time to download all the required packages the first time the program is run. This only happens once.
• Masked Heatmaps: Patterned masked heatmaps use ggpattern and require R 4.1+.
• Bundled Demo Inputs: The Quick Start notebook looks for demo files inside the installed rmsx package first, then falls back to repo-style test_files folders if you are running from source.
• Notebook Demo Outputs: The Quick Start notebook writes demo results into rmsx_demo_outputs next to the notebook so packaged demo files stay read-only.
• Chain IDs: If your PDB has chain “A” or “B”, but chain_sele="C" is passed, you’ll see errors or zero B-factors. Ensure the chain ID matches.
• ChimeraX: Download here if you’d like to visualize the Flipbook in ChimeraX.
• Jupyter Notebook Behavior: Use viewer="molstar" for an inline notebook/Colab viewer. If you use viewer="chimerax", the next cell may not run until you close ChimeraX.

7. Citation

If you use RMSX + Flipbook in your work, please cite:

Beruldsen, F., de Freitas, M.V. & Antunes, D.A. High resolution mapping of protein motions in time and space with RMSX and Flipbook. Scientific Reports (2026). https://doi.org/10.1038/s41598-026-39869-7

BibTeX:

@article{Beruldsen2026RMSXFlipbook,
  author = {Beruldsen, F. and de Freitas, M. V. and Antunes, D. A.},
  title = {High resolution mapping of protein motions in time and space with RMSX and Flipbook},
  journal = {Scientific Reports},
  year = {2026},
  doi = {10.1038/s41598-026-39869-7},
  url = {https://doi.org/10.1038/s41598-026-39869-7}
}

RMSX now prints this citation reminder once per Python session when analysis functions are first run.
To suppress it in automated pipelines, set:

export RMSX_NO_CITATION=1

---

That’s it! For more examples and advanced usage check out the Quick Start Guide. If you need anything, open an issue on GitHub.

Color Palette Options

RMSX supports multiple perceptual palettes for heatmaps and flipbook coloring.