Metadata-Version: 2.4
Name: rmsx
Version: 0.1.5
Summary: Residue-level molecular-dynamics motion analysis and visualization
Author: Finn Beruldsen
License-Expression: MIT
Project-URL: Homepage, https://antuneslab.github.io/rmsx/
Project-URL: Documentation, https://antuneslab.github.io/rmsx/
Project-URL: Repository, https://github.com/AntunesLab/rmsx
Project-URL: Issues, https://github.com/AntunesLab/rmsx/issues
Keywords: molecular dynamics,protein dynamics,trajectory analysis,RMSF,RMSD,ChimeraX,bioinformatics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: MDAnalysis>=2.0.0
Requires-Dist: pandas>=1.1.0
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Dynamic: license-file

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

## Start Here: [Launch RMSX + Molstar in Google Colab](https://colab.research.google.com/github/AntunesLab/rmsx/blob/main/RMSX_Molstar_Colab_Demo.ipynb)

[![Open RMSX Molstar Colab Demo](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/AntunesLab/rmsx/blob/main/RMSX_Molstar_Colab_Demo.ipynb)

**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](https://doi.org/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.

![RMSX and Flipbook workflow overview](RMSX_Flipbook_how_to_linkedin.gif)

### Run Locally

Download the [Quick Start Guide Notebook](https://github.com/AntunesLab/rmsx/raw/main/RMSX_FlipBook_Quickstart.ipynb), 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](https://www.youtube.com/watch?v=UoN0GQKHCsw)

### 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**](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git#:~:text=Installing%20on%20Windows&text=Just%20go%20to%20https%3A%2F%2F,to%20https%3A%2F%2Fgitforwindows.org.) Installed and added to your path (likely already done if you are using macOS or Linux)
- [**Python**](https://www.python.org/) If not already installed (tested with 3.8+)
- [**Jupyter Notebooks**](https://phoenixnap.com/kb/install-jupyter-notebook#:~:text=Install%20Jupyter%20Notebook%20on%20Linux,via%20pip) (Recommended) 
- [**R**](https://cran.r-project.org/) 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**](https://www.cgl.ucsf.edu/chimerax/download.html) or [**VMD**](https://www.ks.uiuc.edu/Development/Download/download.cgi?PackageName=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**](https://github.com/AntunesLab/rmsx/raw/main/RMSX_FlipBook_Quickstart.ipynb)
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**:
   ```bash
   git clone https://github.com/AntunesLab/rmsx.git
   ```

2. **Install RMSX** in editable mode:
   ```bash
   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:

```python
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:

```python
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):

```python
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:

```python
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:

```python
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](https://www.cgl.ucsf.edu/chimerax/download.html) 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:

```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:

```bash
export RMSX_NO_CITATION=1
```

---

**That’s it!** For more examples and advanced usage check out the [**Quick Start Guide**](https://github.com/AntunesLab/rmsx/raw/main/RMSX_FlipBook_Quickstart.ipynb). If you need anything, open an [issue on GitHub](https://github.com/AntunesLab/rmsx/issues). 

### Color Palette Options

RMSX supports multiple perceptual palettes for heatmaps and flipbook coloring.

![Color options for RMSX and Flipbook](flipbook_and_rmsx_color_maps.png)

![Protease RMSX and Flipbook Example](protease_rmsx_flipbook_overview.png)




















