pdb-legacy

name	pdb-legacy
description	Understanding the legacy Protein Data Bank (PDB) fixed-column text format for macromolecular structures, its record types, and how it relates to the modern PDBx/mmCIF format. Use this together with the mmcif skill when implementing a NEP reader for protein structure files.
metadata	{"author":"netcdf-analysis","version":"1.0","date":"2026-07-29"}

Legacy PDB Format Skill

This skill covers the legacy Protein Data Bank (PDB) fixed-column text format used to distribute experimentally determined macromolecular structures (proteins, nucleic acids, and their complexes) prior to the wwPDB's move to PDBx/mmCIF as the master format.

For NEP purposes, this skill is background for a read-only reader: it explains what a .pdb/.ent file contains and how those contents map onto the same NetCDF model used by the mmcif skill, so that a single dispatch implementation can share code between the two formats where practical (they describe the same underlying data model).

Overview

The PDB format was introduced in 1976 by the Brookhaven National Laboratory and is now maintained by the Worldwide Protein Data Bank (wwPDB, https://www.wwpdb.org/). Since 2014 the wwPDB no longer accepts new depositions in this format and instead treats PDBx/mmCIF as the canonical archive format; legacy PDB files for new/updated large or complex structures may be incomplete or unavailable (files with more than 62 chains, or using multi-character chain/residue identifiers, cannot be represented at all in legacy PDB columns). PDB format files remain widely used by older software and are still generated by the PDB archive as a derived format for structures that fit within its constraints.

Format documentation: wwPDB Format Version 3.30, https://files.wwpdb.org/pub/pdb/doc/format_descriptions/Format_v33_A4.pdf

File Structure

A PDB file is plain ASCII text, one record per line, up to 80 columns. The first six columns (left-justified, blank-padded) hold the record name, which is an exact match against a fixed vocabulary (ATOM, HETATM, HEADER, SEQRES, ...). Records fall into six sections that must appear in a fixed relative order when present:

Title section        HEADER, OBSLTE, TITLE, SPLIT, CAVEAT, COMPND,
                      SOURCE, KEYWDS, EXPDTA, NUMMDL, MDLTYP, AUTHOR,
                      REVDAT, SPRSDE, JRNL, REMARK
Primary structure     DBREF, DBREF1/2, SEQADV, SEQRES, MODRES
Heterogen section      HET, HETNAM, HETSYN, FORMUL
Secondary structure   HELIX, SHEET
Connectivity annotation SSBOND, LINK, CISPEP
Miscellaneous features SITE
Crystallographic/coordinate transformation
                      CRYST1, ORIGX1-3, SCALE1-3, MTRIX1-3
Coordinate section    MODEL, ATOM, ANISOU, TER, HETATM, ENDMDL
Connectivity           CONECT
Bookkeeping           MASTER, END

Only CRYST1, ORIGXn, SCALEn, and END are unconditionally mandatory; most others are "mandatory if" a condition applies (e.g. SEQRES is mandatory if ATOM records exist).

Key Records for a Structure Reader

HEADER / TITLE / COMPND / SOURCE

Record	Columns	Field	Notes
HEADER	11-50	classification	Function classification
HEADER	51-59	depDate	Deposition date DD-MMM-YY
HEADER	63-66	idCode	4-character PDB ID
TITLE	11-80 (continued)	title	Free-text description
COMPND	11-80	compound	Molecule name, chain IDs, EC number (token=value pairs)
SOURCE	11-80	srcName	Organism scientific/common name, strain, etc.

CRYST1 — Unit Cell

COLUMNS  DATA TYPE     FIELD          DEFINITION
1 - 6    Record name   "CRYST1"
7 - 15   Real(9.3)     a              Unit cell length a (Å)
16 - 24  Real(9.3)     b              Unit cell length b (Å)
25 - 33  Real(9.3)     c              Unit cell length c (Å)
34 - 40  Real(7.2)     alpha          Unit cell angle alpha (deg)
41 - 47  Real(7.2)     beta           Unit cell angle beta (deg)
48 - 54  Real(7.2)     gamma          Unit cell angle gamma (deg)
56 - 66  LString       sGroup         Space group
67 - 70  Integer       z              Z value

SEQRES — Polymer Sequence

COLUMNS  DATA TYPE     FIELD          DEFINITION
1 - 6    Record name   "SEQRES"
8 - 10   Integer       serNum         Serial number of this SEQRES line for this chain
12       Character     chainID        Chain identifier
14 - 17  Integer       numRes         Number of residues in the chain
20 - 22, 24-26, ...     resName(1..13) Residue names (up to 13 per line), 3-letter codes

ATOM / HETATM — Coordinates

COLUMNS  DATA TYPE       FIELD        DEFINITION
1 - 6    Record name     "ATOM  "/"HETATM"
7 - 11   Integer         serial       Atom serial number
13 - 16  Atom            name         Atom name
17       Character       altLoc       Alternate location indicator
18 - 20  Residue name    resName      Residue name (3-letter code)
22       Character       chainID      Chain identifier (single character)
23 - 26  Integer         resSeq       Residue sequence number
27       AChar           iCode        Insertion code
31 - 38  Real(8.3)       x            Orthogonal X coordinate (Å)
39 - 46  Real(8.3)       y            Orthogonal Y coordinate (Å)
47 - 54  Real(8.3)       z            Orthogonal Z coordinate (Å)
55 - 60  Real(6.2)       occupancy    Occupancy
61 - 66  Real(6.2)       tempFactor   Isotropic B-factor
73 - 76  LString(4)      segID        Segment identifier (legacy, optional)
77 - 78  LString(2)      element      Element symbol, right-justified
79 - 80  LString(2)      charge       Charge on the atom (e.g. "2+")

HETATM uses the same column layout as ATOM but flags non-standard groups (ligands, ions, water) that are not part of the standard polymer chemical dictionary.

MODEL / ENDMDL

Used for NMR ensembles or multi-model files. MODEL (cols 11-14, integer serial number) opens a model; ENDMDL closes it. All ATOM/HETATM records between them belong to that model.

TER

Marks the end of a chain's coordinate records. Same column layout as ATOM for serial, resName, chainID, resSeq, iCode but no coordinate fields.

ANISOU — Anisotropic Displacement

Same serial/name/chainID/resSeq columns as ATOM, followed by six integers (cols 29-70) for U(1,1) U(2,2) U(3,3) U(1,2) U(1,3) U(2,3), scaled by 10^4 Ų.

CONECT — Explicit Bonds

COLUMNS  DATA TYPE     FIELD
1 - 6    Record name   "CONECT"
7 - 11   Integer       serial number of source atom
12-16,17-21,22-26,27-31  Integer  serial numbers of up to 4 bonded atoms

Coordinate Precision and Limits

• Real coordinate fields have fixed width Real(8.3): 3 decimal digits, limiting precision to 0.001 Å and magnitude to under 10,000 Å.
• chainID is a single character: at most ~62 distinct chains (A-Z, a-z, 0-9) can be represented; this is the main reason large assemblies cannot be losslessly expressed in legacy PDB format (PDBx/mmCIF allows arbitrary-length identifiers).
• resSeq is a 4-digit integer (max 9999) with a 1-character iCode for overflow/insertions.
• Atom serial numbers (ATOM/HETATM/CONECT) are limited to 5 digits (99999); very large structures wrap or switch to hybrid-36 encoding.

Mapping Legacy PDB to the NetCDF Model

This mirrors the mmcif skill's mapping so both formats can drive the same reader-side abstraction:

• Dimensions:
  • model = number of MODEL...ENDMDL blocks (or 1 if absent)
  • atom = number of ATOM/HETATM records per model
  • chain = number of distinct chainID values (derived, not stored directly)
• Coordinate variable: atom_site_Cartn_x/y/z (or a combined [model][atom][3] variable), NC_FLOAT, shape [model][atom] or [model][atom][3].
• Per-atom 1-D variables (dimension [atom], constant across models unless noted): atom_site_id (serial), atom_site_label_atom_id (name), atom_site_label_comp_id (resName), atom_site_auth_asym_id (chainID), atom_site_auth_seq_id (resSeq), atom_site_occupancy, atom_site_B_iso_or_equiv (tempFactor), atom_site_type_symbol (element), atom_site_group_PDB (ATOM/HETATM).
• Global attributes (strings): idCode (from HEADER), title (concatenated TITLE continuation lines), classification, depDate, compnd, source, keywds, expdta.
• Unit cell global attributes: cell_length_a/b/c, cell_angle_alpha/beta/gamma (from CRYST1), space_group_name_H-M (from CRYST1 sGroup field), symmetry_Z (from CRYST1 z field).
• sequence group or variables (from SEQRES): a residue dimension per chain, with a mon_id string variable listing the 3-letter residue codes in order.

Field-width parsing is fixed-column: read exactly the columns specified above (1-indexed, inclusive) rather than splitting on whitespace, since some fields (e.g. resName right-justified in 18-20) can abut adjacent fields without a separating space, and atom names have leading-space conventions relevant to element-symbol alignment.

Relationship to PDBx/mmCIF

Every legacy PDB record type has an approximate PDBx/mmCIF category equivalent; see the mapping table in the mmcif skill (Legacy PDB format records column). In general:

• One-to-one: CRYST1 → _cell/_symmetry, ATOM/HETATM → _atom_site, SEQRES → _entity_poly_seq.
• Many legacy fields lack a direct home in mmCIF because mmCIF splits concepts more finely (e.g. chainID in ATOM corresponds to _atom_site.auth_asym_id, while the "clean" model identifier is _atom_site.label_asym_id, a separate assignment).
• Some mmCIF categories (_entity, _struct_asym, _pdbx_poly_seq_scheme) have no legacy PDB record at all.

Because mmCIF is the more complete and authoritative representation, a NEP reader should prefer implementing the mmcif UDF handler first and treat the legacy PDB reader as a secondary/optional format sharing the same target NetCDF schema.

NEP-Specific Guidance

UDF Slot

Legacy PDB should share the same UDF slot conventions as mmCIF but is distinguished by its own magic number and dispatch entry point. Based on current NEP allocations (see docs/formats.md):

Slot	Format
UDF0	GeoTIFF BigTIFF
UDF1	GeoTIFF standard TIFF
UDF2	GRIB2
UDF3	FITS
UDF4	NASA CDF
UDF5	NASA/ESA PDS4
UDF6	DICOM
UDF7	Legacy PDB
UDF8	PDBx/mmCIF (see mmcif skill)
UDF9	Reserved

Magic Number / Detection

Legacy PDB files have no fixed magic byte sequence at offset 0 the way binary formats do — they are line-oriented text. The most reliable detection heuristic is: the first non-blank record name is one of the title-section keywords (commonly HEADER), or, failing that, the file contains at least one line beginning with ATOM or HETATM in the correct fixed columns. A .pdb/.ent extension check is a reasonable first-pass filter since there is no reliable binary magic number.

/** Legacy PDB format uses UDF7 slot */
#define NEP_UDF_PDB NC_UDF7

/** Legacy PDB magic: first record name, checked at open time by content
 *  inspection rather than a fixed byte pattern */
#define NEP_MAGIC_PDB "HEADER"

#define NEP_FORMAT_NAME_PDB "PDB"

Build Options

Build system	Option
CMake	-DNEP_ENABLE_PDB=ON/OFF (default OFF)
Autotools	--enable-pdb / --disable-pdb

No external library is required — the format is simple enough to parse with a line-oriented reader in NEP itself (unlike mmCIF, which benefits from a real CIF/STAR tokenizer).

Tests

• Use a small, freely redistributable PDB entry for testing (e.g. a short entry from the RCSB PDB such as 1CRN — crambin, no chain breaks, no alternate locations).
• Test cases:
  • Open a .pdb file through nc_open.
  • Verify atom dimension length matches the number of ATOM/HETATM lines.
  • Read atom_site_Cartn_x/y/z for a known atom and compare to values read directly from the file at columns 31-54.
  • Verify unit cell global attributes match the CRYST1 record.
  • Verify behavior on a multi-model NMR file (model dimension > 1).

Important Caveats

1. Fixed columns, not whitespace-delimited: always slice by column range; naive whitespace splitting breaks on tightly packed fields (e.g. resName and chainID can be adjacent with no space when chainID is blank).
2. Chain ID collisions: a single-character chainID may repeat across distinct entities in unusual files; combine with SEQRES/COMPND parsing if entity-level fidelity is needed.
3. Deprecated format: since 2014 wwPDB does not accept new PDB-format depositions and derived legacy files are not generated for entries that do not fit its constraints (large assemblies, long chain IDs). A NEP PDB reader should be documented as best-effort/legacy-only.
4. Element symbol column (77-78) may be blank in older files; element must then be inferred from the atom name (name field, cols 13-16) using standard heuristics.
5. hybrid-36 encoding: some large-structure PDB-format files (e.g. produced by PHENIX) encode serial numbers and residue numbers beyond the fixed-width decimal limits using hybrid-36 (base-36 with a decimal prefix range). A reader that assumes plain decimal integers will misparse these fields.

References

• wwPDB Format Version 3.30: https://files.wwpdb.org/pub/pdb/doc/format_descriptions/Format_v33_A4.pdf
• wwPDB Format Version 2.3: https://www.wwpdb.org/documentation/file-format-content/format23/
• UCSF "Introduction to Protein Data Bank Format": https://www.cgl.ucsf.edu/home/meng/docs/UsersGuide/tutorials/pdbintro.html
• RCSB PDB: https://www.rcsb.org/

When to Use This Skill

Use this skill when:

• Adding a legacy PDB-format UDF handler to NEP.
• Mapping fixed-column PDB records to NetCDF dimensions, variables, and attributes, ideally sharing schema with the mmcif skill's mapping.
• Deciding whether a feature should be represented via the mmCIF reader instead, given legacy PDB's structural limitations.
• Debugging fixed-column parsing, hybrid-36 encoding, or multi-model handling issues.