debase 0.1.0__py3-none-any.whl

debase/PIPELINE_FLOW.md

@@ -0,0 +1,100 @@
+# DEBase Pipeline Flow
+
+## Overview
+The DEBase pipeline extracts enzyme engineering data from chemistry papers through a series of modular steps.
+
+## Pipeline Architecture
+
+```
+┌─────────────────────┐     ┌─────────────────────┐
+│   Manuscript PDF    │     │       SI PDF        │
+└──────────┬──────────┘     └──────────┬──────────┘
+           │                           │
+           └───────────┬───────────────┘
+                       │
+                       ▼
+         ┌─────────────────────────────┐
+         │ 1. enzyme_lineage_extractor │
+         │   - Extract enzyme variants │
+         │   - Parse mutations         │
+         │   - Get basic metadata      │
+         └─────────────┬───────────────┘
+                       │
+                       ▼
+         ┌─────────────────────────────┐
+         │    2. cleanup_sequence      │
+         │   - Validate sequences      │
+         │   - Fix formatting issues   │
+         │   - Generate full sequences │
+         └─────────────┬───────────────┘
+                       │
+           ┌───────────┴───────────────┐
+           │                           │
+           ▼                           ▼
+┌─────────────────────────┐ ┌─────────────────────────┐
+│ 3a. reaction_info       │ │ 3b. substrate_scope     │
+│     _extractor          │ │     _extractor          │
+│ - Performance metrics   │ │ - Substrate variations  │
+│ - Model reaction        │ │ - Additional variants   │
+│ - Conditions            │ │ - Scope data            │
+└───────────┬─────────────┘ └───────────┬─────────────┘
+            │                           │
+            └───────────┬───────────────┘
+                        │
+                        ▼
+          ┌─────────────────────────────┐
+          │    4. lineage_format_o3     │
+          │   - Merge all data          │
+          │   - Fill missing sequences  │
+          │   - Format final output     │
+          └─────────────┬───────────────┘
+                        │
+                        ▼
+                ┌─────────────┐
+                │ Final CSV   │
+                └─────────────┘
+```
+
+## Module Details
+
+### 1. enzyme_lineage_extractor.py
+- **Input**: Manuscript PDF, SI PDF
+- **Output**: CSV with enzyme variants and mutations
+- **Function**: Extracts enzyme identifiers, mutation lists, and basic metadata
+
+### 2. cleanup_sequence.py  
+- **Input**: Enzyme lineage CSV
+- **Output**: CSV with validated sequences
+- **Function**: Validates protein sequences, generates full sequences from mutations
+
+### 3a. reaction_info_extractor.py
+- **Input**: PDFs + cleaned enzyme CSV
+- **Output**: CSV with reaction performance data
+- **Function**: Extracts yield, TTN, selectivity, reaction conditions
+
+### 3b. substrate_scope_extractor.py
+- **Input**: PDFs + cleaned enzyme CSV  
+- **Output**: CSV with substrate scope entries
+- **Function**: Extracts substrate variations tested with different enzymes
+
+### 4. lineage_format_o3.py
+- **Input**: Reaction CSV + Substrate scope CSV
+- **Output**: Final formatted CSV
+- **Function**: Merges data, fills missing sequences, applies consistent formatting
+
+## Key Features
+
+1. **Modular Design**: Each step can be run independently
+2. **Parallel Extraction**: Steps 3a and 3b run independently 
+3. **Error Recovery**: Pipeline can resume from any step
+4. **Clean Interfaces**: Each module has well-defined inputs/outputs
+
+## Usage
+
+```bash
+# Full pipeline
+python -m debase.wrapper_clean manuscript.pdf --si si.pdf --output results.csv
+
+# With intermediate files kept for debugging  
+python -m debase.wrapper_clean manuscript.pdf --si si.pdf --keep-intermediates
+```

debase/__init__.py

@@ -0,0 +1,18 @@
+"""DEBase - Enzyme lineage analysis and sequence extraction package."""
+
+from ._version import __version__
+
+from .enzyme_lineage_extractor import run_pipeline as extract_lineage
+from .cleanup_sequence import main as cleanup_sequences
+from .reaction_info_extractor import ReactionExtractor
+from .substrate_scope_extractor import run_pipeline as extract_substrate_scope
+from .lineage_format import run_pipeline as format_lineage
+
+__all__ = [
+    "__version__",
+    "extract_lineage",
+    "cleanup_sequences",
+    "ReactionExtractor",
+    "extract_substrate_scope",
+    "format_lineage",
+]

