AtomWorks

What is atomworks?

atomworks is a Python toolkit designed for biological data workflows. It is built on top of Biotite and provides a unified interface for several key tasks:

• Data Parsing: Support for formats including mmCIF, PDB, FASTA, and SMILES.
• Manipulation: Tools for transforming and annotating protein, nucleic acid, and small molecule data.
• Featurization: Preparing biological data for downstream analysis or machine learning applications.

It enables seamless conversion between different biological data representations, making it suitable for both structural biology research and machine learning pipelines.

The utils module in atomworks contains a collection of helper functions designed to simplify common molecular operations. Supported categories of utilities include:

• Assembly: Functions for building or combining structures.
• Bonds: Utilities for managing and querying chemical bonds.
• CCD: Support for Common Complex Fragments (CCD).
• Chain operations: Manipulating molecular chains.
• I/O: Input/Output helpers for file handling.
• Selection: Tools for selecting specific atoms or residues.
• Sequence: Utilities for handling amino acid or nucleotide sequences.
• Testing: Helpers for unit testing and validation.
• Visualization: Tools for rendering and viewing structures.

AtomWorks defines structural components using a hierarchy of three concepts:

1. Chains: The smallest covalently bound unit. In mmCIF, a chain is defined by a unique combination of an asym_id and a transformation_id.
2. PN_Unit (Polymer or Non-polymer Unit): A collection of covalently linked chains of the same type. For example, multiple non-polymer chains forming an oligosaccharide constitute one pn_unit. However, a protein and its bound oligosaccharide are two separate pn_units because they differ in chain type.
3. Molecule: A single connected component of a covalent bond graph (determined by traversal). A single molecule can contain multiple pn_units (e.g., a protein with a covalently bound glycan modification).

AtomWorks uses a specific nomenclature to distinguish between chemical identity and spatial positioning in mmCIF files:

• Entities: Represent the chemical compound itself. They define the covalent connectivity and components but do not include specific 3D coordinates. Think of an entity as a class in Python.
• Instances: Represent unique copies of an entity in 3D space. They have specific coordinates. Think of an instance as an instance of a class.

For example, if a mmCIF file contains multiple copies of the same protein chain (each with unique coordinates but identical sequences), they are distinct instances but belong to the same underlying entity (sharing the same UNIREF identifier).

When you call parse(), it returns a dictionary with the following keys:

• chain_info: A mapping of chain IDs to their sequence, type, and metadata.
• ligand_info: Information about ligands present in the structure.
• asym_unit: An AtomArrayStack of the asymmetric unit (similar to PDB content).
• assemblies: A mapping of assembly IDs to AtomArrayStacks.
• metadata: Structure-level metadata (e.g., crystallization details, method, resolution).
• extra_info: Internal-use information for caching and compatibility.

AtomWorks requires Python >= 3.11 and the dotenv package. You can install different versions of the package depending on your needs using pip or uv:

• Base installation (only atomworks.io): pip install atomworks
• ML installation (includes torch and atomworks.ml): pip install "atomworks[ml]"
• Development installation: pip install "atomworks[dev]"
• Open Babel installation: pip install "atomworks[openbabel]"
• Full installation (all dependencies): pip install "atomworks[ml,openbabel,dev]"

If using uv, use:

uv pip install "atomworks[ml,openbabel,dev]"

WARNING

A vulnerability in pyarrow (a dependency) has been identified. If your system supports pyarrow>=23.0.1, update your pyproject.toml to a newer version before installing AtomWorks.

To test the pipeline without downloading the full PDB (~100 GB), you can download a ~500 MB test pack containing a mini-PDB, custom CCD, and metadata.

Note: Run this command from the AtomWorks root directory to ensure the data is placed in tests/data.

# Download test pack (~500 MB)
atomworks setup tests

# Run data loading pipeline tests
pytest tests/ml/pipelines/test_data_loading_pipelines.py

If you are contributing to or developing AtomWorks, clone the repository and install it in editable mode.

To install in a fresh environment, you can use the provided make env command.

git clone https://github.com/RosettaCommons/atomworks.git
cd atomworks
make install  # or pip install -e ".[dev]"

# To install in a fresh environment:
git clone https://github.com/RosettaCommons/atomworks.git
cd atomworks
make env

To run the test suite, you must download the test data pack (~500 MB) and configure the environment variables so the tests can locate the data.

1. Download data: Run atomworks setup tests to populate tests/data/ with PDB, CCD, and shared ML data.
2. Configure paths: Create a .env file in the repository root. You can use .env.sample as a template. You must set PDB_MIRROR_PATH and CCD_MIRROR_PATH to point to the downloaded test data.
3. Run tests: Use pytest to execute the suite.

# 1. Download test data
atomworks setup tests

# 2. Create and configure .env
cp .env.sample .env
# Edit .env to set:
PDB_MIRROR_PATH=tests/data/pdb
CCD_MIRROR_PATH=tests/data/ccd

# 3. Run tests
pytest tests -m "not very_slow"

To facilitate sampling and filtering for training, AtomWorks uses pre-processed metadata. You can download pre-computed metadata (containing PN units and interfaces) using the atomworks setup metadata command.

This produces two primary Parquet files:

• pn_units_df.parquet: Metadata for each PN unit (a polymer XOR non-polymer unit, which behaves like a chain but treats multi-ligand complexes as a single unit).
• interfaces_df.parquet: Metadata for all binary interfaces in the PDB, listed as (pn_unit_1, pn_unit_2) pairs.

atomworks setup metadata /path/to/metadata