Welcome to the SOURSOP Documentation!

Version 2.0.3 (released July 2026)

SOURSOP (Simulation analysis Of Unfolded RegionS Of Proteins) is a Python package for the analysis of all-atom and coarse-grained simulations of unfolded and disordered proteins. It provides a wide range of functionality that may not be relevant for folded proteins but is essential for extracting polymer-physics insight from simulations of intrinsically disordered proteins (IDPs) and intrinsically disordered regions (IDRs). SOURSOP was formerly CAMPARITraj, which was formerly CTraj, and includes all the original functionality therein.

The SOURSOP GitHub page can be accessed here: https://github.com/holehouse-lab/soursop.

SOURSOP was built with the CAMPARI simulation engine in mind, but has been successfully tested on a wide range of trajectories generated by different software packages. It uses the mdtraj (https://mdtraj.org) backend for trajectory reading and representation, and focusses on analysis routines for characterizing ensembles of disordered and unfolded proteins through the lens of polymer physics. It works for both all-atom and one-bead-per-residue coarse-grained ensembles.

Why SOURSOP?

Most molecular-simulation analysis tools are oriented towards folded proteins (RMSD to a native state, secondary-structure stability, binding-pocket geometry). Disordered proteins have no single reference structure, so the questions - and the right observables - are different. SOURSOP focusses on the ensemble- and polymer-centric quantities that are meaningful for IDPs/IDRs:

  • Global dimensions - radius of gyration, hydrodynamic radius, end-to-end distance, asphericity, the gyration tensor, and the dimensionless size parameter \(\langle t \rangle\).

  • Polymer scaling - internal-scaling profiles, apparent scaling exponents (with frame-level bootstrap confidence intervals and a reduced-\(\chi^2\) fit-quality estimate), and homopolymer-deviation maps.

  • Distance & contact maps - mean / RMS inter-residue distance maps and fractional contact maps, including fast inter-chain maps for multi-chain systems.

  • Local structure - DSSP and BBSEG2 secondary structure, dihedral angles and dihedral mutual information, sliding-window local heterogeneity and local collapse.

  • Solvent exposure - per-residue / per-atom / sidechain / backbone SASA and regional accessibility.

  • NMR & PRE observables - sequence-corrected random-coil chemical shifts, backbone ³J(HN, Hα) scalar couplings, and per-frame NOE distances (ssnmr), plus synthetic paramagnetic relaxation enhancement profiles (sspre) — computed by default with a coarse-grained spin-label cloud model calibrated against DEER-PREdict — for direct comparison with experiment.

  • HDX protection factors - per-residue Best-Vendruscolo ln(P) from heavy-atom contacts and backbone H-bonds (sshdx), ready for reweighting against experimental HDX data.

  • Sampling quality - assessment of ensemble convergence via the PENGUIN tools in sssampling.

  • Ensemble reweighting - every ensemble-average observable accepts an optional per-frame weights vector, applied consistently and deterministically, for re-weighted / enhanced-sampling / maximum-entropy ensembles (see Ensemble reweighting (frame weights)). Weights can be derived directly from experimental data by Bayesian Maximum Entropy / iterative BME (see ssbme) or by COPER / iterative COPER (see sscoper) reweighting.

In addition to the pre-built analyses, SOURSOP gives easy and rapid access to all inter-residue and inter-atomic distances, so custom observables are straightforward to build.

Quickstart

pip install soursop          # or:  uv pip install soursop

from soursop.sstrajectory import SSTrajectory

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

# each protein chain is an SSProtein object
protein = traj.proteinTrajectoryList[0]

# per-frame radius of gyration, and the ensemble mean
rg = protein.get_radius_of_gyration()
print(rg.mean())

# a re-weighted ensemble average (e.g. from an MSM / MaxEnt reweighting)
rg_reweighted = protein.get_radius_of_gyration(weights=my_weights)

# mean inter-residue distance map and a contact map
dmap, dstd = protein.get_distance_map()
cmap, corder = protein.get_contact_map()

See Overview for the core concepts (SSTrajectory vs. SSProtein, multi-chain systems) and Examples for eleven worked, end-to-end IDP analyses.

Documentation map

Contents:

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. (2023). doi:10.1021/acs.jctc.3c00190.

Reporting bugs & requesting features

Please report bugs, typos, or unexpected behaviour on the GitHub issue tracker. Contributions are welcome - see Development for the plugin workflow and contribution guidelines.

Release notes

Release notes and the full, versioned changelog are maintained in CHANGELOG.md on GitHub.

About

SOURSOP was built by Jared Lalmansingh (Pappu lab) and Alex Holehouse. Its development was supported financially and intellectually by the Molecular Sciences Software Institute (MOLSSI). It was also supported by NSF grant no. 2128068 to Alex, and we thank members of the Water and Life Interface Institute (WALII), supported by NSF DBI grant #2213983, for helpful discussions.