debase/__main__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+"""
+Command-line interface for the DEBase enzyme analysis pipeline.
+"""
+
+from .wrapper import main
+
+if __name__ == "__main__":
+    main()

debase/_version.py

@@ -0,0 +1,3 @@
+"""Version information."""
+
+__version__ = "0.1.0"

debase/build_db.py

@@ -0,0 +1,190 @@
+"""
+Build an IUPAC/Synonym -> SMILES SQLite database from PubChem
+and fall back to OPSIN for names not found locally.
+
+New in this version
+-------------------
+- Downloads and ingests CID-Synonym-filtered.gz
+- Adds a simple opsin_lookup() fallback
+- locate_db() helper so user code can find the DB
+
+Usage
+-----
+python build_db.py        # one-time build (3-4 GB disk, <6 GB RAM)
+python -m i2s "ethyl 2-(dimethyl(p-tolyl)silyl)propanoate"
+"""
+
+from __future__ import annotations
+import gzip, sqlite3, urllib.request, pathlib, sys, subprocess, shutil, os
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# 0.  Where to keep big files?
+# ---------------------------------------------------------------------------
+# Use local data directory in the project
+DATA_DIR      = pathlib.Path(__file__).parent.parent.parent / "data"
+DL_DIR        = DATA_DIR / "pubchem"
+DB_PATH       = DATA_DIR / "iupac2smiles.db"
+
+BASE = "https://ftp.ncbi.nlm.nih.gov/pubchem/Compound/Extras/"
+FILES = {
+    "CID-IUPAC.gz"           : "cid_iupac.gz",
+    "CID-SMILES.gz"          : "cid_smiles.gz",
+    "CID-Synonym-filtered.gz": "cid_synonym.gz",   # NEW
+}
+
+# ---------------------------------------------------------------------------
+# 1.  Download
+# ---------------------------------------------------------------------------
+def download_all() -> None:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    DL_DIR.mkdir(parents=True, exist_ok=True)
+    for remote, local_name in FILES.items():
+        local = DL_DIR / local_name
+        if not local.exists():
+            print(f"Downloading {remote}")
+            urllib.request.urlretrieve(BASE + remote, local)
+        else:
+            print(f"[OK] {local_name} already present")
+
+# ---------------------------------------------------------------------------
+# 2.  Build DB (streaming, memory-safe)
+# ---------------------------------------------------------------------------
+def build_sqlite() -> None:
+    db = sqlite3.connect(DB_PATH)
+    c  = db.cursor()
+    c.executescript("""
+        PRAGMA journal_mode = OFF;
+        PRAGMA synchronous   = OFF;
+        CREATE TABLE IF NOT EXISTS x(
+            name   TEXT PRIMARY KEY,   -- lower-case
+            smiles TEXT NOT NULL
+        );
+    """)
+
+    # 2a.  SMILES lookup dict  (CID -> SMILES)   ~1.3 GB -> <1 GB RAM
+    print("Loading SMILES...")
+    cid2smiles: dict[str, str] = {}
+    with gzip.open(DL_DIR / "cid_smiles.gz", "rt", encoding="utf-8") as f:
+        for line in f:
+            cid, smiles = line.rstrip("\n").split("\t")
+            cid2smiles[cid] = smiles
+
+    # helper to flush batches
+    batch: list[tuple[str, str]] = []
+    def canonicalize(name: str) -> str:
+        """Canonicalize name: lowercase, strip, collapse spaces"""
+        return ' '.join(name.lower().split())
+    
+    def flush():
+        if batch:
+            c.executemany("INSERT OR IGNORE INTO x VALUES(?,?)", batch)
+            db.commit()
+            batch.clear()
+
+    # 2b.  IUPAC table
+    print("Merging IUPAC...")
+    with gzip.open(DL_DIR / "cid_iupac.gz", "rt", encoding="utf-8") as f:
+        for n, line in enumerate(f, 1):
+            cid, iupac = line.rstrip("\n").split("\t")
+            smiles = cid2smiles.get(cid)
+            if smiles:
+                batch.append((canonicalize(iupac), smiles))
+            if len(batch) == 100_000:
+                flush()
+                print(f"   ... {n:,} IUPAC rows", end="\r")
+    flush()
+
+    # 2c.  Synonyms table  **NEW**
+    print("\nAdding synonyms...")
+    with gzip.open(DL_DIR / "cid_synonym.gz", "rt", encoding="utf-8") as f:
+        for n, line in enumerate(f, 1):
+            cid, syn = line.rstrip("\n").split("\t")
+            smiles = cid2smiles.get(cid)
+            if smiles:
+                batch.append((canonicalize(syn), smiles))
+            if len(batch) == 100_000:
+                flush()
+                if n % 1_000_000 == 0:
+                    print(f"   ... {n:,} synonym rows", end="\r")
+    flush()
+
+    c.execute("CREATE INDEX IF NOT EXISTS idx_name ON x(name);")
+    db.commit()
+    print("Build complete")
+    db.close()
+
+# ---------------------------------------------------------------------------
+# 3.  Lookup helpers
+# ---------------------------------------------------------------------------
+def locate_db(explicit: Optional[str] = None) -> pathlib.Path:
+    """Return path to SQLite DB, or raise FileNotFoundError."""
+    for p in (
+        pathlib.Path(explicit) if explicit else None,
+        DB_PATH,  # Primary location in project data folder
+        pathlib.Path.cwd() / "data" / "iupac2smiles.db",
+        pathlib.Path.home() / ".iupac2smiles.db",
+    ):
+        if p and p.exists():
+            return p
+    raise FileNotFoundError("iupac2smiles.db not found; run build_db.py")
+
+def sqlite_lookup(name: str, db_path: pathlib.Path | str = DB_PATH) -> Optional[str]:
+    # Canonicalize: lowercase, strip, collapse multiple spaces
+    canonical = ' '.join(name.lower().split())
+    with sqlite3.connect(db_path) as db:
+        row = db.execute("SELECT smiles FROM x WHERE name = ?", (canonical,)).fetchone()
+        return row[0] if row else None
+
+# ---------------------------------------------------------------------------
+# 4.  OPSIN fallback  **NEW**
+# ---------------------------------------------------------------------------
+def check_opsin_available() -> bool:
+    return shutil.which("opsin") is not None    # expects 'opsin' on PATH
+
+def opsin_lookup(name: str) -> Optional[str]:
+    """
+    Convert an IUPAC name to SMILES via OPSIN CLI.
+    Install with:  brew install opsin   (macOS) or
+                   conda install -c conda-forge opsin or
+                   download JAR: https://opsin.ch.cam.ac.uk
+    """
+    if not check_opsin_available():
+        return None
+    try:
+        # OPSIN reads from stdin and outputs SMILES by default
+        res = subprocess.run(
+            ["opsin"],
+            input=name,
+            capture_output=True, text=True, check=True, timeout=10,
+        )
+        smiles = res.stdout.strip()
+        return smiles or None
+    except subprocess.SubprocessError:
+        return None
+
+def iupac_to_smiles(name: str, db_path: pathlib.Path | str | None = None) -> Optional[str]:
+    db_path = locate_db(db_path) if db_path else locate_db()
+    smi = sqlite_lookup(name, db_path)
+    if smi:
+        return smi
+    # try OPSIN
+    return opsin_lookup(name)
+
+# ---------------------------------------------------------------------------
+# 5.  CLI helper
+# ---------------------------------------------------------------------------
+if __name__ == "__main__":
+    if len(sys.argv) == 1:
+        print("Usage:")
+        print("  build_db.py download      # fetch PubChem files")
+        print("  build_db.py build         # create SQLite")
+        print("  python -m i2s NAME        # (see below)")
+    elif sys.argv[1] == "download":
+        download_all()
+    elif sys.argv[1] == "build":
+        build_sqlite()
+    else:
+        # act like a tiny module:  python build_db.py "acetylsalicylic acid"
+        q = " ".join(sys.argv[1:])
+        print(iupac_to_smiles(q) or "Not found")