aggrescan3d/aggrescan/__init__.py

"""Module for simple AGGRESCAN3D method."""

from __future__ import annotations
import pathlib
from aggrescan import analysis
from aggrescan.aggrescan_3d import Residue


def run_aggrescan3d(
    structure_path: str,
    distance: float = 10,
) -> list[Residue]:
    """Run AGGRESCAN3D on the input structure.

    Args:
        structure_path: Path to pdb structure.
        distance: Radius around the central atom within which atoms are included in the
        aggrescan3d score calculation.

    Returns:
        List of aggrescan3D `Residue` objects.
        `Residue` objects have the following attributes:
        - chain: Chain ID.
        - rsa: Relative surface area. Value in range [0, 100].
        - score: Aggrescan3D score.
        - resi: Residue index.
        - resn: One letter residue type.
        - coords: Tuple of (x, y, z) coordinates.

    """
    struct_path = pathlib.Path(structure_path)
    # Check if structure exists. If it doesn't, it only gets caught by freeSASA and it
    # throws a confusing error message.
    if not struct_path.exists():
        raise RuntimeError(f"Structure '{structure_path}' does not exist.")
    config = {
        "distance": distance,
        "naccess": False,
        "ph": False,
    }
    analysis._run_free_sasa(target=structure_path, agg=".")
    residues: list[Residue] = analysis._run_aggrescan(
        target=structure_path, working_dir=".", config=config,
    )
    return residues