Metadata-Version: 2.4
Name: SOURSOP
Version: 2.0.7
Summary: Simulation analysis package for working with disordered proteins
Author-email: Alex Holehouse <alex.holehouse@wustl.edu>
License-Expression: LGPL-3.0-only
Project-URL: Homepage, https://github.com/holehouse-lab/soursop
Project-URL: Documentation, https://soursop.readthedocs.io
Project-URL: Repository, https://github.com/holehouse-lab/soursop
Project-URL: Issues, https://github.com/holehouse-lab/soursop/issues
Project-URL: Changelog, https://github.com/holehouse-lab/soursop/blob/master/CHANGELOG.md
Keywords: molecular dynamics,intrinsically disordered proteins,polymer physics,simulation analysis,biophysics,mdtraj
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.5.0
Requires-Dist: cython
Requires-Dist: mdtraj>=1.9.5
Requires-Dist: pandas>=0.23.0
Requires-Dist: threadpoolctl>=2.2.0
Requires-Dist: natsort
Requires-Dist: matplotlib
Provides-Extra: test
Requires-Dist: pytest>=6.1.2; extra == "test"
Dynamic: license-file

# SOURSOP

*A Python package for the analysis of simulations of intrinsically disordered and unfolded proteins.*

[![Build Status](https://github.com/holehouse-lab/soursop/actions/workflows/soursop-ci.yml/badge.svg?branch=master)](https://github.com/holehouse-lab/soursop/actions)
[![codecov](https://codecov.io/gh/holehouse-lab/soursop/branch/master/graph/badge.svg)](https://codecov.io/gh/holehouse-lab/soursop)
[![Documentation Status](https://readthedocs.org/projects/soursop/badge/?version=latest)](https://soursop.readthedocs.io/en/latest/?badge=latest)
[![PyPI version](https://img.shields.io/pypi/v/soursop.svg)](https://pypi.org/project/soursop/)
[![Python versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://pypi.org/project/soursop/)
[![License: LGPL v3](https://img.shields.io/badge/license-LGPLv3-blue.svg)](LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.1021%2Facs.jctc.3c00190-blue.svg)](https://doi.org/10.1021/acs.jctc.3c00190)
[![Last commit](https://img.shields.io/github/last-commit/holehouse-lab/soursop.svg)](https://github.com/holehouse-lab/soursop/commits/master)

---

## Overview

**SOURSOP** is a Python-based simulation analysis package built for the conformational analysis of intrinsically disordered regions (IDRs), unfolded states, and other flexible biopolymers. It builds on MDTraj, which handles trajectory I/O and low-level atomic representation, and adds an analysis layer of polymer-physics-aware observables designed specifically for disordered ensembles.

SOURSOP was originally developed by Jared Lalmansingh in the [Pappu lab](https://pappulab.wustl.edu/) and Alex Holehouse in the [Holehouse Lab](https://www.holehouselab.com/) at Washington University in St. Louis. Since its original release in 2023, we have substantially expanded and extended the codebase, and in the summer of 2026, SOURSOP 2.0 was released to minimal fanfare. SOURSOP 2.0 provides deep integrated support for ensemble reweighting, as well as improved performance and an expanded repertoire of analysis routines.

## Features

- **Global dimensions & shape** — radius of gyration, hydrodynamic radius, end-to-end distance, asphericity, acylindricity, prolateness, and the full gyration tensor.
- **Polymer scaling** — internal scaling profiles, the apparent scaling exponent ν (with bootstrap confidence intervals), and local scaling heterogeneity.
- **Distances & contacts** — inter-residue and inter-atomic distance maps, polymer-scaled distance maps, contact maps, and fraction of native contacts (*Q*).
- **Secondary structure** — per-frame DSSP assignments and BBSEG backbone-torsion classification.
- **Solvent accessibility** — per-residue, regional, and site-level SASA, with a dedicated path for one-bead-per-residue coarse-grained ensembles that uses the force field's own per-residue bead sizes (Mpipi, HPS, KH and friends) rather than atomic van der Waals radii.
- **NMR observables** — random-coil chemical shifts, ³J(HN, Hα) scalar couplings, NOE distances (`ssnmr`), and paramagnetic relaxation enhancement (`sspre`), computed by default with a coarse-grained spin-label cloud model (calibrated against DEER-PREdict) that works on all-atom and coarse-grained trajectories alike.
- **Ensemble reweighting** — a consistent, deterministic per-frame `weights` system across the package, with Bayesian Maximum Entropy (`ssbme`: BME / iBME/ BMECustom) and Convex Optimization for Ensemble Reweighting (`sscoper`: COPER / iCOPER) for reweighting ensembles against experimental data.
- **HDX protection factors** — Best–Vendruscolo ln(P) predictions (`sshdx`).
- **Sampling diagnostics** — convergence assessment of disordered-proteinensembles via PENGUIN (`sssampling`).
- **Multiple resolutions** — all-atom and one-bead-per-residue coarse-grained trajectories, with automatic detection.

## Installation

SOURSOP can be installed from PyPI with either `pip` or
[uv](https://docs.astral.sh/uv/):

```bash
pip install soursop
# or
uv pip install soursop
```

To install the latest development version directly from GitHub:

```bash
pip install "git+https://github.com/holehouse-lab/soursop.git"
```

Verify the installation with:

```bash
python -c "import soursop; print(soursop.__version__)"
```

Full installation instructions (conda, editable/source installs, and running the
tests) are in the [documentation](https://soursop.readthedocs.io/).

## Quickstart

```python
import numpy as np
from soursop.sstrajectory import SSTrajectory

# read in a trajectory (trajectory file + topology file)
traj = SSTrajectory('traj.xtc', 'start.pdb')

# extract the first protein chain (an SSProtein object)
protein = traj.proteinTrajectoryList[0]

# ensemble-average radius of gyration and end-to-end distance
rg  = np.mean(protein.get_radius_of_gyration())
ree = np.mean(protein.get_end_to_end_distance())

# ensemble-average inter-residue distance map
dmap = protein.get_distance_map()

print(f"Rg  = {rg:.2f} Å")
print(f"Ree = {ree:.2f} Å")
```

See the [worked examples](https://soursop.readthedocs.io/en/latest/usage/examples.html) in the documentation for end-to-end analyses.

## Documentation

Full documentation, including installation, tutorials, worked examples, and the complete API reference, is hosted at **[soursop.readthedocs.io](https://soursop.readthedocs.io/)**.

## Versioning and changelog

The current release is the **2.0.x** series, a large maintenance, performance, documentation, and feature release relative to the previous `0.2.7` line. It adds a consistent ensemble-reweighting (`weights`) system across the package,
two new modules for deriving frame weights from experimental data (`ssbme`: BME / iBME / BMECustom, and `sscoper`: COPER / iCOPER), new experimental forward-model observables (scalar `³J(HN, Hα)` couplings and NOE distances in `ssnmr`, plus HDX protection factors in the new `sshdx` module) — alongside wide-ranging bug fixes and behavior-preserving speed-ups. 

* **2.0.2** added a coarse-grained spin-label cloud model to the `sspre` PRE calculation and made it the default — a breaking change relative to the point-at-CB model of `2.0.1`
  (pass `use_label=False` to reproduce older profiles). 
* **2.0.3** makes multi-model PDB files load ~2x faster and fixes a batch of correctness bugs from a package-wide review (a few of which change numerical output — notably `get_local_to_global_correlation`, coarse-grained/`COM`-mode strided distance maps, `get_clusters`, and DSSP fractions at termini). 
* **2.0.4** adds first-class SASA support for one-bead-per-residue coarse-grained models, computed against each model's own bead sizes — a breaking change, in that SASA on a coarse-grained chain now requires the force field to be named (e.g.`forcefield='mpipi-gg'`) rather than silently treating every bead as a carbon atom. 
* **2.0.5** and **2.0.6** are correctness and documentation releases that include a slew of minor updates and corrections. 
* **2.0.7** is a TINY update so SOURSOP can read partially written XTC files.

The full, versioned changelog is in [CHANGELOG.md](CHANGELOG.md).

## Reporting bugs and requesting features

If you find a bug, typo, or error, [please raise an issue on GitHub](https://github.com/holehouse-lab/soursop/issues).

If you wish to add a new feature or contribute a plugin, please see the [development documentation](https://soursop.readthedocs.io/en/latest/usage/development.html).

## Citing SOURSOP

If you use SOURSOP in your work, please cite:

> Lalmansingh, J. M., Keeley, A. T., Ruff, K. M., Pappu, R. V. & Holehouse, A. S. **SOURSOP: A Python Package for the Analysis of Simulations of Intrinsically Disordered Proteins.** *J. Chem. Theory Comput.* **19**, 5609–5620 (2023). doi:[10.1021/acs.jctc.3c00190](https://doi.org/10.1021/acs.jctc.3c00190)

- [Journal link](https://pubs.acs.org/doi/full/10.1021/acs.jctc.3c00190)
- [Paper PDF](https://www.dropbox.com/s/bd5szapvxpn83r6/soursop_jctc.pdf?dl=0)

## License

SOURSOP is distributed under the GNU Lesser General Public License v3.0
(LGPLv3). See [LICENSE](LICENSE) for the full text.

Copyright © 2014–2026 Alex Holehouse and contributors.

## Acknowledgements

Project structure based on the [Computational Molecular Science Python Cookiecutter](https://github.com/molssi/cookiecutter-cms) version 1.0. SOURSOP was also supported via a [MOLSSI](https://molssi.org/) Computational Sciences postdoctoral fellowship to A.S.H.

