rmsx 0.1.0__tar.gz

rmsx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Finn2400
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rmsx-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: rmsx
+Version: 0.1.0
+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)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

rmsx-0.1.0/README.md

@@ -0,0 +1,247 @@
+# 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)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

rmsx-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rmsx"
+version = "0.1.0"
+description = "Residue-level molecular-dynamics motion analysis and visualization"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [{name="Finn Beruldsen"}]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["molecular dynamics", "protein dynamics", "trajectory analysis", "RMSF", "RMSD", "ChimeraX", "bioinformatics"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+  "MDAnalysis>=2.0.0",
+  "pandas>=1.1.0",
+#  "plotly>=4.14.3"
+]
+
+[project.urls]
+Homepage = "https://antuneslab.github.io/rmsx/"
+Documentation = "https://antuneslab.github.io/rmsx/"
+Repository = "https://github.com/AntunesLab/rmsx"
+Issues = "https://github.com/AntunesLab/rmsx/issues"
+
+[project.optional-dependencies]
+docs = ["mkdocs-material>=9.5"]
+
+[project.scripts]
+rmsx = "rmsx.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["rmsx*"]
+
+[tool.setuptools.package-data]
+rmsx = [
+  "r_scripts/*.R",
+  "commands.cxc",
+  "vmd_scripts/*.tcl",
+  "molstar_static/script.js",
+  "molstar_static/vendor/molstar/5.4.2/*",
+  "test_files/*",
+]

rmsx-0.1.0/rmsx/__init__.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+__all__ = [
+    "run_rmsx",
+    "combine_pdb_files",
+    "all_chain_rmsx",
+    "run_rmsx_flipbook",
+    "run_flipbook",
+    "run_shift_map",
+    "all_chain_shift_map",
+    "run_shift_flipbook",
+    "MolstarFlipbookResult",
+    "build_molstar_manifest",
+    "write_molstar_flipbook",
+]
+
+_CORE_EXPORTS = {
+    "run_rmsx",
+    "combine_pdb_files",
+    "all_chain_rmsx",
+    "run_rmsx_flipbook",
+    "run_shift_map",
+    "all_chain_shift_map",
+    "run_shift_flipbook",
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _CORE_EXPORTS:
+        core = import_module(".core", __name__)
+        return getattr(core, name)
+    if name == "run_flipbook":
+        flipbook = import_module(".flipbook", __name__)
+        return getattr(flipbook, name)
+    if name in {"MolstarFlipbookResult", "build_molstar_manifest", "write_molstar_flipbook"}:
+        molstar_viewer = import_module(".molstar_viewer", __name__)
+        return getattr(molstar_viewer, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    # Avoid importing heavy dependencies during introspection/test discovery.
+    return sorted(set(globals().keys()))

rmsx-0.1.0/rmsx/__main__.py

@@ -0,0 +1,5 @@
+# rmsx/__main__.py
+from .cli import main
+if __name__ == "__main__":
+    main(prog="rmsx")
+