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.

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

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

Options

Option	Description	Default
--stride=N	Process every Nth frame	1
--start=N	Start from frame N	0
--end=N	End at frame N	all
--classifier=TYPE	ccd, naccess, protor, oons	naccess
--threads=N	Thread count (0 = auto)	0
--precision=P	f32 (fast) or f64 (precise)	f32
--no-hydrogens	Exclude hydrogen atoms	included
--batch-size=N	Frames per batch (omit for auto)	auto
-o, --output=FILE	Output CSV file	traj_sasa.csv

Output Format

CSV with per-frame total SASA:

frame,step,time,total_sasa
0,1,1.000,1866.44
1,2,2.000,1977.96
2,3,3.000,1884.93

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

Approach	Best For	Formats	Dependencies
CLI traj	Quick analysis, scripting	XTC, TRR, DCD, AMBER NetCDF	None (Zig binary)
MDAnalysis	Complex selections, multi-format	XTC, DCD, + many more	MDAnalysis
MDTraj	Drop-in replacement for mdtraj.shrake_rupley	XTC, DCD, + many more	mdtraj
pyztraj	Direct trajectory-file I/O and trajectory-native analysis	XTC, TRR, DCD, AMBER NetCDF	pyztraj
Legacy zsasa.xtc/zsasa.dcd	Existing compatibility code	XTC, DCD	None