Choosing CLI vs Python

zsasa provides two main interfaces. The right choice depends on your input data and workflow.

Decision Guide#

CLI: Pre-processed Structures#

The CLI works best with clean, simple structures that need no pre-processing:

• AlphaFold/ESMFold predicted structures (single model, protein only)
• Pre-cleaned PDB/mmCIF files
• Batch processing of many files

# Single structure
zsasa calc structure.cif output.json

# With classifier
zsasa calc --classifier=naccess structure.cif output.json

# Batch: process all files in a directory
zsasa batch structures/ results/

For repeated batch analyses with shared settings or named chain-complex jobs, prefer Workflow Files. Workflow TOML files keep calculation, output, classifier, and per-job settings together so analyses are easier to rerun and review.

The CLI supports basic filtering (--chain, --model for calc, --altloc, --include-hetatm, --include-hydrogens), but has limitations:

• Altloc — one rule for the whole file: --altloc keeps altloc A or the highest occupancy (auto, the default), the highest occupancy, one altloc ID, or every alternate (see Alternate Locations). There is no per-residue choice
• HETATM — all-or-nothing (--include-hetatm), no granular control (e.g., keep ligands but remove waters)
• No programmatic control — cannot combine with other analysis libraries

Python Integrations: Structure Processing Required#

Use Python integrations when your structures need pre-processing or you're combining zsasa with other analysis tools.

Structure pre-processing (Gemmi, BioPython, Biotite)#

These integrations parse structure files through their respective libraries, which handle:

• Altloc selection — choose specific conformers by editing the structure before the calculation (see Alternate locations for what each integration does by default)
• HETATM filtering — include/exclude ligands, waters, ions
• Model selection — pick specific models from NMR ensembles
• Chain/residue selection — analyze specific parts of a structure

from zsasa.integrations.gemmi import calculate_sasa_from_structure

# Basic usage (polymer atoms only; HETATM and hydrogens are excluded by default)
result = calculate_sasa_from_structure("complex.cif")

# Include ligands, ions and waters
result = calculate_sasa_from_structure(
    "complex.cif",
    include_hetatm=True,
)

MD trajectory analysis (MDAnalysis, MDTraj)#

For molecular dynamics trajectories with atom selections:

import MDAnalysis as mda
from zsasa.mdanalysis import SASAAnalysis

u = mda.Universe("topology.pdb", "trajectory.xtc")
sasa = SASAAnalysis(u, select="protein and not resname HOH")
sasa.run()

Combining with other tools#

When zsasa is part of a larger analysis pipeline:

import gemmi
from zsasa.integrations.gemmi import calculate_sasa_from_model

# Load and manipulate structure with Gemmi
st = gemmi.read_structure("complex.cif")
st.remove_ligands_and_waters()

# Then calculate SASA
result = calculate_sasa_from_model(st[0])

Quick Reference#

Available Integrations#