Command: build

Subcommands of build correspond to sections of the Build Structure tool:

• build start – generate a new molecule not bonded to existing atoms
• build modify – change an existing atomic structure
• build join – add a covalent bond between two atomic models to form a single model
• build invert – swap substituents, potentially changing chirality
• build replace – replace part of a chain with part of another chain (without changing the position of the latter set of residues)

See also: addh, bond, angle, torsion, delete, swapaa, swapna, tug, altlocs, dockprep, combine, renumber, changechains, open, rna

• build start atom  model-info  [ position  x,y,z ] [ resName  resname ] [ select  true | false ]
• build start fragment  model-info   fragment-name  [ position  x,y,z ] [ resName  resname ]
• build start peptide  model-info  sequence   φ₁,ψ₁   φ₂,ψ₂  ...  φ_N,ψ_N  [ position  x,y,z ] [ chainId  ID ] [ rotLib   rotamer-library ]
• build start nucleic  model-info  sequence  [ position  x,y,z ] [ type  dna | rna | hybrid ] [ form  A | B ]

For starting a new molecule with build start, the choices are atom, fragment, peptide, or nucleic. With the open command, however, a wide variety of atomic structures for subsequent modification can be fetched from online sources or modeled from a SMILES string.

The model-info can be given as the identifier of an existing atomic model (for example, #2) or a character-string name for a new model.

The position of the new atom or new molecule's geometric center defaults to the current center of view, but can be given as x,y,z coordinates separated by commas only.

For fragment, both model-info and fragment-name are required. Several planar 5- and 6-membered rings and their fused ring systems are available, with choices for fragment-name as listed in the Build Structure dialog.

For peptide, the required arguments are model-info and the sequence as a string of single-letter amino acid codes (upper- or lowercase) and a list of comma-separated pairs of φ,ψ values, up to one pair for each residue, in the same order as in the sequence. Even though the terminal residues lack either φ or ψ, a pair of values is required for each residue; if fewer φ,ψ pairs are entered, however, the values from the last-entered pair will be used multiple times as needed. The “extra” values for the terminal residues will be ignored. Examples:

build start peptide "custom helix" ADKLLNIH -57,-47 rotLib Dunbrack
build start pep ext5 SVQLH -137,145 -150,148 -153,146 -116,157 -123,156

For nucleic, the required arguments are model-info and the sequence of one strand as a string of single-letter nucleic acid codes (upper- or lowercase). The complementary strand of the double helix will also be built according to the specified type (default dna) and form (default B). For building a hybrid DNA/RNA, the sequence of the DNA strand should be given. The nucleic acid chains will be assigned the first two unused chain IDs of the atomic model.

Further options:

• resName – for atom or fragment, a name for the new residue (default UNL)
• select – for atom only, whether to select the new atom (default true), as may be convenient for subsequent modification

Options for peptide only:

• chainId – an existing or new chain ID (default the “lowest” unused ID)
• rotLib – which amino acid sidechain rotamer library to use (see swapaa for details and literature citations):
  • Dunbrack (default)
  • Dynameomics
  • Richardson.common
  • Richardson.mode

The build modify command changes the type of a single specified atom and automatically fills its valence with attached hydrogens. The hydrogens could be modified in turn to continue building outward. The element (element symbol) and numBonds (total number of bonds to the atom, including hydrogens) must also be given, for example:

build modify sel O 2 geometry tetrahedral

Hydrogens will be added to the atom to generate the indicated total number of bonds. They are added to form the idealized bond angles for the specified geometry, or if the atom already has two or more substituents, to maximally avoid those substituents. The default geometry is the same as for the atom's current type. Since the geometry around the atom may be changing, any pre-existing directly attached hydrogens are removed beforehand. No other atoms are removed automatically. If the atom is already bonded to one (and only one) other nonhydrogen atom, the length of the bond will be adjusted depending on the elements involved. No other atoms are moved.

Other options:

• connectBack (default true) – if a newly added hydrogen would be very close to an existing atom in the same model, discard the hydrogen and form a bond to the existing atom instead
• colorByElement (default true) – color the modified atom and any newly added hydrogens by element
• name – new name for the modified atom; if not given, the atom name is kept the same if the element stays the same, or changed to an element-based name if the element is changed
• newRes – whether to put the modified atom and any attached hydrogens into a new residue.
  If newRes is false (default):
  • the resName option can be used to rename the residue containing the modified atom
  • if resName is omitted, the residue containing the modified atom will retain its original name
  • if resName is given as auto, the residue will be renamed according to the following rules:
    • UNK for an amino acid in a bonded chain
    • N for a nucleic acid in a bonded chain
    • UNL otherwise
  If newRes is true:
  • a name for the new residue can be supplied with the resName option
  • if resName is omitted or given as auto, the new residue's name will be based on the atom's original residue type according to the following rules:
    • UNK for an amino acid in a bonded chain
    • N for a nucleic acid in a bonded chain
    • UNL otherwise

The build join command forms a covalent bond of the specified geometry between two atomic models, combining the two models into one. The atoms of one model are repositioned and incorporated into the other model; the original model specified as the one to move will no longer exist. Thus, it may be a good idea to save a session beforehand, since the join (along with other building actions) cannot be undone. The related command combine also combines atomic models, but without forming a bond or changing the relative positions of the atoms.

For build join peptide:

The bond-atoms must include exactly one peptide C-terminal carbon atom C –OR– N-terminal nitrogen atom N (not both) from one model, and from a second model, exactly one of whichever of those two atoms is not in the first. These C and N atoms each must be bonded to only one carbon (except N in proline or hydroxyproline can be bonded to two carbons); however, it may also be bonded to hydrogen and/or OXT, and if so, these atoms will be replaced as appropriate by the new peptide bond. The default length for the new C-N bond is 1.330 Å and the default omega angle (Cα-C-N-Cα dihedral) is 180.0°. There is no default for the phi angle (C-N-Cα-C dihedral). Options for which model to move:

• large – the one with the greater number of atoms
• small (default) – the one with fewer atoms
• C – the one containing the C atom to be bonded
• N (default if the two models have equal numbers of atoms) – the one containing the N atom to be bonded

The residues from the moving model will be assigned the same chain ID as the rest of the chain in the nonmoving model, although their numbers may be shifted by a constant amount to avoid duplicate residue numbers within a chain. If the moving model includes additional chains, the other chain IDs will also be changed as needed to avoid duplicate chain IDs within a model (as described for combine).

The values of omega and phi (along with other peptide torsion angles) are attributes of the amino acid residue containing the newly bonded N.

For build join bond (the more general case):

The replace-atoms must include exactly one atom from each model; these two atoms will be deleted and replaced with the new bond. Each of the replace-atoms must be bonded to only one other atom, and it is these two other atoms that will form the new bond. Usually these atoms to be replaced are hydrogens, so it may be useful to add hydrogens beforehand, to whole models with addh or in a more local fashion with the Modify Structure section of Build Structure. If no length is supplied, it will be estimated from the covalent bond radii of the elements of the atoms. The dihedral angle around the new bond is defined by the newly bonded atoms (atom2, atom3) and their flanking bonds (atom1-atom2, atom3-atom4). If the dihedral angle is specified, unless atom1 and atom4 are unambiguous (the only possibilities), the dihedralAtoms option is required to specify them. If no dihedral angle is given, the two models are simply aligned along the vectors of the two bonds to be replaced, and there is no attempt to rotate them to form a chemically reasonable dihedral angle. Example:

build join bond #1:29@oxt #2:1@h2 length 1.32 dihedral 180 dihedralAtoms #1:29@ca #2:1@ca

Options for which model to move:

• large – the one with the greater number of atoms
• small (default) – the one with fewer atoms
• model-spec – the specified model

If the new bond is between min-backbone atoms (both peptide or both nucleic), the residues from the moving model will be assigned the same chain ID as the rest of the chain in the nonmoving model, although their numbers may be shifted by a constant amount to avoid duplicate residue numbers within a chain. If the moving model includes additional chains, the other chain IDs will also be changed as needed to avoid duplicate chain IDs within a model (as described for combine).

The build invert command exchanges the positions of two substituents of an atom, potentially inverting a chiral center. Substituents of atoms that are not chiral centers can also be swapped.

• If a single atom is specified, the command exchanges the positions of its two smallest substituents based on number of atoms, or if those are the same, the atomic weights of the atoms directly bonded to the selected atom. Implicit hydrogens on the selected atom are considered, but not those on its substituents. These rules are not meant to reproduce the much more complex “priority” calculations used in chirality determination.
• If two atoms directly bonded to the same central atom are specified, the command will exchange the positions of the substituents rooted at those atoms.

The results can be reversed by simply repeating the command.

The build replace command deletes a set of residues from a chain (res-spec1) and replaces them with a copy of set of residues from another chain (res-spec2). The two chains must be of the same polymer type, either both peptide or both nucleic acid. This command is somewhat special-purpose in that nothing is moved; the copied residues will have exactly the same coordinates as the original set of residues. If the geometry is not reasonable, some other method (e.g., dynamic refinement with ISOLDE) would be required to improve the structure.

The copied residues will be assigned the chain ID of the residues that they replaced, and will potentially be renumbered starting from numberingStart  N (default is the same starting number as the deleted residues). Numbers that would give duplicates within the same chain are skipped. The original set of residues is left unchanged.

The bondStart and bondEnd options specify whether to covalently bond the copied residues to their new chain, if the appropriate atoms for a standard mainchain linkage are present. If false, a missing-structure pseudobond will be added instead. The default for each is to add a bond only when the bonding distance is reasonable (same criteria as for the bond command), otherwise a pseudobond. If the appropriate atoms are not both present, regardless of how the corresponding option is set, a pseudobond will be added unless the replaced residues are already at the terminus.