Docs v0.11.0 GitHub

ReferenceClassifier API

Classifier API

Atom classification and RSA calculation.

ClassifierType#

python
class ClassifierType(IntEnum):
    NACCESS = 0  # NACCESS-compatible radii
    PROTOR = 1   # Static ProtOr-compatible radii
    OONS = 2     # OONS radii
    CCD = 3      # CCD-based radii (default)

PROTOR is a separate value, not an alias of CCD: it selects the static ProtOr-compatible table without any CCD resource parsing.

CCD does less in Python than in the CLI. Everything that goes through the C classify API (get_radius, get_atom_class, classify_atoms, and the gemmi, BioPython and Biotite integrations built on them) looks atoms up in the built-in ProtOr table only, so it gives CCD and PROTOR the same radii. There is no bond-topology analysis of components that are not in the table: their atoms get a NaN radius (None from get_radius) and class UNKNOWN, and the integrations then use the element's radius. The bond-topology analysis of ligands and modified residues runs in the CLI (inline _chem_comp_bond data of an mmCIF file, SDF bonds or --ccd) and in process_directory (inline mmCIF data and SDF bonds; it cannot take an external dictionary). With a structure that has HETATM ligands, the integrations can therefore give a different total than zsasa calc with --classifier=ccd.

AtomClass#

python
class AtomClass(IntEnum):
    POLAR = 0    # Polar atoms (N, O, etc.)
    APOLAR = 1   # Apolar atoms (C, etc.)
    UNKNOWN = 2  # Unknown classification

classify_atoms#

python
def classify_atoms(
    residues: list[str],
    atoms: list[str],
    classifier_type: ClassifierType = ClassifierType.CCD,
    *,
    include_classes: bool = True,
) -> ClassificationResult

Classify multiple atoms at once (batch operation).

Parameters:

Parameter Type Default Description
residues list[str] required Residue names (e.g., ["ALA", "GLY"])
atoms list[str] required Atom names (e.g., ["CA", "N"])
classifier_type ClassifierType CCD Classifier to use
include_classes bool True Whether to compute atom classes

Returns: ClassificationResult

Example:

python
from zsasa import classify_atoms, ClassifierType

result = classify_atoms(
    ["ALA", "ALA", "GLY"],
    ["CA", "O", "N"],
    ClassifierType.CCD
)
print(result.radii)   # [1.88 1.42 1.64]
print(result.classes) # [1 0 0] (APOLAR, POLAR, POLAR)

The values above are the CCD (ProtOr) radii. With ClassifierType.NACCESS the same atoms give [1.87 1.4 1.65].

ClassificationResult#

python
@dataclass
class ClassificationResult:
    radii: NDArray[float64]  # Per-atom radii (NaN for unknown)
    classes: NDArray[int32]  # Per-atom polarity classes

Utility Functions#

Function Description
get_radius(residue, atom, classifier_type=ClassifierType.CCD) Get radius for a specific atom, or None if the classifier does not know it
get_atom_class(residue, atom, classifier_type=ClassifierType.CCD) Get polarity class for an atom
guess_radius(element) Guess radius from element symbol
guess_radius_from_atom_name(atom_name) Guess radius from a column-padded PDB atom name (" CA " is carbon, "CA " is calcium)

classify_atoms and get_radius take no element. With NACCESS and OONS, atoms outside the tables (hydrogens, ligands) have class UNKNOWN and a radius guessed from the residue and atom names; see Handling Unknown Atoms. When you know the element, use guess_radius(element) for those atoms, as the structure-library integrations do.

RSA API

Relative Solvent Accessibility calculation.

MAX_SASA#

Reference maximum SASA values from Tien et al. (2013):

python
MAX_SASA = {
    "ALA": 129.0, "ARG": 274.0, "ASN": 195.0, "ASP": 193.0,
    "CYS": 167.0, "GLN": 225.0, "GLU": 223.0, "GLY": 104.0,
    "HIS": 224.0, "ILE": 197.0, "LEU": 201.0, "LYS": 236.0,
    "MET": 224.0, "PHE": 240.0, "PRO": 159.0, "SER": 155.0,
    "THR": 172.0, "TRP": 285.0, "TYR": 263.0, "VAL": 174.0,
}

calculate_rsa#

python
def calculate_rsa(sasa: float, residue_name: str) -> float | None

Calculate Relative Solvent Accessibility (RSA = SASA / MaxSASA).

Returns: RSA value (0.0-1.0+), or None for non-standard amino acids.

Example:

python
from zsasa import calculate_rsa

rsa = calculate_rsa(64.5, "ALA")  # 64.5 / 129.0 = 0.5

calculate_rsa_batch#

python
def calculate_rsa_batch(
    sasas: NDArray[float64] | list[float],
    residue_names: list[str],
) -> NDArray[float64]

Batch RSA calculation. Returns NaN for non-standard amino acids.

get_max_sasa#

python
def get_max_sasa(residue_name: str) -> float | None

Get maximum SASA reference value for a residue.

Edit this page