{"id":2413,"library":"biotraj","title":"Biotraj - Trajectory File I/O for Biotite","description":"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.","status":"active","version":"1.2.2","language":"en","source_language":"en","source_url":"https://github.com/biotite/biotraj","tags":["chemistry","biology","molecular-dynamics","trajectory","biotite","file-io"],"install":[{"cmd":"pip install biotraj","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Core dependency providing molecular structure data types and C-extensions for processing.","package":"biotite","optional":false},{"reason":"Fundamental package for numerical operations and array handling.","package":"numpy","optional":false},{"reason":"Scientific computing library, often used for advanced numerical operations.","package":"scipy","optional":false}],"imports":[{"note":"Main class for representing and manipulating trajectory data.","symbol":"Trajectory","correct":"from biotraj import Trajectory"},{"note":"Convenience function to load trajectory files from disk.","symbol":"load","correct":"import biotraj as bt\ntraj = bt.load('path/to/file.xtc')"},{"note":"Similar to `load`, but can be used for specific trajectory file types (e.g., DCD, XTC).","symbol":"read_traj","correct":"import biotraj as bt\ntraj = bt.read_traj('path/to/file.dcd')"}],"quickstart":{"code":"import biotite.structure as struc\nimport biotite.structure.io.xtc as xtc\nimport biotraj as bt\nimport numpy as np\nimport os\n\n# 1. Create a dummy AtomArray to represent a molecule\natom1 = struc.Atom([0.0, 0.0, 0.0], atom_name=\"CA\", res_name=\"ALA\", chain_id=\"A\", res_id=1, element=\"C\")\natom2 = struc.Atom([1.0, 0.0, 0.0], atom_name=\"N\", res_name=\"ALA\", chain_id=\"A\", res_id=1, element=\"N\")\n\n# 2. Create a 2-frame trajectory (AtomArrayStack)\ntrajectory_coords = np.array([\n    [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]], # Frame 1\n    [[0.1, 0.1, 0.1], [1.1, 0.1, 0.1]]  # Frame 2\n])\ntraj_array = struc.AtomArray(trajectory_coords[0]) # Start with first frame's atoms\ntraj_array = traj_array.stack_as_trajectory(struc.AtomArrayStack(trajectory_coords))\n\n# 3. Save the AtomArrayStack as an XTC file using Biotite's I/O\nxtc_file = \"dummy.xtc\"\nwith xtc.XTCFile(xtc_file, \"w\") as f:\n    f.write(traj_array)\n\n# 4. Load the trajectory file using biotraj\ntry:\n    traj = bt.load(xtc_file)\n    print(f\"Loaded trajectory with {traj.n_frames} frames and {traj.n_atoms} atoms.\")\n    print(f\"First frame coordinates:\\n{traj.xyz[0]}\")\n    print(f\"Second frame coordinates:\\n{traj.xyz[1]}\")\nexcept Exception as e:\n    print(f\"Error loading trajectory: {e}\")\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(xtc_file):\n        os.remove(xtc_file)\n","lang":"python","description":"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."},"warnings":[{"fix":"Use MDTraj if full analysis functionality is required. Use biotraj only for I/O with Biotite structures.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your molecular structures are converted to biotite.structure.AtomArray or AtomArrayStack objects. Refer to Biotite's documentation for structure conversion utilities.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Replace `traj.atom_slice(indices)` with `traj.select_atoms(indices)` and assign the result to a new variable.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}