molscene 0.2.0

PDB/mmCIF file parsing using pandas DataFrames

MolScene

Molecular structures as pandas DataFrames.

MolScene reads molecular structures (PDB, mmCIF) into pandas DataFrames and writes them back out (PDB, mmCIF, GRO). Every Scene is a DataFrame so the full pandas toolbox (filtering, grouping, plotting, to_csv, etc.) works out of the box. MolScene adds a layer on top for molecular structural data operations: atom selection, rigid-body transformations and alignment, residue morphing, multi-frame trajectories, and distance maps.

from molscene import Scene

s = Scene.from_pdb("1jge.pdb")          # load a structure into a DataFrame
ca = s.select("chain A and name CA")    # VMD-style atom selection
ca = ca - ca.get_center()               # center it on the origin (operator math)
ca.write_pdb("ca_centered.pdb")         # write it back out

Why use MolScene?

• Just a DataFrame. Scene subclasses pandas.DataFrame, so columns like chain, resid, resname, name, x, y, z are all there to slice, group, and analyze with common data analysis tools.
• Atom selection. Use a familiar VMD-style string ("protein and within 5 of resname HEM") via the optional molselect engine, or plain keyword filters (s.select(chain=["A"], name=["CA"])) with no extra dependencies.
• Geometry reads like math. +, -, *, / translate, scale, and reflect coordinates; scene1 + scene2 concatenates two structures.
• Built-in structural alignment Pair atoms by order, by columns, or by sequence (Needleman–Wunsch), then superpose, compute rmsd, or get a Transformation (rotation + translation).
• Smooth morphing and trajectories. Interpolate between conformations with screw-linear (dual-quaternion) or slerp motion, and carry multiple coordinate frames per scene.
• Metadata travels with the data. Attach arbitrary metadata to a scene, like bonds, angles or dihedrals, that depend on atom indices; it is preserved through selections and transformations.

Installation

pip install molscene

String atom selection (Scene.select("chain A and resid 1 to 100")) is powered by the optional molselect package. Install it with the extra:

pip install "molscene[selection]"

The keyword form Scene.select(chain=["A"]) works without it.

Conda: a conda-forge recipe lives in recipe/; conda install support will follow once the package is published to conda-forge.

Quickstart

import numpy as np
from molscene import Scene

# Load from a file (format auto-detected by from_file, or use from_pdb/from_cif/from_gro)
s = Scene.from_pdb("1jge.pdb")

# It's a DataFrame — use pandas directly
print(s["resname"].value_counts())
print(len(s), "atoms")

# Select atoms (string needs molscene[selection]; kwargs always work)
backbone = s.select("name CA C N O")
chain_a  = s.select(chain=["A"])

# Geometry with operators
centered = s - s.get_center()
shifted  = s + np.array([10, 0, 0])
scaled   = s * 2.0

# Align one structure onto another and measure RMSD
mobile = Scene.from_pdb("model.pdb")
ref    = Scene.from_pdb("native.pdb")
aligned = mobile.superpose(ref, match="sequence")
print(aligned.rmsd(ref, match="sequence"))

# Write back out (format from extension)
centered.write_pdb("centered.pdb")

See the full documentation for the User Guide (with API reference) and Developer Guide.

Documentation

• Getting Started: installation and first steps
• User Guide: full API reference
• Examples
• Developer Guide

Build the docs locally with:

pip install "molscene[docs]"
sphinx-build -b html docs docs/_build/html

Contributing

Contributions are welcome — see .github/CONTRIBUTING.md and the Code of Conduct. Run the test suite with:

pip install "molscene[test,selection]"
pytest molscene/tests/

License

MIT — see LICENSE.

Copyright

Copyright (c) 2025-2026, Carlos Bueno

Acknowledgements

Project skeleton based on the Computational Molecular Science Python Cookiecutter version 1.10.