Skip to main content

ciffer

PyPI Tests

Biomolecular structures as NumPy tables, ready for ML pipelines.

Every structure is three linked tables (atoms, residues, and chains) whose columns are NumPy arrays. Built on gemmi.

  • Read and write in one line. mmCIF and PDB, with models, altlocs, and assemblies chosen as you read.
  • Navigate like PyMOL. Select atoms, hop to their residues and chains, and extract what you keep.
  • Handle columns like pandas. Every column is a NumPy array, and your own columns go in with [].
  • Save once, load as is. to_bytes() keeps every column, bond, and metadata entry.

Installation

pip install ciffer

ciffer needs Python 3.11 or newer.

Usage

A first look

import ciffer

st = ciffer.fetch("1stp", assembly=True)  # from RCSB, as the biological tetramer

st.atoms.name[:4]  # ['N', 'CA', 'C', 'O']
st.atoms.xyz.shape  # (4004, 3)
len(st.atoms.bond)  # 3280

st.residues.name[:4]  # ['ASP', 'PRO', 'SER', 'LYS']
st.residues.label_seq_id[:4]  # [1, 2, 3, 4]

st.chains.label_asym_id[:3]  # ['A1', 'B1', 'C1']
st.chains.entity_type[:3]  # ['polymer', 'non-polymer', 'water']

st.metadata["resolution"]  # 2.6
st.metadata["release_date"]  # '1992-10-15'

st  # prints every column, edge, and metadata key
Output of st
<Structure atoms=4004 residues=976 chains=12>
  atoms
    name       <U3
    element    <U1
    altloc     <U1
    occupancy  float64
    b_factor   float64
    charge     int64
    xyz        float64 (3,)
    edges
      bond  3280 edges
        order     int64
        aromatic  bool
      struct_conn  0 edges
        type   <U1
        order  int64
  residues
    name          <U3
    label_seq_id  int64
    auth_seq_id   <U3
    ins_code      <U1
    comp_type     <U17
  chains
    label_asym_id  <U2
    auth_asym_id   <U2
    entity_id      <U1
    entity_type    <U11
    polymer_type   <U14
    description    <U32
  metadata
    id            '1STP'
    title         'STRUCTURAL ORIGINS OF HIGH-AFFINITY BIOTIN BINDING TO STREPTAVIDIN'
    keywords      'BIOTIN BINDING PROTEIN'
    deposit_date  '1992-03-12'
    methods       ['X-RAY DIFFRACTION']
    authors       ['Weber, P.C.', 'Salemme, F.R.']
    resolution    2.6
    release_date  '1992-10-15'
    model         1
    models        [1]
    assembly      '1'
    assemblies    ['1']

Read and write

ensemble = ciffer.fetch("1l2y", directory="data", model="all")  # cached in data/
len(ensemble)  # 38
ciffer.write(ensemble[0], "trp_cage.pdb.gz")
ciffer.read("trp_cage.pdb.gz").atoms.xyz.shape  # (304, 3)

read takes .cif, .mmcif, .pdb, and .ent, gzipped or not. fetch also takes extended ids such as pdb_00001stp. Both accept model, altloc, and assembly.

Select and navigate

Select rows with a mask, hop between levels, and extract() what you keep:

import numpy as np

biotin = st.residues[st.residues.name == "BTN"].atoms
protein = st.chains[st.chains.entity_type == "polymer"].atoms
distance = np.linalg.norm(protein.xyz[:, None] - biotin.xyz, axis=-1).min(axis=1)
pocket = protein[distance < 5].residues
pocket.name  # ['ASN', 'LEU', 'SER', 'TYR', 'SER', 'VAL', ...]
pocket.chains.auth_asym_id  # ['A1', 'A2', 'A3', 'A4']
ciffer.write(pocket.extract(), "pocket.cif")

Label and edit

Add your own column with [], select with it, and edit through the whole level:

st.atoms["pocket"] = np.isin(st.atoms.indices, pocket.atoms.indices)
ca = st.atoms[st.atoms.name == "CA"]
len(ca[ca["pocket"]])  # 72
noise = np.random.default_rng(0).normal(scale=0.5, size=(len(pocket.atoms), 3))
st.atoms.xyz[pocket.atoms.indices] += noise  # writes into the structure
# A selection such as `ca` holds copies, so `ca.xyz += 1` raises a TypeError.

Save and load

Store a structure as bytes in any database, such as SQLite, and load it back:

import sqlite3

db = sqlite3.connect("structures.db")
db.execute("CREATE TABLE IF NOT EXISTS structures (id TEXT PRIMARY KEY, data BLOB)")
db.execute("REPLACE INTO structures VALUES (?, ?)", ("1stp", st.to_bytes()))
db.commit()

(data,) = db.execute("SELECT data FROM structures WHERE id = '1stp'").fetchone()
st = ciffer.Structure.from_bytes(data)
int(st.atoms["pocket"].sum())  # 616
len(st.atoms.bond)  # 3280
st.metadata["resolution"]  # 2.6

Your column, the bonds, and the metadata all come back.

Metadata

Release files for ciffer 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ciffer 0.1.0
File Size Uploaded Provenance Actions
ciffer-0.1.0.tar.gz 549.7 kB Without provenance Details for ciffer-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ciffer 0.1.0
File Interpreter ABI Platform Actions
ciffer-0.1.0-py3-none-any.whl Python 3 none any Details for ciffer-0.1.0-py3-none-any.whl

Total release size: 592.0 kB

Release files / ciffer-0.1.0.tar.gz

Download URL ciffer-0.1.0.tar.gz
Size 549.7 kB
Tags Source
SHA-256 checksum
How to use checksums
248d7ac73365cea2f164398dd7b5ab0468f6a05c26e15ea63530026ed4048012
BLAKE2b-256 checksum
How to use checksums
89c1069ee2751a6d264800e887a95a5aa9f1c23369c65d83a823e27974cd69ef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / ciffer-0.1.0-py3-none-any.whl

Download URL ciffer-0.1.0-py3-none-any.whl
Size 42.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7ed7d746946121734242e2a6a4d7323d4e4e50c0a305f35a879828222fb6c393
BLAKE2b-256 checksum
How to use checksums
075d02a0ce3ad95ee18bb48fb5d6c4e8ff76545e945a857309ae29f6d27b9e89
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for ciffer 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page