Biotraj - Trajectory File I/O for Biotite

1.2.2 · active · verified Fri Apr 10

Biotraj provides basic functionality to load and handle molecular dynamics trajectory files, specifically designed for use with the Biotite package. It is a lightweight fork of MDTraj, with MDTraj's C-extensions and analysis functionality removed, focusing purely on efficient trajectory I/O. The current version is 1.2.2, with releases typically aligned with the Biotite ecosystem.

Warnings

gotcha Biotraj is a fork of MDTraj, but it specifically removes MDTraj's C-extensions and analysis capabilities. It is intended *only* for trajectory I/O and basic handling within the Biotite ecosystem, not as a drop-in replacement for MDTraj's full feature set.
Fix: Use MDTraj if full analysis functionality is required. Use biotraj only for I/O with Biotite structures.
gotcha Biotraj is tightly integrated with the Biotite ecosystem and primarily works with 'biotite.structure.AtomArray' and 'AtomArrayStack' objects. Users coming from other molecular dynamics libraries may need to convert their structures to Biotite's format before using biotraj for I/O.
Fix: Ensure your molecular structures are converted to biotite.structure.AtomArray or AtomArrayStack objects. Refer to Biotite's documentation for structure conversion utilities.
gotcha Unlike MDTraj, `biotraj.Trajectory` objects do not have an `atom_slice` property for generating a view of a subset of atoms. Instead, use the `select_atoms()` method, which returns a *new* Trajectory object containing only the selected atoms.
Fix: Replace `traj.atom_slice(indices)` with `traj.select_atoms(indices)` and assign the result to a new variable.

Install

pip install biotraj Install stable release

Imports

Trajectory
```
from biotraj import Trajectory
```
Main class for representing and manipulating trajectory data.
load
```
import biotraj as bt
traj = bt.load('path/to/file.xtc')
```
Convenience function to load trajectory files from disk.
read_traj
```
import biotraj as bt
traj = bt.read_traj('path/to/file.dcd')
```
Similar to `load`, but can be used for specific trajectory file types (e.g., DCD, XTC).

Quickstart

This quickstart demonstrates how to create a simple `biotite.structure.AtomArrayStack`, save it to an XTC file using Biotite's I/O, and then load it as a `biotraj.Trajectory` object. It illustrates the core process of reading trajectory data into a usable object within the Biotite ecosystem.

import biotite.structure as struc
import biotite.structure.io.xtc as xtc
import biotraj as bt
import numpy as np
import os

# 1. Create a dummy AtomArray to represent a molecule
atom1 = struc.Atom([0.0, 0.0, 0.0], atom_name="CA", res_name="ALA", chain_id="A", res_id=1, element="C")
atom2 = struc.Atom([1.0, 0.0, 0.0], atom_name="N", res_name="ALA", chain_id="A", res_id=1, element="N")

# 2. Create a 2-frame trajectory (AtomArrayStack)
trajectory_coords = np.array([
    [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]], # Frame 1
    [[0.1, 0.1, 0.1], [1.1, 0.1, 0.1]]  # Frame 2
])
traj_array = struc.AtomArray(trajectory_coords[0]) # Start with first frame's atoms
traj_array = traj_array.stack_as_trajectory(struc.AtomArrayStack(trajectory_coords))

# 3. Save the AtomArrayStack as an XTC file using Biotite's I/O
xtc_file = "dummy.xtc"
with xtc.XTCFile(xtc_file, "w") as f:
    f.write(traj_array)

# 4. Load the trajectory file using biotraj
try:
    traj = bt.load(xtc_file)
    print(f"Loaded trajectory with {traj.n_frames} frames and {traj.n_atoms} atoms.")
    print(f"First frame coordinates:\n{traj.xyz[0]}")
    print(f"Second frame coordinates:\n{traj.xyz[1]}")
except Exception as e:
    print(f"Error loading trajectory: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(xtc_file):
        os.remove(xtc_file)

view raw JSON →