Ligand index

Every structure of the MolNFT archive holds more than its polymer chains: cofactors, substrates, inhibitors and drugs, metal ions, sugars, and the additives of the crystallization. GL1X reads each of them as the structure file describes it, finds the polymer residues it touches, and keeps them in a ligand index: a catalog of chemical components that can be searched by component, name or formula, filtered by class, element, weight and protein, with every binding site of every component and the residues those sites are made of.

Where: the Ligands page (/bio/ligands, in the left menu under Science), a page per component (/bio/ligands/HEM), the Ligands panel of every MolNFT record under its 3D structure, the header search (ligand:HEM, ligand:heme), the API (/api/bio/ligands…) and MCP (ligand_search, ligand_sites, molecule_ligands).

What a ligand is #

A ligand is a non-polymer group of the structure's first model: one residue of the file that belongs to no polymer chain and is not water.

• mmCIF and BinaryCIF state it: the groups of the non-polymer and branched entities (_entity.type), each with its label_asym_id.
• PDB files do not state entities, so GL1X decides as the PDB does: an ATOM residue belongs to its chain, and so does a modified residue written as HETATM (MSE, SEP, 5MC…) that is bonded to the residue before or after it or lies within the numbering of the chain's ATOM residues, even with its trace atoms missing; every other HETATM group is a ligand, a free amino acid or nucleotide included, and so is a cofactor that has an amino acid's atoms (SAH, numbered after the chain, is not bonded to it).
• Left out: waters (HOH, DOD, WAT and their kin), hydrogen and deuterium atoms (a ligand is described by its heavy atoms), and the alternate locations after the first, as for the chains.
• Kept for each ligand: its chemical component (HEM, ATP, ZN), the author chain and residue number with its insertion code (how the file and every paper name it: HEM A:154), the label_asym_id when the file has one, its heavy atoms with their elements (C34 Fe N4 O4), and its centroid.
• Limits: 5,000 ligands a structure, 300 binding-site residues a ligand, 40,000 binding-site residues in all a structure.

Binding sites #

A ligand's binding site is the set of polymer residues (protein, DNA or RNA) with a heavy atom within 4.5 Å of a heavy atom of the ligand, the usual definition of a binding-site residue (4.0 Å before GL1X 3.0; the wider cutoff keeps water-mediated and longer polar contacts that pocket and mutation analyses need). Each residue is kept with its author chain, number and insertion code, its residue name and the closest distance, in chain order. Each ligand also keeps its occupancy, the mean occupancy of its heavy atoms: 1 for a ligand present in every copy of the crystal, less for a partial one, so a site seen at 0.3 occupancy can be told from a firm one.

• How: the polymer's heavy atoms go in a grid of 4.5 Å cells; each atom of a ligand looks in the 27 cells around it, so a structure with thousands of ligands costs milliseconds. A test compares the grid with a comparison of every pair of atoms: the same residues, the same distances.
• Residues are named by their one-letter code and author number, as people write them: K16, H67; A:K16 when a site spans chains (a cofactor between two subunits). Modified residues use their parent's code (MSE is M); residues without a code their name (UNK5).
• What it is not: a contact list says which residues are near, not which interactions they make. The 3D view adds that: when a ligand is shown, Mol's focus draws its surroundings with hydrogen bonds, ionic interactions, π-stacking, metal coordination and the other interactions Mol computes.

Classes #

Every ligand gets one class, from its component and atoms and, when the file states them, its component's type and its entity's type:

The classes help filter, they remove nothing: a sulfate in a phosphate site or a glycerol in an active site can say something about the protein, so every group stays in the index and on its record's page.

Chemical components #

A component is named as the structure files name it:

• mmCIF and BinaryCIF: _chem_comp (name, pdbx_synonyms, formula, formula_weight, type) and _pdbx_entity_nonpoly (name).
• PDB files: HETNAM (name), HETSYN (synonyms) and FORMUL (formula), their continuation lines joined.
• Formulas are written one way: elements with their counts, separated by spaces, the charge last as a signed number (C34 H32 Fe N4 O4, Zn +2). A formula searched for matches whatever order its elements are given in (both sides are read in Hill order).
• Weights come from the file, or are computed from the formula with the IUPAC standard atomic weights.
• The catalog keeps, for each component, the first name, synonyms, formula and weight any structure gave it, and counts its instances (groups), records (MolNFT records in the current inventory that hold it) and entries (PDB IDs: an entry minted in both MolNFT v1 and v2 counts once). The indexing process counts them at start and every five minutes while ligands change; each web process keeps the catalog in memory and reads it again every two minutes.

