Preparing inputs#

An annotated CIF is an ordinary mmCIF with extra columns carrying the conditions: hold this atom still, keep that residue’s identity, treat this one as a hotspot. See Annotated CIF for what the format is, why it keeps structure and intent in one file, and how coordinate and sequence conditioning attach at different granularities. This page covers how to build one and run the model against it.

Three ways to make an annotated CIF#

Pick by how much of the design problem you need to express. The Python API can express anything the model can read.

Route	Reach for it when
`rfd4-proteina-annotated-cif`	You want an agent to interview you, inspect existing artifacts, and author or edit the CIF
YAML condition spec	You want the problem as data, in version control
Python API	You are generating many problems, or need something the others cannot say

Python API#

Parse a starting CIF into an AtomArray, set annotations with the AtomWorks condition API, and write the result back out as an annotated CIF. Use this when you want to script many variants of a design, or express something the other two routes cannot say directly.

See the Python API how-to page for a guided walkthrough of parsing, selecting atoms, and setting conditions, including the two core methods — set_annotation_from_ground_truth() and set_annotation() — and when to reach for each. You can find the full API docs here.

YAML condition spec#

To script or template design problems without writing Python, describe them in a small YAML or JSON file. You subset the input, insert expandable segments, and set conditions on atom selections. From there you either write annotated CIFs or hand the spec straight to generate.py. Either way you end up with the same annotated CIF representation described above. This is shorthand for authoring one, not a different format.

See the YAML/JSON condition spec how-to guide for a guided tour of the file shape, contig, and setting conditions; the field-by-field reference has the full syntax and examples.

Running the model#

rfd4-generate \
    inputs=annotated.cif \
    num_replicates=10 batch_size=8

inputs takes a single .cif or .bcif, a directory of them, or a list of file names. Each file is one design problem. Outputs echo source component provenance (information on where each residue, inserted segment in the output structure came from) as per-residue SA_SRC labels like A3; expandable segments retain range labels like 3-10. This lets you trace each output residue to its input residue or inserted segment.

Supported annotations#

Every condition the model reads, its exact CIF column, accepted values, and training definition are in the annotations reference. That page also covers coordinate groups and which conditions are actually wired up today. For why conditions behave the way they do, for example why fixing a sidechain coordinate also fixes its sequence, and why charges and bonds are consumed the way they are, see Conditioning.

Motif scaffolding example#

Here we describe how the annotation conditions work for describing a motif scaffolding design task.

Starting from a theozyme (a handful of catalytic residues and a substrate with no sacffold) you can condition only the atoms in the motif and leave the rest for your model to design using these three annotation conditions:

Condition	Granularity	In a theozyme
`C_CRD`, coordinate	per atom	Pin the atoms that set the active site geometry, so a catalytic residue’s functional atoms and the substrate’s reactive core. Partial on purpose. Leave flexible parts like a phosphate tail free.
`C_SEQ`, sequence	per residue	Fix the identity of a residue or the substrate. All or nothing within one residue, though across a motif you can reveal it on some residues and not others.
`C_IDX`, index	per residue	On by default. Turn it off on the catalytic residues so the model places them freely along the new chain, which makes an unindexed motif.

So a catalytic residue usually fixes its functional atoms with C_CRD and its identity with C_SEQ, while staying unindexed with C_IDX off. The substrate fixes its reactive atoms and identity and keeps its default index. The enzyme design tutorial builds one of these and runs it end to end.

Read Conditioning before conditioning anything with a ligand, metal, covalent modification, or non-canonical residue: those couplings are enforced during input validation and determine what you can fix without unintentionally revealing sequence.

To insert a variable-length placeholder segment, including how it combines with an unindexed motif, see Expandable segments.

FAQ and gotchas#

Do I have to use annotated CIFs? Not directly. JSON inputs and the YAML condition spec are supported. However, these JSON/YAML spec files will create an annotated CIF (or annotated CIFS) based on the specifications. The only input type RFD4-Proteina directly uses is an annotated CIF. Annotated CIFs are useful when conditions and explicit component chemistry should be inspected and edited with the structure. The input-authoring skill creates or edits annotated CIFs directly from prose and structures.

Can I open an annotated CIF in PyMOL or other tools? Yes. See It’s still a CIF.

Why is a fixed sidechain also fixing my sequence? Because atom37 reveals identity, as Conditions are not independent explains. To redesign sequence under a fixed fold, condition on backbone atoms only.

Can I condition expandable segments? Yes. For residue based conditions like chain COM or secondary structure, conditioning a whole expanded region at once often makes sense. Condition an expandable segment and the condition applies to every token its expansion produces.

I have a ligand bound to a peptide chain via a PTM. Should it have its own IndexGroup? No. The model reasons over molecules, not chains. A PTM is part of the same molecule as the peptide chain by definition, so a valid bond graph distance exists between atoms on the PTM and any residue on the main chain. The model sees bond graph distance features whenever the tokens share a molecule and an IndexGroup. Gaps in res_id between the PTM and the peptide chain are fine, because we use bond graph distance for relative positional encoding of atomized segments instead of res_id gaps.