Trajectory Analysis

zsasa supports SASA calculation over MD trajectory frames using the CLI or Python bindings.

Supported trajectory formats:

• XTC (GROMACS) — compressed trajectory
• TRR (GROMACS) — full-precision trajectory with coordinates
• DCD (NAMD/CHARMM) — uncompressed trajectory
• AMBER NetCDF (.nc, .ncdf) — AMBER convention NetCDF trajectory

Coordinates are normalized to Å internally by the ztraj readers before SASA calculation.

Format is auto-detected from file extension.

CLI: traj Subcommand#

zsasa traj <trajectory> <topology> [OPTIONS]

The topology file (PDB or mmCIF) provides atom names and radii. See Topology Requirements for how it has to match the trajectory.

Example#

# XTC trajectory
zsasa traj trajectory.xtc topology.pdb

# DCD trajectory (NAMD/CHARMM)
zsasa traj trajectory.dcd topology.pdb

# TRR trajectory (GROMACS)
zsasa traj trajectory.trr topology.pdb

# AMBER NetCDF trajectory
zsasa traj trajectory.nc topology.pdb

# With classifier and frame selection
zsasa traj trajectory.xtc topology.pdb \
    --classifier=naccess \
    --stride=10 \
    --start=100 --end=500

# Exclude hydrogens (included by default)
zsasa traj trajectory.xtc topology.pdb --no-hydrogens

# Lee-Richards instead of Shrake-Rupley
zsasa traj trajectory.xtc topology.pdb --algorithm=lr --n-slices=50

# Output to specific file
zsasa traj trajectory.xtc topology.pdb -o sasa_results.csv

Options#

--algorithm and --precision are independent: Lee-Richards runs at f32 by default and at f64 with --precision=f64. See Commands & Options for the full list.

Output Format#

CSV with per-frame total SASA:

frame,step,time,total_sasa
0,1,1.000,1840.88
1,2,2.000,1944.47
2,3,3.000,1848.46

These are the first frames of test_data/1l2y.xtc with test_data/1l2y.pdb as topology, at the defaults (NACCESS classifier, 100 test points, f32).

Topology Requirements#

The topology must describe exactly the atoms stored in the trajectory, in the same order. zsasa reads every ATOM and HETATM record of the first model of the topology file and compares the atom count with the trajectory before any frame is processed.

• A multi-model file (for example an NMR ensemble) can be used directly; only its first model is the topology.
• Solvent, ions and ligands that are part of the trajectory must be listed in the topology, and they are part of the reported SASA. To restrict the calculation to a subset, write a trajectory and topology that contain only those atoms, or use the MDAnalysis integration with a selection.
• For residues the classifier does not know, radii fall back to generic atom-name or element-based values, as in calc.
• --altloc selects which alternate locations of a PDB or mmCIF topology are kept (default auto, one per atom). The trajectory must hold the atoms that remain.

Hydrogens#

Hydrogens are included by default, because MD trajectories carry explicit hydrogens and the default naccess classifier has radii for them. --no-hydrogens removes the hydrogen atoms of the topology and skips their coordinates in every frame, so it works on a normal all-atom trajectory: the trajectory and the topology still have to contain the same atoms, hydrogens included. If the trajectory has already been stripped of hydrogens, pass a hydrogen-free topology and leave the option out.

Failures#

All options are checked before the output file is created, so a rejected command never overwrites an existing results file. If reading or calculating a frame fails, zsasa writes the frames completed before it, reports the error and exits with a non-zero status.

Python: MDAnalysis Integration#

import MDAnalysis as mda
from zsasa.mdanalysis import SASAAnalysis

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

print(f"Mean SASA: {sasa.results.mean_total_area:.2f} Ų")
print(f"Per-frame: {sasa.results.total_area}")

See MDAnalysis Integration for full API details.

Python: MDTraj Integration#

import mdtraj as md
from zsasa.mdtraj import compute_sasa

traj = md.load("trajectory.xtc", top="topology.pdb")
sasa = compute_sasa(traj)  # returns (n_frames, n_atoms) array

A drop-in replacement for mdtraj.shrake_rupley().

See MDTraj Integration for full API details.

Python: Direct Trajectory I/O with pyztraj#

For Python workflows that read trajectory files directly, use pyztraj. pyztraj centralizes trajectory I/O and trajectory-native analysis for XTC, TRR, DCD, and AMBER NetCDF. zsasa keeps zsasa.xtc and zsasa.dcd for compatibility, but new trajectory formats are handled in pyztraj.

import pyztraj

structure = pyztraj.load_pdb("topology.pdb")
with pyztraj.open_trr("trajectory.trr", structure.n_atoms) as reader:
    for frame in reader:
        sasa = pyztraj.compute_sasa(structure, frame.coords)
        print(frame.step, sasa.total_area)

See Legacy Native XTC Reader for the compatibility XTC API.

Choosing an Approach#