How the index is built #

Ligands are read with a structure's chains: when the structure queue reads a record's file (see Structures, reading structures), it keeps the chains as before and, in the same transaction, the record's ligands (molecular_ligands); their components then go to the catalog (molecular_ligand_components).

Records whose structures were read before 2.9.0 have chains but no ligands yet. The structure queue reads their files again when it has nothing else to do: a structure waiting to be read for the first time always goes first, and the free workers then take the structures without ligands, experimental structures first (predicted models rarely hold ligands), in order of collection and token. Their chains, GSA strings and comparisons are kept as they are; a file whose digest no longer matches what was read goes back to the structure queue as a whole. A file that cannot be fetched is tried again after an hour, then after twice as long each time (a day at most). The admin's Bio tab follows the backfill (structures read for ligands, the time per file, the failures).

A record the index has not read yet still shows its ligands: its page reads them from the structure file on the spot (at most four files at once; a record read this way is kept ten minutes), says so, and the index adds it when its turn comes.

Search #

The search box (q) takes three kinds of query, and the page says which it read:

• a component id: HEM, ATP, ZN, NAG. An exact id opens straight to its page from the header search (ligand:HEM); on the Ligands page it is shown first, with a link to its binding sites.
• a formula: C34 H32 Fe N4 O4 or C34H32FeN4O4, at least two elements, in any order.
• words of names and synonyms: heme, adenosine triphosphate, flavin. Every word must begin a word of the component's name or synonyms; a piece of three letters or more also matches inside them.

Results are ranked: the exact id, the exact formula, ids beginning with the query, a name or synonym equal to the query, names whose words begin with the query's words, then names that contain it; within a rank, in the order asked.

Every answer says how far the index has read (coverage: structures indexed, read for their ligands, still to read, with ligands; ligands and components), so an empty answer early in the backfill reads as such.

A component's page #

/bio/ligands/{component} shows a component with:

• its facts: formula, weight, class, structures and instances, PDB entries and the component type;
• binding-site residues: the kinds of residue its sites are made of, as bars, each with its share of all the contacts and the number of sites (zinc: cysteines and histidines);
• found with: the components found in the same records, most often first (NAD with zinc in alcohol dehydrogenase, GDP analogues with magnesium in GTPases);
• its binding sites, by collection and record: the structure (PDB ID, title, collection, method), the ligand's chain and number, its heavy atoms and the residues of its site, closest first. View in 3D opens the structure in Mol* with the ligand and its site as ball-and-stick, selected, the viewer's focus on the ligand (its surroundings and their interactions) and the camera on the pocket; Open the record opens the record with the ligand shown. Sites come 25 at a time (More sites).

The counts of sites and records are always complete. For the commonest components (sulfate, glycerol, zinc: up to hundreds of thousands of sites) the binding-site residues come from the first 20,000 sites in collection and token order, and the components found with it from the first 5,000 records; the page says so.

A protein filter (a UniProt accession) keeps the sites touching chains of that protein, and buttons keep one collection. The page's address keeps both (/bio/ligands/HEM?accession=P69905).

A record's ligands #

Every MolNFT record with a structure has a Ligands panel under its 3D view: each group with its component's name and formula, its chain and number, its heavy atoms and its binding site, by class (All, Ligands, Metals…). Show in 3D shows a ligand in the structure above (ball-and-stick, selected, the focus with its interactions, the camera on it) and puts it in the address (?ligand=HEM:A:154: component, author chain, author number), so a link opens the record with the ligand shown; the binding sites of the component pages and of the API link records that way.

API and MCP #

curl -s 'https://YOUR-DOMAIN/api/bio/ligands?q=heme'                         # components by name
curl -s 'https://YOUR-DOMAIN/api/bio/ligands?q=C34H32FeN4O4'                 # by formula
curl -s 'https://YOUR-DOMAIN/api/bio/ligands?class=metal&sort=records'       # every metal
curl -s 'https://YOUR-DOMAIN/api/bio/ligands?element=F&min_weight=150&max_weight=900&class=ligand'
curl -s 'https://YOUR-DOMAIN/api/bio/ligands?accession=P00533'               # what binds EGFR
curl -s 'https://YOUR-DOMAIN/api/bio/ligands/HEM?limit=25'                   # binding sites of heme
curl -s https://YOUR-DOMAIN/api/bio/records/0xde3723766bc32dcacd03c17baa400a7b36837eba/7/ligands

