Cookbook

The atomworks cookbook is intended to be a quick reference for various common tasks. Note the code snippets may not be complete as-written, and may require imports or other preparatory steps.

As the AtomArray object comes from biotite, the biotite documentation and api reference contains additional resources for working with it.

Input

Standard Local File Input

Accepts common structure input formats (mmCIF, PDB, mmjson and BCIF/BinaryCIF), both with filenames and file-like objects. CIF files can also be gzip- or Zstandard-compressed.

See the Parser tutorial page for details on parameters and output. You can also find the API docs for the parse function here. The example below shows how to set a few common options with ParseConfig (their defaults are shown):

import atomworks.io
import atomworks.io.config

result_dict = atomworks.io.parse(
    filename,
    config=atomworks.io.config.ParseConfig(add_missing_atoms=True, remove_waters=True, hydrogen_policy="keep"),
)

# Extract relevant AtomArray:
asym_unit = result_dict["asym_unit"][0]       # The full asymmetric unit
assembly = result_dict["assemblies"]["1"][0]  # The Biological Assembly/biounit (possibly comprising multiple asym_units)

Load from Clean Files

For previously processed structures (e.g. those which have already passed through an AtomWorks preparation pipeline), use the minimal parser preset. This keeps waters and loads the structure without adding missing atoms:

import atomworks.io

atom_array = atomworks.io.parse(filename, config="minimal")["asym_unit"][0]

Database Input

The parse() function can be used to download the given PDB id from the RCSB website:

result_dict = atomworks.io.parse( atomworks.io.utils.testing.get_pdb_path_or_buffer( PDBID ) )

CCD/SDF/SMILES Input

ccd_code_to_annotated_atom_array(), sdf_to_annotated_atom_array(), smiles_to_annotated_atom_array() can be used to convert CCD codes, SDF files, or SMILES strings into annotated AtomArrays, respectively.:

atom_array = atomworks.io.tools.inference.ccd_code_to_annotated_atom_array( ccd_code, chain_id )
atom_array = atomworks.io.tools.inference.sdf_to_annotated_atom_array( sdf_filename, chain_id )
atom_array = atomworks.io.tools.inference.smiles_to_annotated_atom_array( smiles_string, chain_id )

Sequence Input

The following is a simple procedure for how to create an annotated AtomArray from a sequence string:

chain_type = atomworks.enums.ChainType.POLYPEPTIDE_L

# If you have RF3-style sequence string with parenthesized CCD codes:
ccd_list = atomworks.io.tools.fasta.one_letter_to_ccd_code( atomworks.io.tools.fasta.split_generalized_fasta_sequence( sequence_string ), chain_type=chain_type )

# ccd_list is just a list with one CCD code per entry.

atom_array = atomworks.io.tools.inference.sequence_to_annotated_atom_array( ccd_list, chain_id, chain_type=chain_type )
# Caution! The atom array will not contain coordinates.

API docs for these functions:

• POLYPEPTIDE_L

• one_letter_to_ccd_code()

• split_generalized_fasta_sequence()

• ccd_code_to_annotated_atom_array()

Output

mmCIF output

to_cif_file() supports .cif, .cif.gz and .bcif outputs:

import atomworks.io.utils.io_utils

atomworks.io.utils.io_utils.to_cif_file(atom_array, filename, chain_disambiguation="chain_iid")

You can also write a CIF to an in-memory buffer and read it back into AtomWorks. The example below keeps track of the different copies of a chain in a biological assembly using transformation_id:

import atomworks.io
import atomworks.io.utils.io_utils

buffer = atomworks.io.utils.io_utils.to_cif_buffer(
    atom_array,
    config=atomworks.io.utils.io_utils.CIFWriteConfig(
        include_entity_categories=True,
        chain_disambiguation="transformation_id",
    ),
)
restored = atomworks.io.parse(buffer, config="minimal")["asym_unit"][0]

If you plan to open the CIF in another program, use chain_disambiguation="chain_iid" to give each chain copy a unique name. The transformation_id option keeps the original chain names and records the copies in a form AtomWorks can read. To save additional annotations, check the writer options and whether the program reading the file supports them. Parsing the file again can still change some annotations, even with the minimal preset.

Legacy PDB output

While the use of to_pdb_string() is possible for creating legacy PDB files, use of mmCIF instead is recommended:

import atomworks.io.utils.io_utils
import numpy

resolved = atom_array[numpy.isfinite(atom_array.coord).all(axis=-1)]
with open(filename, "w") as f:
    f.write(atomworks.io.utils.io_utils.to_pdb_string(resolved))

This example leaves out atoms with missing coordinates, which PDB cannot store. Use mmCIF if your chain, residue, or atom identifiers exceed the limits of the PDB format.

SDF/SMILES output

This procedure may not work reliably for multi-residue AtomArrays (or too-small fractions of a single residue):

rdmol = atomworks.io.tools.rdkit.atom_array_to_rdkit( atom_array )

