fastmdanalysis 0.0.3

Software for automated MD trajectory analysis

---

Highlights

• Perform complex molecular dynamics analyses with intuitive, single-line commands
• Automatically generate publication-quality figures with customizable styling for immediate use
• Seamlessly switch between Python API for advanced workflows and CLI for rapid batch processing
• Scalable workflows that handle everything from quick exploratory analysis to large-scale production runs

Analysis Modules

Analysis	Description
rmsd	Root-Mean-Square Deviation relative to a reference frame
rmsf	Per-atom Root-Mean-Square Fluctuation
rg	Radius of Gyration for molecular compactness
hbonds	Hydrogen bond detection and count using Baker-Hubbard algorithm
ss	Secondary Structure assignments using DSSP
cluster	Trajectory clustering using KMeans, DBSCAN, and Hierarchical methods
sasa	Solvent Accessible Surface Area with total, per-residue, and average per-residue
dimred	Dimensionality reduction using PCA, MDS, and t-SNE methods

Installation

Recommended: Install in a Virtual Environment

We strongly recommend installing FastMDAnalysis in a virtual environment to avoid conflicts with system packages and ensure the fastmda command is available in your PATH.

Using venv (Python's built-in virtual environment):

# Create a virtual environment
python -m venv fastmda_env

# Activate the virtual environment
# On Linux/macOS:
source fastmda_env/bin/activate
# On Windows:
# fastmda_env\Scripts\activate

# Install FastMDAnalysis
pip install fastmdanalysis

# Verify installation
fastmda --version
fastmda analyze --help

Using conda:

# Create a conda environment
conda create -n fastmda_env python=3.9

# Activate the environment
conda activate fastmda_env

# Install FastMDAnalysis
pip install fastmdanalysis

# Verify installation
fastmda --version
fastmda analyze --help

Usage

Command-Line Interface (CLI)

After installation, you can run FastMDAnalysis from the command line using the fastmda command. Global options allow you to specify the trajectory and topology file paths. Optionally, specify frame selection and atom selection. Frame selection is provided as a tuple (start, stop, stride). Negative indices (e.g., -1 for the last frame) are supported. If no options are provided, the entire trajectory and all atoms are used by default.

Run the analyze orchestrator to execute multiple analyses in one go.

Run all available analyses

fastmda analyze -traj path/to/trajectory -top path/to/topology

Include specific analyses

fastmda analyze -traj traj.dcd -top top.pdb --include rmsd rg

Exclude specific analyses

fastmda analyze -traj traj.dcd -top top.pdb --exclude sasa dimred cluster

Supply options via file (YAML or JSON)

fastmda analyze -traj traj.dcd -top top.pdb --options options.yaml

Create a slide deck from generated figures

fastmda analyze -traj traj.dcd -top top.pdb --options options.yaml --slides

Global flags:

• --frames start,stop,stride (e.g., 0,-1,10)
• --atoms "MDTraj selection" (e.g., protein and name CA)
• --output DIR (output directory name)
• --verbose (prints progress and writes logs under <command>_output/ unless --output is set)

Show help:

• fastmda -h
• fastmda analyze -h

Options file (schema)

Provide per-analysis keyword arguments in a single file. CLI and Python API share the same schema:

# options.yaml
rmsd:
  ref: 0
  align: true
rg:
  by_chain: false
cluster:
  methods: [kmeans, hierarchical]
  n_clusters: 5
  eps: 0.3
  min_samples: 8

JSON is also supported. If using YAML, ensure PyYAML is installed.

Slides:

• --slides creates fastmda_slides_<ddmmyy.HHMM>.pptx in the current working directory.
• --slides path/to/deck.pptx writes to an explicit filename.

Single-analysis commands (legacy, still available)

fastmda rmsd   -traj traj.dcd -top top.pdb --ref 0     # aliases: --reference-frame, -ref
fastmda rmsf  -traj traj.dcd -top top.pdb
fastmda rg     -traj traj.dcd -top top.pdb
fastmda ss -traj traj.dcd -top top.pdb
fastmda cluster -traj traj.dcd -top top.pdb --methods kmeans hierarchical --n_clusters 5

Python API

Instantiate a FastMDAnalysis object with your trajectory and topology file paths.

Run the analyze orchestrator to execute all available analyses.

from fastmdanalysis import FastMDAnalysis
from fastmdanalysis.datasets import TrpCage  # optional helper

fastmda = FastMDAnalysis(TrpCage.traj, TrpCage.top)
fastmda.analyze()

Include or Exclude specific analyses; specify options, generate slides

fastmda = FastMDAnalysis(TrpCage.traj, TrpCage.top)
result = fastmda.analyze(
    include=["rmsd", "rg"],                 # or exclude=[...]; omit to run all
    options={"rmsd": {"ref": 0, "align": True}},
    slides=True                             # or slides="results.pptx"
)

(Optional) Access per-analysis outputs

rmsd_result = result["rmsd"].value          # object/type depends on analysis
slides   = result.get("slides")             # AnalysisResult; .ok and .value (path)

Notes

• Figures are saved during each analysis; slide decks include all figures produced in the run.
• MDTraj may emit benign warnings (e.g., dummy CRYST1 records); they do not affect results.

Output

Output includes data files, figures, logs ...

Documentation

The documentation (with an extensive user guide) is available here.

Contributing

Contributions are welcome. Please submit a Pull Request.

Development Installation

If you want to contribute or modify the code:

# Clone the repository
git clone https://github.com/aai-research-lab/FastMDAnalysis.git
cd FastMDAnalysis

# Create and activate virtual environment
python -m venv fastmda_env
source fastmda_env/bin/activate  # On Windows: fastmda_env\Scripts\activate

# Install in development mode with test dependencies
pip install -e ".[test]"

# Verify installation
fastmda --version
fastmda analyze --help

Citation

If you use FastMDAnalysis in your work, please cite:

Adekunle Aina and Derrick Kwan (2025). FastMDAnalysis: Software for Automated Molecular Dynamics Trajectory Analysis. GitHub. https://github.com/aai-research-lab/fastmdanalysis

@software{FastMDAnalysis,
  author       = {Adekunle Aina and Derrick Kwan},
  title        = {FastMDAnalysis: Software for Automated Molecular Dynamics Trajectory Analysis},
  year         = {2025},
  publisher    = {GitHub},
  url          = {https://github.com/aai-research-lab/fastmdanalysis}
}

License

FastMDAnalysis is licensed under the MIT license.

Acknowledgements

FastMDAnalysis builds upon excellent open-source libraries to provide its high-performance analysis capabilities and to improve workflow efficiency, accessibility, usability, and reproducibility in molecular dynamics trajectory analysis. We gratefully acknowledge:

• MDTraj for foundational trajectory I/O and analysis modules
• NumPy for efficient numerical computations
• scikit-learn for advanced machine learning algorithms
• Matplotlib for publication-quality visualization

While leveraging these robust tools, FastMDAnalysis streamlines analysis for students, professionals, and researchers, especially those new to molecular dynamics. We thank the scientific Python community for their contributions to the ecosystem.