About and methods

The mapping rules, the observed and inferred rule, sources and licences, and how to contribute.

Methods

What a page is

One page per molecule. Proteins are keyed on their UniProt accession (with an isoform suffix when a page is about one isoform). The schema also defines RNA pages (RNAcentral URS, with the Rfam family), DNA structure pages (DNA- plus 12 hex digits of the SHA-256 of the sequence, with NAKB and PDB identifiers) and complex pages (CPX-, linking component pages); protein, RNA and DNA pages are built; complexes are not yet. A page lists the states a protein is curated to have, the evidence from each technique that has probed it, how each evidence item maps to a state, the conflicts between comparable measurements, and the models exported for observed states.

The proteins built are listed in targets.yaml. A protein with no curation file still gets a page with all its evidence, labelled "states not yet curated"; nothing on it is mapped until a curator defines states.

Observed and inferred

Every state and every model carries one of two labels.

• Observed: the state is directly resolved by a structure determination. X-ray crystallography, cryo-EM, microED, neutron diffraction and NMR structure determination are observed methods.
• Inferred: the state or model is fitted to indirect constraints. Smoothed or averaged measurements (smFRET, force spectroscopy, HDX-MS, SAXS, CD, relaxation dispersion and the rest of the taxonomy) are inferred.
• Integrative models (PDB-IHM entries distributed through the PDB) are inferred: they are fitted to several kinds of restraints.
• Computational predictions (AlphaFold DB models, molecular dynamics, Markov state models, AlphaFold-based ensembles) are inferred and also flagged as predictions.

An inferred state or model must list its assumptions. The pipeline refuses to build one without them, and the page shows them one click away.

Nucleic-acid states, vocabularies, mutational effects and kinetics

These are in the schema; no source fills them yet.

• Secondary structure: an RNA or DNA state may carry a dot-bracket string ((), with [], {}, <> and letter pairs for pseudoknots, + for G-quadruplex tetrad guanines). The validator checks that brackets balance, that the string fits the sequence, and that every pair is Watson-Crick or G-U.
• Profiles: per-residue or per-nucleotide data (SHAPE and DMS reactivities, protection factors) are stored as one profile on the evidence item, not one item per position. Φ-values are a profile on the transition.
• Populations: when one dataset resolves several states (DREEM or DRACO clustering, cryo-EM classes), each state records its population and the method.
• Family vocabularies (taxonomy/state_vocabularies/): kinases (KLIFS), GPCRs (GPCRdb), secondary transporters, ion channels, riboswitches and G-quadruplexes, each citing its source. A state may carry a family_label (one term per axis, for example DFG-in and alphaC-out) alongside its free name; the validator checks every term exists.
• Mutational effects (mutational_effect records): a variant in HGVS notation, or a per-residue summary of a large dataset that is linked, not copied; the shift (ΔΔG of folding or of a state equilibrium, ΔTm or a functional score); the state pair it refers to; method and conditions; ClinVar ID when there is one.
• Kinetics on transitions: forward and reverse rate constants, m-values, distance to the transition state, activation energy, Φ-values, and the measuring method.
• Ions: conditions list ions with concentrations (Mg²⁺ for nucleic acids) next to the total salt.

Evidence

One evidence item per experiment or deposit:

• RCSB PDB: one item per polymer entity whose UniProt mapping includes the accession.
• NAKB (RNA and DNA): one item per nucleic-acid entity with exactly the molecule's sequence, or, for RNA, in the same Rfam family and organism (another construct of the same RNA; the item says which).
• Rfam (RNA): one item per family hit, with the fraction of the sequence the covariance model covers. Labelled as a prediction.
• BMRB: one item per entry in BMRB's UniProt mapping.
• SASBDB: one item per entry whose sample lists a molecule with this UniProt code (radius of gyration with its error).
• DisProt: one item per curated region with a structural-state or structural-transition term; the ECO evidence code names the technique.
• AlphaFold DB: one item per predicted model (mean pLDDT).
• MDDB: one item per simulation project that references the accession (trajectory length).
• SMASH-BIO: one item per extracted force-spectroscopy result, or one study-level item when a record has no extracted value. The extraction level (automatic or curated) is kept on the item.

Items a source returns but that cannot become evidence (an unmapped method, a non-structural term, a sample without the protein) are listed with the reason in build/<UniProt>/ingest.json. Each item records the technique, the construct, the conditions (environment, temperature, pH, ligands, applied force), the observable with its value, uncertainty and unit, the provenance (source, DOI, deposit ID, retrieval date, licence) and a link to the data.

Conditions are always present. An unknown value is recorded as null, not omitted. Temperatures from mmCIF fields (defined in kelvin) are converted to degrees Celsius. pH and temperature are null when an entry does not carry them in its machine-readable fields.

Mapping

Each link from an evidence item to a state is a mapping record: who made it, a confidence (high, medium or low), and a one-line justification. The mapping is always shown on the page next to the evidence.