smiles = rdkit.Chem.MolToSmiles( rdmol )

with rdkit.Chem.SDWriter( sdf_filename ) as w:
    w.write( rdmol )

API docs for these functions:

• atom_array_to_rdkit()

• MolToSmiles

• SDWriter

FASTA output

biotite.structure.to_sequence will raise an error if the atom_array contains non-polymeric residues:

results = biotite.structure.to_sequence( atom_array )

seq_list = results[0] # The second entry in the returned tuple is chain_start_indices

Structure Manipulation

Combining AtomArrays

For example, to combine a receptor with a ligand:

combined_atom_array = atom_array_1 + atom_array_2

Subsetting AtomArray

AtomArray can be subsetted by indexing with a Boolean array, resulting in another AtomArray:

present = atom_array[ atom_array.occupancy > 0 ]
calpha  = atom_array[ atom_array.atom_name == "CA" ]
chainA  = atom_array[ atom_array.chain_id == "A" ]
gly     = atom_array[ atom_array.res_name == "GLY" ]
polymer = atom_array[ atom_array.is_polymer ]
not_bb  = atom_array[ ~biotite.structure.filter_peptide_backbone(atom_array) ]
res_B34 = atom_array[ (atom_array.chain_id == "B") & (atom_array.res_id == 34) ] # Parenthesis are needed.

atom_array contains a number of helpful utility functions (primarily used in structure loading):

no_waters = atomworks.io.transforms.atom_array.remove_waters( atom_array )
no_ccd    = atomworks.io.transforms.atom_array.remove_ccd_components( atom_array, ccd_code_list )
no_hydro  = atomworks.io.transforms.atom_array.remove_hydrogens( atom_array )

The biotite.structure module contains a number of filter functions to help subset the AtomArray:

sugars = atom_array[ biotite.structure.filter_carbohydrates(atom_array) ]

Each selection uses annotations on the AtomArray, such as occupancy or is_polymer. If your assembly contains several copies of the same chain, select by chain_iid or pn_unit_iid to choose just one copy before selecting its residues. The backbone filter in the example applies to proteins.

Changing annotations

Note this naive manipulation doesn’t update the _id/_iid/pn_unit/molecule/etc. identity correspondences:

atom_array.chain_id[ atom_array.is_polymer ] = "A"
atom_array.res_id[ atom_array.res_id == 1004 ] = 4

Coordinate Manipulation

Simple Translation/Rotation

translated = biotite.structure.translate( atom_array, (x,y,z) ) # Displacement can be any array-shaped
rotated    = biotite.structure.rotate_about_axis( atom_array, axis, angle, center ) # Center can be omitted to rotate around origin

API docs for these functions:

• biotite.structure.translate

• biotite.structure.rotate_about_axis

Alignment

If the AtomArrays have identical atom layouts:

superimposed, transformation = biotite.structure.superimpose( fixed, mobile )

superimposed2 = transformation.apply( mobile2 ) # Apply same transformation to different AtomArray

If the structures aren’t identical, the following uses sequence alignments to find pairings:

superimposed, transformation, fixed_indices, mobile_indices = biotite.structure.superimpose_homologs( fixed, mobile )

If there’s low sequence similarity, the following uses structural similarity to find pairings:

superimposed, transformation, fixed_indices, mobile_indices = biotite.structure.superimpose_structural_homologs( fixed, mobile )

API docs for these functions:

• biotite.structure.superimpose

• biotite.structure.superimpose_homologs

• biotite.structure.superimpose_structural_homologs

Calculations

Distances/Angles

Geometry calculations take AtomArrays all of N entries (or one entry to be broadcasted), resulting in a numpy array of N distances:

distances = biotite.structure.distance( atom_array_1, atom_array_2 ) # In Angstroms
angles    = biotite.structure.angle( atom_array_1, atom_array_2, atom_array_3 ) # In radians
dihedrals = biotite.structure.dihedral( atom_array_1, atom_array_2, atom_array_3, atom_array_4 ) # In radians

There’s convenience functions for standard protein dihedrals:

bb_dihedral = biotite.structure.dihedral_backbone( atom_array ) # tuple of (phi, psi, omega) array

API docs for these functions:

• biotite.structure.distance

• biotite.structure.angle

• biotite.structure.dihedral

• biotite.structure.dihedral_backbone

Structural Comparison

rmsd = biotite.structure.rmsd( reference, subject ) # RMSD without superposition
lddt = biotite.structure.lddt( reference, subject )
# fixed_indices & mobile_indices can come from superimpose_structural_homologs()
tm_score = biotite.structure.tm_score( reference, subject, fixed_indices, mobile_indices )

API docs for these functions:

• biotite.structure.rmsd

• biotite.structure.lddt

• biotite.structure.tm_score

Visualization

Viewer

Interactive viewer (view()) (for Notebooks):

atomworks.io.utils.visualize.view(atom_array)

Other

If there are other common tasks you think are worth including here, please open an issue on Github.