Metadata-Version: 2.4
Name: fastmdanalysis
Version: 0.0.3
Summary: Software for automated MD trajectory analysis
Project-URL: Repository, https://github.com/aai-research-lab/FastMDAnalysis
Project-URL: Documentation, https://fastmdanalysis.readthedocs.io
Project-URL: Issues, https://github.com/aai-research-lab/FastMDAnalysis/issues
Author-email: Adekunle Aina <kunleaina@gmail.com>
License: MIT License
        
        Copyright (c) 2025 A:Ai Research Lab
        
        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.
License-File: LICENSE
Keywords: molecular dynamics,trajectory analysis
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: cairosvg>=2.7
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: mdtraj>=1.9.7
Requires-Dist: numpy>=1.21.0
Requires-Dist: pillow>=10.0
Requires-Dist: python-pptx>=0.6.21
Requires-Dist: pyyaml>=6.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: scipy>=1.10
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

![FastMDAnalysis Banner](assets/fastmdanalysis_banner.png)

[![Tests](https://github.com/aai-research-lab/FastMDAnalysis/actions/workflows/test.yml/badge.svg)](https://github.com/aai-research-lab/FastMDAnalysis/actions)
[![Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://fastmdanalysis.readthedocs.io/en/latest/)
[![Documentation](https://readthedocs.org/projects/fastmdanalysis/badge/?version=latest)](https://fastmdanalysis.readthedocs.io)
[![PyPI](https://img.shields.io/pypi/v/fastmdanalysis)](https://pypi.org/project/fastmdanalysis/)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
<!--[![codecov](https://codecov.io/gh/aai-research-lab/FastMDAnalysis/branch/main/graph/badge.svg)](https://codecov.io/gh/aai-research-lab/FastMDAnalysis)-->
---
# 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

<!-- Perform a variety of MD trajectory analyses with a single line of code -->
<!-- Simplify your workflow by loading a trajectory once (with options for frame and atom selection) and then performing multiple analyses without repeating input file details. --> 
<!--  Automatically generate publication-quality figures (with options for customization) -->
<!--  Use the Python API or the Command‐Line Interface (CLI) -->



# 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
<!-- ## From PyPI (Recommended for users) -->
**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):
```bash
# 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:
```bash
# 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**
```bash
fastmda analyze -traj path/to/trajectory -top path/to/topology
```
**Include specific analyses**
```bash
fastmda analyze -traj traj.dcd -top top.pdb --include rmsd rg
```
**Exclude specific analyses**
```bash
fastmda analyze -traj traj.dcd -top top.pdb --exclude sasa dimred cluster
```
**Supply options via file (YAML or JSON)**
```bash
fastmda analyze -traj traj.dcd -top top.pdb --options options.yaml
```
**Create a slide deck from generated figures**
```bash
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:
```yaml
# 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)**
```bash
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.**
```python
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**
```python
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**
```python
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](https://fastmdanalysis.readthedocs.io).


# Contributing
Contributions are welcome. Please submit a Pull Request. 

**Development Installation**

If you want to contribute or modify the code:
```bash
# 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

```bibtex
@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.


