Dynamics-Visualizer

A Streamlit-based app for post-MD analyses and visualization of GROMACS simulation trajectories.

Supports standard analyses (RMSD, RMSF, SASA, Radius of Gyration, Protein–Ligand minimum distance), PCA (protein-only and protein–ligand), DCCM (dynamic cross-correlation matrix), and a trajectory visualizer that can extract frames, render PNGs with PyMOL, and assemble MP4 MD-trajectory videos.

📑 Table of contents

1. 📝 Overview
2. 📦 Installation
3. 🏃 How to run
4. 📂 Input file formats & expected structure
5. 🔄 App workflows and usage
   • Standard analyses
   • PCA
   • DCCM
   • Trajectory visualizer
6. 📚 Citation
7. 📸 Rendered plots and MD-trajectory
8. ⚙️ Key implementation notes & limitations

📝 Overview

This repository contains a Streamlit application (app.py) that:

• Detects and reads common GROMACS .xvg analysis files.
• Produces publication-quality time-series plots (RMSD, RMSF, SASA, Radius of Gyration, PL-Minimum Distance).
• Runs PCA on trajectories and produces PCA plots with time-based colorbars.
• Computes and visualizes DCCM heatmaps.
• Extracts frames from a trajectory, renders PNG frames using PyMOL, and creates trajectory motion videos.

📦 Installation

Required Python packages:

• streamlit
• numpy
• matplotlib
• seaborn
• scikit-learn
• MDAnalysis
• opencv-python
• scipy

Create new conda environment (Recommended):

From repository root, open terminal and run:

conda create -n mdviz python=3.11

conda activate mdviz

pip install -r requirements.txt

Install PyMOL from conda-forge instead of pip:

conda install -c conda-forge pymol-open-source

• Alternatively, download PyMOL from the official website and add it to the system's PATH.

🏃 How to run

From repository root, run in terminal:

streamlit run app.py

📂 Input file formats & expected structure

Standard analyses (RMSD/RMSF/SASA/Rg/PL-Dist)

• Provide a main_input_dir with subfolders named (case-insensitive):

  • rmsd/
  • rmsf/
  • sasa/
  • gyrate/
  • pl-dist/

• Each subfolder should contain .xvg files for each complex.

• Use identical filenames across subfolders for each complex to ensure consistent line colors in all plots.

• See Examples folder for input directory format.

  ⚠️ If your .xvg headers are non-standard, detection may misclassify.

PCA / DCCM / Trajectory Visualizer

• Trajectory: .xtc (GROMACS trajectory)
• Input run file: .tpr or .pdb (GROMACS input run file or pdb file containing solvent and ions).
• Ligand ID: Residue name like LIG, UNK, UNL, or custom defined during simulation.
• Protein chain: single-letter chain ID (e.g., A).

⚠️ Always use centered trajectory .xtc files before running the Dynamics Visualizer, otherwise molecules may drift across the box, leading to misleading or poor-quality results.

🔄 App workflows and usage

Top-level selection in UI:

• Standard Analyses (RMSD, RMSF, SASA, Rg, PL-Dist)
• Principal Component Analysis (PCA)
• Dynamic Cross-Correlation Matrix (DCCM)
• Trajectory Visualizer

Standard analyses

1. Choose Standard Analyses.
2. Input:
   • Main input directory (contains subfolders described above).
   • Main output directory.
3. Click Run Visualizations.
4. Output: PNGs for each analysis type saved in the output directory.

Behavior & notes:

• Colors assigned per complex from fixed palette (20 colors by default).
• If the number of complexes exceeds the palette length, the app returns an error for that plot.
• Time-series smoothing is applied automatically; the smoothing window scales with the number of frames.

PCA

1. Choose PCA, pick Protein-only or Protein-ligand.
2. Provide trajectory (.xtc), input run file (.tpr or .pdb), ligand resname (for complex only), and output folder.
3. Run PCA. Output images:
   • protein_pca.png (always)
   • ligand_pca.png (for complex)
   • complex_pca.png (combined dual plot for complex)

Notes:

• Trajectory alignment is performed before PCA.
• PCA operates on flattened coordinates; large systems/timeframes can be memory-heavy.
• Colorbars show progression over time in ns.

DCCM

1. Choose DCCM, select Protein-only or Protein-ligand.
2. Provide trajectory, input run file, ligand resname (if needed), and output folder.
3. Output:
   • protein_dccm.png
   • complex_dccm.png

Notes:

• DCCM computed from CA atoms (and ligand heavy atoms if included).
• Matrix is clipped to [-1, 1] and plotted with a custom diverging colormap.
• Quadrants annotated if PL-complex plot.

Trajectory visualizer

Two workflows:

A) Extract Frames and Generate MD Video

Steps:

• Provide .xtc (trajectory) and input run file .tpr (or .pdb)
• Provide protein chain ID, ligand resname (for PL-complex), and an output folder path.
• After validating the trajectory, choose the number of frames to extract.
• Set image dimensions (width, height), DPI, and Frames per second (FPS).
• The app extracts evenly spaced frames, writes per-frame PDBs to pdb_frames/, renders PNG frames via PyMOL to png_frames/, and assembles:
  • md-trajectory.mp4
  • smooth-md_motion.mp4
• It also generates a frames extraction log file md.log.

Important:

• PyMOL rendering (ray tracing) may require an X display, or xvfb on headless machines.
• Rendering many frames at high DPI is time- and disk-consuming.

B) Generate MD Video from Existing Frames

Steps:

• Provide a directory path to existing PNG frames.
• Set FPS and provide output folder path.
• The app assembles frames into an MP4 and produces an MD-trajectory video.

Notes:

• Use a lower FPS value (between 15 and 40) to generate smooth trajectory videos.

📚 Citation

If you use this tool in your research, presentations, or publications, please consider citing it to acknowledge the effort behind its development:

Dynamics Visualizer. GitHub: https://github.com/usman4373/Dynamics-Visualizer

📸 Rendered plots and MD-trajectory

---

smooth-md_motion-compressed.mp4

⚙️ Key implementation notes & limitations

• .xvg files detection is heuristic. If files have atypical headers, detection may fail. Update detect_file_type() to match your .xvg headers.

• PyMOL dependency Frame rendering relies on the PyMOL Python API. On headless servers, run under xvfb or configure off-screen rendering. Ray tracing requires GPU/GL support; turn off ray tracing for the simplest headless runs.

• Memory usage PCA and DCCM load coordinates into memory. For large systems or long trajectories:

  • Subsample frames.
  • Use CA-only selections.
  • Consider incremental/online PCA or random projection approaches for scale.

• Performance DCCM is O(n_atoms² × n_frames) — expensive for large atom counts.

• Video encoding OpenCV VideoWriter is used; MP4 encoding/compatibility depends on platform codecs. Installing system ffmpeg is recommended.

---