• GET /api/bio/ligands answers the components (comp_id, name, synonyms, formula, weight, chem_type, class, instances, records, entries, url), the query as read (with its formula in Hill order), total, by_class, coverage and the index's rules.
• GET /api/bio/ligands/{comp} answers the component, a page of items (each site with its contract, token_id and index, chain, label_chain, number, class, atoms, elements, center, contacts with chain, number, residue, code and distance, the record, the structure's entry_id, method, predicted, structure_title and structure file, and a url that opens the record with the ligand shown), total, next_cursor (pass it as cursor for the next page; 25 sites by default, at most 100), binding_residues, found_with, by_collection and stats_sample (how many sites and records the residues and the components found with it come from). It takes accession, collection, limit and cursor.
• GET /api/bio/records/{contract}/{tokenId}/ligands answers a record's ligands (each with index, comp_id, name, formula, weight, class, chain, label_chain, number, atoms, elements, center and contacts), components, by_class, contact_distance and source: index (from the ligand index), file (read from the structure file just now) or none (the record has no structure file).
• Errors say why: invalid_component, invalid_query, invalid_class, invalid_element, invalid_weight, invalid_sort, invalid_accession, invalid_collection, invalid_limit, invalid_offset, invalid_cursor, invalid_contract, invalid_token, ligand_not_found (404: no such component in the index), record_not_found (404), ligands_pending (503: the structure file is still being read, ask again in a few seconds), structure_unavailable (502), ligand_rate_limited (429: searches and sites, 30 at once and one more a second for each client). Answers are cached for 30 seconds (a record's: 60 seconds from the index, 15 seconds otherwise).

MCP: ligand_search (the catalog: q, class, element, min_weight, max_weight, accession, sort, limit), ligand_sites (a component's binding sites: comp, accession, collection, limit, cursor) and molecule_ligands (a record's ligands). An agent can go from a protein to what binds it (ligand_search with accession), from a cofactor to every pocket that holds it (ligand_sites), and from a record to its ligands and their residues (molecule_ligands), then on to the structures (structure_search) and datasets (bio_dataset). → MCP

Limits #

• The index describes what the files deposit: a ligand modelled in part has the atoms that were modelled; a site where the ligand was not modelled is not one. Predicted models (AlphaFold DB and others) have no ligands.
• Only the first model of a structure is read: in an NMR ensemble, the first conformer.
• Contacts are distances, not interactions; there is no docking, no binding affinity and no pocket detection without a ligand.
• Components are named by the files; the catalog does not fetch the PDB's Chemical Component Dictionary, so a component a PDB file names without a HETNAM record has its id and formula only, or its id alone.
• Classes come from component lists and a few rules: an unusual buffer may be a ligand, a metal-containing cluster (an iron-sulfur cluster, SF4) is a ligand, not a metal.

References #

• Hill EA (1900) On a system of indexing chemical literature; adopted by the Classification Division of the U.S. Patent Office. J Am Chem Soc 22:478–494.
• Prohaska T, Irrgeher J, Benefield J, et al. (2022) Standard atomic weights of the elements 2021 (IUPAC Technical Report). Pure Appl Chem 94:573–600.
• Sehnal D, Bittrich S, Deshpande M, et al. (2021) Mol* Viewer: modern web app for 3D visualization and analysis of large biomolecular structures. Nucleic Acids Res 49:W431–W437.
• Westbrook JD, Shao C, Feng Z, Zhuravleva M, Velankar S, Young J (2015) The chemical component dictionary: complete descriptions of constituent molecules in experimentally determined 3D macromolecules in the Protein Data Bank. Bioinformatics 31:1274–1278.
• Yang J, Roy A, Zhang Y (2013) BioLiP: a semi-manually curated database for biologically relevant ligand–protein interactions. Nucleic Acids Res 41:D1096–D1103.
• Zhang C, Zhang X, Freddolino PL, Zhang Y (2024) BioLiP2: an updated structure database for biologically relevant ligand–protein interactions. Nucleic Acids Res 52:D404–D412.