ciffer 0.1.0__tar.gz

ciffer-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,19 @@
+name: Lint
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run ty check

ciffer-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write # PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --locked
+      - run: uv run pytest
+      - run: uv build
+      - run: uv publish

ciffer-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: Test
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run pytest

ciffer-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.venv

ciffer-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --no-sync ruff check --fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: ruff-format
+        name: ruff format
+        entry: uv run --no-sync ruff format
+        language: system
+        types_or: [python, pyi, markdown]
+        require_serial: true
+      - id: ty
+        name: ty check
+        entry: uv run --no-sync ty check
+        language: system
+        types_or: [python, pyi]
+        pass_filenames: false

ciffer-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

ciffer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Howon Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ciffer-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.5
+Name: ciffer
+Version: 0.1.0
+Summary: Biomolecular structures as NumPy tables, ready for ML pipelines.
+Project-URL: Repository, https://github.com/Buddha7771/ciffer
+Project-URL: Issues, https://github.com/Buddha7771/ciffer/issues
+Author-email: Howon Lee <hwlee7771@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: machine-learning,mmcif,numpy,pdb,protein,structure
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: gemmi>=0.7.5
+Requires-Dist: numpy>=2.2
+Requires-Dist: zstandard>=0.25.0
+Description-Content-Type: text/markdown
+
+# ciffer
+
+[![PyPI](https://img.shields.io/pypi/v/ciffer)](https://pypi.org/project/ciffer/) [![Tests](https://github.com/Buddha7771/ciffer/actions/workflows/test.yml/badge.svg)](https://github.com/Buddha7771/ciffer/actions/workflows/test.yml)
+
+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](https://github.com/project-gemmi/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
+
+```sh
+pip install ciffer
+```
+
+ciffer needs Python 3.11 or newer.
+
+## Usage
+
+### A first look
+
+```python
+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
+```
+
+<details>
+<summary>Output of <code>st</code></summary>
+
+```text
+<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']
+```
+
+</details>
+
+### Read and write
+
+```python
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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.

ciffer-0.1.0/README.md

@@ -0,0 +1,156 @@
+# ciffer
+
+[![PyPI](https://img.shields.io/pypi/v/ciffer)](https://pypi.org/project/ciffer/) [![Tests](https://github.com/Buddha7771/ciffer/actions/workflows/test.yml/badge.svg)](https://github.com/Buddha7771/ciffer/actions/workflows/test.yml)
+
+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](https://github.com/project-gemmi/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
+
+```sh
+pip install ciffer
+```
+
+ciffer needs Python 3.11 or newer.
+
+## Usage
+
+### A first look
+
+```python
+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
+```
+
+<details>
+<summary>Output of <code>st</code></summary>
+
+```text
+<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']
+```
+
+</details>
+
+### Read and write
+
+```python
+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:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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.

ciffer-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "ciffer"
+version = "0.1.0"
+description = "Biomolecular structures as NumPy tables, ready for ML pipelines."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Howon Lee", email = "hwlee7771@gmail.com" }]
+keywords = ["mmcif", "pdb", "protein", "structure", "numpy", "machine-learning"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Typing :: Typed",
+]
+dependencies = ["gemmi>=0.7.5", "numpy>=2.2", "zstandard>=0.25.0"]
+
+[project.urls]
+Repository = "https://github.com/Buddha7771/ciffer"
+Issues = "https://github.com/Buddha7771/ciffer/issues"
+
+[dependency-groups]
+dev = ["pre-commit>=4.6", "pytest>=9.0.3", "ruff==0.17.0", "ty==0.0.88"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ciffer"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["ALL"]
+extend-select = [
+  "D417",
+] # Disabled by the numpy convention; keep Parameters complete
+ignore = [
+  "COM812",  # Conflicts with ruff formatter
+  "CPY001",  # Missing copyright notice
+  "D100",    # Missing docstring in public module
+  "D104",    # Missing docstring in public package
+  "ANN401",  # Dynamically typed expressions (typing.Any)
+  "PLR0913", # Too many arguments in function definition
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["ANN201", "D", "INP001", "PLR2004", "S101"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ciffer-0.1.0/src/ciffer/__init__.py

@@ -0,0 +1,21 @@
+from .cif import fetch, read, write
+from .structure import Structure, concat
+from .table import EdgeList, Table
+from .view import AtomView, Bond, ChainView, Level, ResidueView, StructConn, View
+
+__all__ = [
+    "AtomView",
+    "Bond",
+    "ChainView",
+    "EdgeList",
+    "Level",
+    "ResidueView",
+    "StructConn",
+    "Structure",
+    "Table",
+    "View",
+    "concat",
+    "fetch",
+    "read",
+    "write",
+]