afrc

The Analytical Flory Random Coil — a sequence-specific reference model for unfolded and intrinsically disordered proteins.

Overview

afrc implements the Analytical Flory Random Coil (AFRC): a closed-form, sequence-specific polymer model that reports the dimensions a polypeptide would adopt if it behaved as an ideal chain in a theta solvent (scaling exponent of 0.5, no finite-size effects). Given only an amino acid sequence, it instantly returns:

• mean end-to-end distance, radius of gyration and hydrodynamic radius (Kirkwood-Riseman or Nygaard et al.), plus the full end-to-end and radius of gyration distributions
• the mean distance and distance distribution between any pair of residues, as well as distance maps and internal scaling profiles
• inter-residue contact fractions and contact maps
• expected paramagnetic relaxation enhancement (PRE) profiles
• explicit 3D conformational ensembles (one bead per residue), written as PDB/XTC files - for the AFRC and every other model below

The AFRC is a reference (null) model, not a predictor of real dimensions. Real unfolded-state dimensions depend on sequence-encoded chain-chain and chain-solvent interactions that the AFRC deliberately omits. Deviations of a simulation or experiment from the AFRC therefore report directly on those interactions, and normalizing to the AFRC puts chains of different length and composition on a common footing.

The package also ships a family of classic analytical polymer models with a common interface, so you can compare one sequence against several reference models.

Installation

afrc requires Python 3.10 or later (tested through Python 3.14) and depends only on NumPy and SciPy.

pip install afrc

Writing 3D ensembles as XTC trajectories also needs mdtraj, which you can install alongside afrc:

pip install "afrc[ensemble]"

Quick start

from afrc import AnalyticalFRC

# create an AnalyticalFRC object from a sequence
P = AnalyticalFRC('MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDI')

# ensemble-average dimensions (Angstroms)
mean_rg  = P.get_mean_radius_of_gyration()
mean_e2e = P.get_mean_end_to_end_distance()
mean_rh  = P.get_mean_hydrodynamic_radius()

# full probability distributions, returned as (distances, probabilities)
rg_r,  rg_p  = P.get_radius_of_gyration_distribution()
re_r,  re_p  = P.get_end_to_end_distribution()

# distribution of the distance between two specific residues (indices start at 0)
d_r, d_p = P.get_interresidue_distance_distribution(4, 20)

# whole-chain maps
distance_map = P.get_distance_map()
contact_map  = P.get_contact_map(15.0)   # contact fractions at a 15 A threshold

# 5000 3D conformations drawn from the AFRC, written as ens.pdb + ens.xtc
# (the XTC needs mdtraj: pip install "afrc[ensemble]")
xyz = P.save_ensemble('ens', n=5000, seed=1)

Generating 3D ensembles

Every model can generate explicit 3D ensembles (one bead per residue). From the command line:

afrc-ensemble -s MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDI -n 5000 -o p53            # the AFRC
afrc-ensemble -s MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDI -m wlc --lp 4 -o p53_wlc  # a worm-like chain

This writes p53.pdb and p53.xtc (use --pdb-only for a single multi-model PDB instead) and a report, p53_report.txt, that checks the ensemble reproduces the model's statistics - radius of gyration, end-to-end distance, inter-residue distances and, where the model fixes them, bond lengths and angles - to within sampling error. The AFRC, freely jointed chain and freely rotating chain ensembles are exact, and the worm-like chain ensembles match the exact chain to within 0.02%; the SAW and nu-dependent SAW ensembles are a Gaussian approximation with the right mean-squared distances. Run afrc-ensemble --help for all the models and options. Writing XTC files needs mdtraj (pip install "afrc[ensemble]"). From Python, every model has sample_conformations(), save_ensemble() and check_ensemble().

Polymer models included

Every model takes an amino acid sequence and exposes a common interface (get_end_to_end_distribution, get_mean_end_to_end_distance, ...), so they can be swapped in and compared directly.

The full mathematical formalism, parameters and usage examples for each model are in the documentation.

Google Colab

Use the AFRC (and the other polymer models) directly in a Google Colab notebook.

Documentation

Full documentation — a theory section (formalism, parameters, references) and an application section (usage examples and code reference) for every model — is hosted at afrc.readthedocs.io. Worked, plotted examples for each model are in the demo/ directory, and the release history is in changelog.md.

Citation

If you use the AFRC in your work, please cite:

Alston, J. J., Ginell, G. M., Soranno, A., & Holehouse, A. S. (2023). The Analytical Flory Random Coil is a simple-to-use reference model for unfolded and disordered proteins. The Journal of Physical Chemistry B, 127(21), 4746–4760. https://doi.org/10.1021/acs.jpcb.3c01619

Help and contributing

If you find a bug or have a feature request, please open an issue on GitHub. To run the test suite, install from a clone of the repository with the test extras (pip install -e ".[test]") and run pytest.

Authors

The AFRC was developed by Garrett Ginell, Jhullian Alston, and Alex Holehouse in the Holehouse Lab.

License

Distributed by the Holehouse Lab under the GNU Lesser General Public License (LGPL v3).

References

• Alston, J. J., Ginell, G. M., Soranno, A., & Holehouse, A. S. (2023). The Analytical Flory Random Coil is a simple-to-use reference model for unfolded and disordered proteins. J. Phys. Chem. B, 127(21), 4746–4760.
• Flory, P. J. (1969). Statistical Mechanics of Chain Molecules. Wiley-Interscience.
• Mao, A. H., Lyle, N., & Pappu, R. V. (2013). Describing sequence–ensemble relationships for intrinsically disordered proteins. Biochemical Journal, 449(2), 307–318.