Input Formats

The input format is auto-detected from the file extension.

.gz inputs may hold several concatenated gzip members, as produced by cat a.gz b.gz or by bgzip (BGZF). All members are decompressed and joined, and the CRC32 and size of each member are verified. A .gz file with trailing bytes that are not a gzip member, including zero padding, is rejected as corrupt, and so is a file that ends inside a member, such as an incomplete download.

JSON Format#

Minimal JSON input with coordinates and radii:

{
  "x": [1.0, 2.0, 3.0],
  "y": [4.0, 5.0, 6.0],
  "z": [7.0, 8.0, 9.0],
  "r": [1.7, 1.55, 1.52]
}

Extended JSON with classification info (required for --classifier):

{
  "x": [1.0, 2.0, 3.0],
  "y": [4.0, 5.0, 6.0],
  "z": [7.0, 8.0, 9.0],
  "r": [1.7, 1.55, 1.52],
  "residue": ["ALA", "ALA", "ALA"],
  "atom_name": ["N", "CA", "C"],
  "element": [7, 6, 6]
}

Fields#

Values keep their JSON type: x, y, z, r and element hold JSON numbers, residue and atom_name hold strings. A number written as a string ("x": [0, "3"]) or an element given as a string ("element": "CN", or symbols such as ["C", "N"]) is rejected with ExpectedNumber, ExpectedArray, ExpectedString or InvalidElement instead of being converted. residue, atom_name and element may be null or left out. Unknown fields and repeated fields are errors.

Validation Rules#

• All arrays must have the same length
• Arrays cannot be empty
• Coordinates must be finite (no NaN or Inf)
• Radii must be positive and ≤ 100 Å

mmCIF Format#

Standard mmCIF files are supported. The parser extracts:

• _atom_site.Cartn_x/y/z - Coordinates
• _atom_site.type_symbol - Element (for VdW radius)
• _atom_site.label_atom_id / auth_atom_id - Atom name
• _atom_site.label_comp_id / auth_comp_id - Residue name
• _atom_site.label_asym_id / auth_asym_id - Chain ID
• _atom_site.label_seq_id / auth_seq_id - Residue number
• _atom_site.pdbx_PDB_ins_code - Insertion code
• _atom_site.pdbx_PDB_model_num - Model number
• _atom_site.label_alt_id and _atom_site.occupancy - Alternate location (see Alternate Locations)

Residue numbers come from label_seq_id. Non-polymer residues (waters, ligands, glycans) have no label_seq_id and are numbered by auth_seq_id, the number they have in the PDB-format file. With --auth-chain, every residue is numbered by auth_seq_id, so chain IDs, residue numbers and insertion codes together match the PDB-format file; a row without a usable auth_seq_id falls back to label_seq_id. A residue with neither value is numbered 0. BinaryCIF input follows the same rules.

BinaryCIF Format#

BinaryCIF input decodes _atom_site for SASA calculation (every decoded column needs a non-empty encoding list that ends in ByteArray or StringArray; a column with an empty list is rejected as InvalidColumnData instead of being read as raw bytes), follows the same alternate-location rules as mmCIF and PDB input, and uses embedded _chem_comp_atom / _chem_comp_bond inline CCD data when --classifier=ccd (or the ccd default) needs bond topology for non-standard compounds. You can still provide external CCD or SDF topology when the BinaryCIF file does not include component topology.

PDB Format#

Standard PDB format files are supported with ATOM and HETATM records. The alternate location indicator in column 17 is handled as described in Alternate Locations.

The element of each atom is read from columns 77-78. It decides which atoms are hydrogens (removed unless --include-hydrogens is given) and which generic radius an atom gets when the classifier has no entry for it. When those columns are blank or do not hold an element symbol (files written before the element column existed can carry an ID code and line number there), the element is inferred from the atom name in columns 13-16:

• An ion is a residue named after its atom: CA in residue CA is calcium, HG in residue HG is mercury.
• Otherwise the columns decide. A name that starts in column 14 is a one-letter element (CA is an alpha carbon, NA in a heme is nitrogen, HG is a hydrogen), and a name that starts in column 13 begins with a two-letter element (FE , ZN , CL1 , SE ).
• Four-character names fill column 13 whatever their element, so HG21 or HD11 is a hydrogen.

Some programs left-justify or center atom names instead (CA for an alpha carbon). zsasa detects such files and then relies on the names alone: a name starting with H, C, N, O, P or S is that element. In those files a metal or halogen inside a larger residue (CL1 in a ligand) cannot be told from carbon, so write the element column if you can.

Alternate Locations#