• Curator assignment (who: curator:<name>): the curator names the evidence and the state in curation/<UniProt>.yaml.
• Curated rule (who: rule:<rule id>): the curator writes criteria in the same file: techniques, sources, observable types, environment, ligands present or absent, and words in the title. Every criterion given must hold. Each rule carries its own confidence and justification, which every mapping it makes repeats.
• A curator assignment always wins: rules are not applied to evidence the curator has assigned.
• When rules for two different states match the same item, the item stays unmapped and is listed as ambiguous on the page.
• Anchor RMSD (who: rule:anchor_rmsd): a structure clusters with an anchor when its C-alpha RMSD, after superposition on shared residues, is within a cut-off. The superposition is implemented and tested. It is not yet run on the pilot, because it needs coordinates for every candidate entry.

Ambiguous evidence stays unmapped. Unmapped evidence is listed on the page and counted, and is never assigned to a state silently.

Conflicts

Two evidence items conflict when they are mapped to the same state, report the same observable type and unit, have comparable conditions (environment, temperature within 5 °C, pH within 0.5, the same ligands), both carry an uncertainty, and their values differ by more than the combined uncertainty. Conflicts are shown on the page. Values are never averaged across a conflict.

Force observables (unfolding, rupture and similar forces) are not compared: they depend on loading rate, which the conditions schema does not record, so values from different pulling protocols are not comparable.

Evidence without an uncertainty is not compared. The page says how many items could not be compared, and that absence of a conflict is not agreement.

Coverage grid

For each protein, the grid counts mapped evidence per state and technique. A state whose mapped evidence comes from exactly one technique is shaded and labelled "one method", so a state that rests on a single technique is visible at a glance.

Models

Observed states export the representative PDB entry's coordinates, unchanged, as PDB and mmCIF files. The file header records the state, its basis and the source entry. Inferred states will get fitted models in a later stage; the pilot exports none.

Transitions

A transition is directional and carries a rate or a free-energy difference, the conditions it was measured under, and the evidence IDs behind it. No transitions are curated in the pilot.

Search and display

The search page matches every word of a query against proteins (name, gene, accession, organism, techniques, sources, states) and against every evidence item (ID, deposit ID, title, construct, ligands, mapped states), with filters for technique, source, organism, curation status and state basis. A protein is listed when its own text or any of its evidence matches. The front page shows a proteins x techniques matrix of evidence counts on a log scale. Both are generated by make site from the same build outputs as every other page.

Reproducibility

Every number on the site is produced by make site from build/, which is produced by make ingest, make map and make models from the raw downloads in data/raw/. The download manifest, data/MANIFEST.json, records the URLs, retrieval dates and SHA-256 hashes of each raw input. Raw downloads are not committed.

Known limits of the pilot

• Only the canonical isoform of each protein is recorded.
• Literature extraction, PED and PDB-IHM restraint tables are not yet ingested. ATLAS is not ingested; MD comes from MDDB.
• Entries annotated to a sibling accession with an identical sequence (for example CALM2 and CALM3 for calmodulin) are not grouped with the pilot accession. See the pilot report.
• Curation is a draft and is labelled as such on every page until a curator reviews it.

Contributing

Adding a protein

Add a line to targets.yaml with the UniProt accession, a batch that says why it was added, and a name. make download and make site then build an evidence-only page for it. Pages without a curation file say "states not yet curated".

Curating a protein

Copy a curation file from curation/ as a template, name it <UniProt>.yaml, define the states (with a representative PDB entry for observed states and assumptions for inferred ones), then add assignments and rules. See curation/README.md for every field.

Correcting a page

Every page has a link to its curation file. To correct a state, a mapping or a description:

1. Open curation/<UniProt>.yaml on GitHub and propose an edit, or open an issue that names the page and the change. 2. Each mapping needs a curator, a confidence (high, medium or low) and a one-line justification. Say which evidence ID (for example EV-PDB-4AKE-1) and which state. 3. Inferred states need assumptions. A state is not inferred because its evidence is indirect; it is inferred when a model is fitted to it. 4. Run make validate before opening a pull request. It checks the schemas, the references between records, the taxonomy, the licence rows and the site.

Adding evidence

Evidence comes from sources, not from hand entry. Add or fix a source module in conformome/sources/ following the contract in conformome/sources/base.py, record its licence in docs/SOURCES.md, and add a fixture if the parser changes.

Adding a technique

Add it to taxonomy/techniques.yaml with its basis (observed or inferred), whether it is a prediction, its resolution class and the observable types it reports. The validator rejects evidence whose technique or observable is not listed.

What not to change by hand

Do not edit anything under site/dist/ or build/. They are regenerated by make site. Do not edit data/MANIFEST.json by hand; it is written by make download.

Ground rules

• No data that a licence forbids redistributing. Link to it instead.
• Nothing extracted from literature goes live without human review.
• Conflicts are shown, not averaged away.

Sources and licences

Each source module in conformome/sources/ has a row here. make validate checks that every module has a row, that the licence is recorded (not TBD), that status matches the module's IMPLEMENTED flag, and that sources marked redistribute: no do not appear in any downloadable file. Where a licence is marked verify, the licence was not checked against the source's own terms in this version and must be confirmed before a public release.

Conformome's own curation files (curation/) and generated pages are licensed under the project licence, which is still to be decided (see docs/PILOT_REPORT.md).