read_structure
Read-only
Read a structure file — PDB, PDBx/mmCIF, or a core CIF small-molecule crystal structure — and report what is in it: the chains and what kind each is, their sequences, the ligands and ordered solvent, the disulfides, the residues the depositor declared modified, the temperature-factor range, the unit cell and space group, the resolution and the experiment. Use it to answer what a structure IS before deciding what to do with it, or to pull a chain's sequence out of a structure so it can be aligned, back-translated or ordered. Reading only: it never writes a structure file and never applies symmetry, so every count it reports is a count of what the file actually holds — for a core CIF that is the asymmetric unit, not the whole cell.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | the coordinate file's contents — a PDB flat file, a PDBx/mmCIF, or a core CIF; the format is read from the bytes, not from a name, because .cif is shared by two unrelated dictionaries. | |
| model | No | which model of an ensemble to describe, 1-based. An NMR entry holds many complete conformers and they are alternatives rather than parts, so the counts always describe ONE of them. The upper bound is the FILE's, so it is not declared here — an out-of-range model is refused by name, with the range that exists. | |
| _files | No | The project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name. | |
| _subject | No | The record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | the 4-character entry id the file declares about itself, empty when it declares none | |
| cell | Yes | unit cell and space group, absent for a determination with no crystal | |
| atoms | Yes | atoms in the model described | |
| title | Yes | the entry's own title line | |
| chains | Yes | one row per chain: id, polymer kind, residue and atom counts, the author numbering range, and the observed one-letter sequence | |
| extent | Yes | the longest side of the bounding box in angstroms — whether this will fit a pore, a groove or a box | |
| format | Yes | which reader actually ran: `pdb`, `mmcif`, or `smallcif` for a core CIF (small-molecule crystallography, which shares the .cif extension with mmCIF and is a different dictionary) | |
| method | Yes | the experimental technique(s) — genuinely more than one for a neutron/X-ray structure | |
| models | Yes | conformers in the file; more than one means an ensemble | |
| waters | Yes | ordered solvent molecules, counted separately from ligands | |
| bFactor | Yes | min, max and mean isotropic B over every atom, or null when the file states none | |
| dialect | Yes | the same answer in words, for a reply to quote | |
| formula | Yes | the empirical formula the file STATES about itself (`_chemical_formula_sum`), empty when it states none. For a crystal structure it describes the contents of the CELL, so it can name more atoms than the sites listed | |
| helices | Yes | helices the DEPOSITOR annotated (not a calculation over the coordinates) | |
| ligands | Yes | non-water heteroatom components with how many copies of each — the ions, cofactors and bound compounds | |
| strands | Yes | strands the depositor annotated | |
| modified | Yes | modified residues with the standard residue each stands in for, from the file's own MODRES / _pdbx_struct_mod_residue — the only authoritative source for what a component like MSE IS | |
| residues | Yes | residues in the model described, solvent included | |
| warnings | Yes | lines the reader could not parse, named rather than dropped | |
| sequences | Yes | the CONSTRUCT sequence per chain as the file declares it (SEQRES / _entity_poly), which includes residues that were never resolved | |
| disulfides | Yes | disulfide bonds the file annotates | |
| hasPolymer | Yes | whether any chain is a polymer. False for a core CIF and for a coordinate set holding only a ligand — where `chains`, `residues` and `sequences` describe a wrapper rather than a molecule, and `atoms` is a count of symmetry-independent SITES | |
| resolution | Yes | diffraction limit in angstroms. 0 means the entry states NONE (an NMR determination has no resolution) — read `hasResolution` rather than treating 0 as sub-angstrom | |
| hasResolution | Yes | whether the entry states a resolution at all |