A structure can list several alternate locations (altlocs) for an atom, each with an altloc ID (A, B, ...) and an occupancy. --altloc=MODE chooses which of them are used. It applies to PDB, mmCIF and BinaryCIF input of calc and batch and to the topology of traj, with the same rules for every format. In a workflow file the setting is altloc under [calculation].

In every mode:

• Atoms without an altloc ID are always kept. With auto and highest-occupancy, alternates of an atom that is also listed without an altloc ID are dropped.
• Equal occupancies are a tie, and the alternate that comes first in the file is kept. This covers 0.50/0.50 pairs and files without occupancies, so exactly one alternate per atom survives.
• The other filters apply first. Altloc IDs on HETATM records or hydrogens only matter (also for none) when those atoms are included.

Microheterogeneity#

At some positions the alternates are different residues: residue 22 of 1EJG is PRO as altloc A and SER as altlocs B and C. Choosing an alternate for each atom name separately would keep atoms of both residues, so zsasa first keeps one residue per position (chain, residue number and insertion code):

• auto: the residue that has altloc A. Without an A, the residue with the highest occupancy.
• highest-occupancy: the residue with the highest occupancy.
• one ID: the residue that carries the ID.

The occupancy of a residue is the occupancy of its first atom with an altloc ID in the file, and on a tie the residue that comes first is kept. The alternate of each atom is then chosen within the surviving residue by the rules above. Atoms of the position without an altloc ID, such as a backbone N that both residues share, are kept under the residue name they have in the file.

SDF/MOL Format#

SDF and MOL files are supported for small-molecule SASA. V2000 and V3000 records are accepted (V3000 lines continued with a trailing - are joined), and batch mode expands multi-molecule SDF files so each molecule is calculated independently. Use --mol=NAME_OR_INDEX to select one molecule from a multi-molecule SDF.

The first line of a record is the molecule title. It may be blank, which is what RDKit writes for a molecule without a name; select such a molecule by its 1-based index. Blank lines after a $$$$ separator and at the end of the file are skipped.

Hydrogens are excluded unless --include-hydrogens is given. Deuterium and tritium atoms (symbols D and T) are hydrogens: they are excluded and included together with H atoms.

With the default ccd classifier, the radii of an SDF or MOL molecule are derived from its own bond table. The title plays no part in this: a molecule without a title, or with a title that is also a residue name such as ALA, is classified like any other, and every molecule of a file uses its own bond table. --sdf and --ccd describe the residues of PDB, mmCIF and BinaryCIF structures and are not consulted for SDF or MOL input.

SDF and MOL files do not name their atoms. zsasa names each atom of a molecule after its element and a per-element counter in file order (C1, C2, O1, Cl1); these names appear in CSV and other per-atom output. A name has at most four characters, so the counter continues in base 36 with a leading letter where decimal digits no longer fit: CA00 follows C999 and ClA0 follows Cl99.

In batch mode each molecule is named stem_title after the file stem and the molecule title, or stem_N when the title is blank; molecules of one file that share a title get their position appended (stem_title_N). See SDF and MOL Output Names for the full rules and the characters replaced in output file names.

Trajectory Formats#

For the traj subcommand, the following trajectory formats are supported:

A topology file (PDB or mmCIF) is required alongside the trajectory to provide atom names and radii classification.

Classifiers#

Built-in classifiers assign atom radii based on residue and atom names. See Classifiers for detailed documentation.

Built-in Classifiers#

Custom Config (--config=FILE)#

Custom classifiers are an advanced feature for studies that require a specific non-standard radius table. The CCD classifier remains the recommended default for most structures.

Custom classifier files must use TOML and the .toml extension.

TOML Format#

name = "my-classifier"

[types]
C_ALI = { radius = 1.87, class = "apolar" }
C_CAR = { radius = 1.76, class = "apolar" }
N     = { radius = 1.65, class = "polar" }
O     = { radius = 1.40, class = "polar" }
S     = { radius = 1.85, class = "apolar" }

[[atoms]]
residue = "ANY"
atom = "CA"
type = "C_ALI"

[[atoms]]
residue = "ALA"
atom = "CB"
type = "C_ALI"

• name - Classifier name (optional, default: "custom")
• [types] - Define atom types with radius (angstrom) and class ("polar" or "apolar")
• [[atoms]] - Map (residue, atom) pairs to defined types. Use "ANY" for fallback entries.

Migrating from legacy FreeSASA-style text#

Older custom classifier text files are no longer loaded directly. Convert each type row and atom mapping to TOML:

# Old FreeSASA-style text
C_ALI 1.87 apolar
ANY CA C_ALI

[types]
C_ALI = { radius = 1.87, class = "apolar" }

[[atoms]]
residue = "ANY"
atom = "CA"
type = "C_ALI"