scigantic-bindingdb 0.2.0__py3-none-any.whl

scigantic_bindingdb/__init__.py

@@ -0,0 +1,41 @@
+"""Query BindingDB directly from a public S3 mirror. No download, no local database."""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+from .cache import cache_dir, disable_cache, enable_cache, is_cache_enabled
+from .cache import resolve as cache_resolve
+from .chembl_bridge import chembl_bridge
+from .connection import connect, query
+from .dti_pairs import dti_pairs
+from .measurements import measurements
+from .releases import (
+    ReleaseCapabilityError,
+    ReleaseInfo,
+    UnknownReleaseError,
+    latest,
+    releases,
+)
+
+try:
+    __version__ = _version("scigantic-bindingdb")
+except PackageNotFoundError:
+    # Running from a source checkout with no install (editable or not).
+    __version__ = "0.0.0"
+
+__all__ = [
+    "chembl_bridge",
+    "connect",
+    "query",
+    "measurements",
+    "dti_pairs",
+    "releases",
+    "latest",
+    "enable_cache",
+    "disable_cache",
+    "is_cache_enabled",
+    "cache_dir",
+    "cache_resolve",
+    "ReleaseInfo",
+    "ReleaseCapabilityError",
+    "UnknownReleaseError",
+]

scigantic_bindingdb/__main__.py

@@ -0,0 +1,8 @@
+"""Enables `python -m scigantic_bindingdb`, same commands as the `scigantic-bindingdb` console script."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

scigantic_bindingdb/_constants.py

@@ -0,0 +1,7 @@
+"""Shared constants: where the mirror lives."""
+
+BUCKET = "scigantic-bindingdb"
+REGION = "us-east-1"
+
+# The scigantic-chembl mirror this package's chembl_bridge() cross-references.
+CHEMBL_BUCKET = "scigantic-chembl"

scigantic_bindingdb/cache.py

@@ -0,0 +1,113 @@
+"""Optional local caching: download once, then work with no network.
+
+Off by default. This package's whole pitch is zero setup, so caching stays
+opt-in rather than something that changes the default behavior:
+
+    import scigantic_bindingdb as bindingdb
+    bindingdb.enable_cache()
+
+chembl_bridge() then reads its one derived file from a local cache directory
+instead of S3, downloading it the first time it's needed and reusing it
+after that.
+
+connect() / query() / measurements() deliberately do NOT use this:
+connect() registers five core tables as views on every call, so caching
+them there would mean any call eagerly downloads everything regardless of
+what the query actually touches. Cache a specific table yourself if you
+want it locally: cache_resolve("<release>/parquet/<table>.parquet")
+downloads it and returns the local path, usable directly in
+read_parquet(...).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import urllib.request
+from pathlib import Path
+
+from ._constants import BUCKET, REGION
+
+_enabled = False
+_cache_dir: Path | None = None
+
+_CHUNK_BYTES = 1024 * 1024
+
+
+def _default_cache_dir() -> Path:
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+    elif sys.platform == "darwin":
+        base = str(Path.home() / "Library" / "Caches")
+    else:
+        base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "scigantic-bindingdb"
+
+
+def enable_cache(cache_dir: str | None = None) -> Path:
+    """Turn on local caching for every function in this package that uses it.
+
+    Cache location: `cache_dir` if given, else the
+    SCIGANTIC_BINDINGDB_CACHE environment variable, else a
+    platform-appropriate user cache directory. Returns the resolved
+    directory.
+    """
+    global _enabled, _cache_dir
+    if cache_dir is not None:
+        resolved = Path(cache_dir)
+    elif os.environ.get("SCIGANTIC_BINDINGDB_CACHE"):
+        resolved = Path(os.environ["SCIGANTIC_BINDINGDB_CACHE"])
+    else:
+        resolved = _default_cache_dir()
+    resolved.mkdir(parents=True, exist_ok=True)
+    _cache_dir = resolved
+    _enabled = True
+    return resolved
+
+
+def disable_cache() -> None:
+    """Turn caching back off. Later calls go straight to S3 again.
+
+    Anything already downloaded stays on disk; this only stops using it.
+    """
+    global _enabled
+    _enabled = False
+
+
+def is_cache_enabled() -> bool:
+    return _enabled
+
+
+def cache_dir() -> Path | None:
+    """The resolved cache directory, or None if caching has never been enabled."""
+    return _cache_dir
+
+
+def resolve(key: str) -> str:
+    """An S3 URL, or a local cached file path if caching is on.
+
+    `key` is a path relative to the bucket root, e.g.
+    "202608/derived/bindingdb_chembl_bridge.parquet". Downloads to the
+    cache on first access; later calls for the same key reuse the local
+    file without touching the network.
+    """
+    if not _enabled:
+        return f"s3://{BUCKET}/{key}"
+
+    assert _cache_dir is not None
+    local_path = _cache_dir / key
+    if local_path.exists():
+        return str(local_path)
+
+    local_path.parent.mkdir(parents=True, exist_ok=True)
+    url = f"https://{BUCKET}.s3.{REGION}.amazonaws.com/{key}"
+    # Download to a sibling temp file and rename into place atomically, so a
+    # download killed partway through never leaves a file that looks cached
+    # but isn't.
+    tmp_path = local_path.with_name(local_path.name + ".part")
+    print(f"scigantic-bindingdb: caching {key} ...", file=sys.stderr, flush=True)
+    with urllib.request.urlopen(url) as response, open(tmp_path, "wb") as fh:
+        while chunk := response.read(_CHUNK_BYTES):
+            fh.write(chunk)
+    os.replace(tmp_path, local_path)
+    return str(local_path)

scigantic_bindingdb/chembl_bridge.py

@@ -0,0 +1,87 @@
+"""Cross-reference BindingDB measurements to ChEMBL, through the precomputed
+bridge table rather than re-deriving the join yourself.
+
+BindingDB ingests ChEMBL as one of its own curated source feeds (51.3% of
+measurements in the 202608 release), and ChEMBL separately absorbs some
+BindingDB patent-derived bioactivity data, so the two archives are not
+independent corpora. derived/bindingdb_chembl_bridge.parquet, built once at
+mirror time, joins measurements to s3://scigantic-chembl by BindingDB's own
+chembl_id column where present (authoritative) and falls back to an exact
+InChIKey match where it's missing. This module wraps that file, and
+optionally reaches into the live scigantic-chembl mirror over the same
+DuckDB connection for compound/target names: a read-only cross-bucket SQL
+join at query time, not a mount-level dependency between the two archives.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._constants import CHEMBL_BUCKET
+from .cache import resolve as _resolve
+from .connection import connect
+from .releases import _require, latest
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+def chembl_bridge(
+    release: str | None = None,
+    chembl_release: str = "chembl_37",
+    reactant_set_id: str | None = None,
+    with_names: bool = True,
+    limit: int | None = None,
+) -> "pd.DataFrame":
+    """BindingDB measurements joined to their ChEMBL cross-reference.
+
+    with_names (default True) also pulls in compound_chembl_id's pref_name
+    from s3://scigantic-chembl/<chembl_release>, a second public bucket read
+    over the same connection. Set False to skip that join and get just the
+    bridge table's own columns (reactant_set_id, chembl_molregno, chembl_id,
+    match_method) plus the measurement's SMILES.
+
+    release defaults to the manifest's current latest(). Only that release
+    is guaranteed to carry the bridge table; call releases() to check.
+    """
+    release = release or latest()
+    _require(release, "chembl_bridge")
+    con = connect(release)
+    try:
+        bridge_path = _resolve(f"{release}/derived/bindingdb_chembl_bridge.parquet")
+        con.execute(
+            "CREATE OR REPLACE VIEW chembl_bridge AS "
+            f"SELECT * FROM read_parquet('{bridge_path}')"
+        )
+
+        where: list[str] = []
+        params: list[str | int] = []
+        if reactant_set_id is not None:
+            where.append("b.reactant_set_id = ?")
+            params.append(reactant_set_id)
+        clause = f"WHERE {' AND '.join(where)}" if where else ""
+
+        if with_names:
+            mol_dict = f"s3://{CHEMBL_BUCKET}/{chembl_release}/parquet/molecule_dictionary.parquet"
+            sql = f"""
+                SELECT b.reactant_set_id, b.chembl_molregno, b.chembl_id, b.match_method,
+                       m.ligand_smiles, d.pref_name AS chembl_pref_name
+                FROM chembl_bridge b
+                JOIN measurements m ON m.reactant_set_id = b.reactant_set_id
+                LEFT JOIN read_parquet('{mol_dict}') d ON d.molregno = b.chembl_molregno
+                {clause}
+            """
+        else:
+            sql = f"""
+                SELECT b.reactant_set_id, b.chembl_molregno, b.chembl_id, b.match_method,
+                       m.ligand_smiles
+                FROM chembl_bridge b
+                JOIN measurements m ON m.reactant_set_id = b.reactant_set_id
+                {clause}
+            """
+        if limit is not None:
+            sql += " LIMIT ?"
+            params.append(int(limit))
+        return con.execute(sql, params).df()
+    finally:
+        con.close()

scigantic_bindingdb/cli.py

@@ -0,0 +1,55 @@
+"""Command-line interface: `scigantic-bindingdb info` and `scigantic-bindingdb query`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Sequence, cast
+
+from .connection import query as run_query
+from .releases import releases
+
+
+def _cmd_info(_args: argparse.Namespace) -> int:
+    for info in releases():
+        derived = [
+            name
+            for name, present in (
+                ("chembl_bridge", info.chembl_bridge),
+                ("dti_pairs", info.dti_pairs),
+            )
+            if present
+        ]
+        suffix = f" + {', '.join(derived)}" if derived else " (raw tables only)"
+        print(f"{info.release}{suffix}")
+    return 0
+
+
+def _cmd_query(args: argparse.Namespace) -> int:
+    df = run_query(args.sql, release=args.release)
+    print(df.to_csv(sep="\t", index=False), end="")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="scigantic-bindingdb")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    info_parser = subparsers.add_parser(
+        "info", help="list mirrored releases and what each one supports"
+    )
+    info_parser.set_defaults(func=_cmd_info)
+
+    query_parser = subparsers.add_parser(
+        "query", help="run SQL against a release and print tab-separated output"
+    )
+    query_parser.add_argument("sql")
+    query_parser.add_argument("--release", default=None, help="defaults to the current release")
+    query_parser.set_defaults(func=_cmd_query)
+
+    args = parser.parse_args(argv)
+    return cast(int, args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scigantic_bindingdb/connection.py

@@ -0,0 +1,84 @@
+"""DuckDB connection helpers. Queries run against the public S3 mirror over
+httpfs, no download.
+
+This module deliberately does not participate in enable_cache() (see
+cache.py): connect() registers all five core tables as views on every call,
+the largest over 200 MB, so caching them here would mean any call to
+connect() or query() eagerly downloads everything regardless of what the
+query actually touches. Caching applies to chembl_bridge() instead, which
+needs exactly one known file.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._constants import BUCKET, REGION
+from .releases import _validate_release, latest
+
+if TYPE_CHECKING:
+    import duckdb
+    import pandas as pd
+
+# Registered as views on connect() so plain SQL can reference a table by
+# name instead of a full read_parquet() path.
+_CORE_TABLES = (
+    "measurements",
+    "target_chains",
+    "target_chain_names",
+    "assays",
+    "id_mappings",
+)
+
+
+def connect(release: str | None = None) -> "duckdb.DuckDBPyConnection":
+    """Open a DuckDB connection against s3://scigantic-bindingdb.
+
+    `SELECT * FROM measurements` works directly; any other table under
+    `<release>/parquet/` is reachable with
+    `read_parquet('s3://scigantic-bindingdb/<release>/parquet/<table>.parquet')`.
+
+    release defaults to whatever the live manifest currently calls latest(),
+    resolved at call time rather than import time.
+    """
+    import duckdb
+
+    release = release or latest()
+    _validate_release(release)
+
+    con = duckdb.connect()
+    # DuckDB auto-shows an ASCII progress bar for queries it estimates will
+    # take a while, on stdout, regardless of whether that's a real terminal.
+    # Surprising output for a library call in a notebook or script, so it's
+    # off here by default.
+    con.execute("SET enable_progress_bar=false")
+    con.execute("INSTALL httpfs")
+    con.execute("LOAD httpfs")
+    con.execute(f"SET s3_region='{REGION}'")
+    # The mirror is public-read. Without this, DuckDB looks for AWS
+    # credentials and fails on a machine that has none configured.
+    con.execute(
+        "CREATE OR REPLACE SECRET scigantic_bindingdb "
+        "(TYPE s3, PROVIDER config, KEY_ID '', SECRET '')"
+    )
+
+    base = f"s3://{BUCKET}/{release}/parquet"
+    for table in _CORE_TABLES:
+        con.execute(
+            f"CREATE OR REPLACE VIEW {table} AS "
+            f"SELECT * FROM read_parquet('{base}/{table}.parquet')"
+        )
+    return con
+
+
+def query(sql: str, release: str | None = None) -> "pd.DataFrame":
+    """Run SQL against a release and return a pandas DataFrame.
+
+    Opens a new connection per call. For several queries against the same
+    release, call connect() once and reuse it instead.
+    """
+    con = connect(release)
+    try:
+        return con.execute(sql).df()
+    finally:
+        con.close()

scigantic_bindingdb/dti_pairs.py

@@ -0,0 +1,74 @@
+"""(Ligand, target, affinity) triples, ready for a drug-target-interaction
+or proteochemometric model to train on.
+
+BindingDB is the dataset most DTI tooling (DeepPurpose and similar) is built
+around, specifically because it ships a full protein sequence alongside
+every affinity measurement, something ChEMBL's bioactivity tables don't
+do as directly. This wraps derived/dti_pairs.parquet, the pre-filtered,
+pre-transformed version of that pairing: exact measurements only (a
+censored ">"/"<" bound is never a usable regression label), chain 1's
+sequence required, and p_affinity already computed as -log10(affinity_nm *
+1e-9), the same transform as ChEMBL's pchembl_value.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from .cache import resolve as _resolve
+from .connection import connect
+from .releases import _require, latest
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+Endpoint = Literal["ki", "ic50", "kd", "ec50"]
+
+
+def dti_pairs(
+    release: str | None = None,
+    endpoint: Endpoint | None = None,
+    uniprot_id: str | None = None,
+    single_chain_only: bool = False,
+    limit: int | None = None,
+) -> "pd.DataFrame":
+    """Ligand/target/affinity triples for DTI or proteochemometric training.
+
+    endpoint filters to one of 'ki', 'ic50', 'kd', 'ec50'; omit to get all
+    four (a row's `endpoint` column says which).
+
+    single_chain_only=True drops rows whose target came from a complex with
+    more than one declared chain (n_chains_declared > 1). Those rows still
+    represent the interaction with chain 1's sequence only, which is fine
+    for most uses, but exclude them if single-chain purity matters for your
+    model.
+
+    release defaults to the manifest's current latest(). Only that release
+    is guaranteed to carry this file; call releases() to check.
+    """
+    release = release or latest()
+    _require(release, "dti_pairs")
+    con = connect(release)
+    try:
+        path = _resolve(f"{release}/derived/dti_pairs.parquet")
+        con.execute(f"CREATE OR REPLACE VIEW dti_pairs AS SELECT * FROM read_parquet('{path}')")
+
+        where: list[str] = []
+        params: list[str | int] = []
+        if endpoint is not None:
+            where.append("endpoint = ?")
+            params.append(endpoint)
+        if uniprot_id is not None:
+            where.append("uniprot_id = ?")
+            params.append(uniprot_id)
+        if single_chain_only:
+            where.append("n_chains_declared = 1")
+        clause = f"WHERE {' AND '.join(where)}" if where else ""
+
+        sql = f"SELECT * FROM dti_pairs {clause} ORDER BY p_affinity DESC"
+        if limit is not None:
+            sql += " LIMIT ?"
+            params.append(int(limit))
+        return con.execute(sql, params).df()
+    finally:
+        con.close()

scigantic_bindingdb/measurements.py

@@ -0,0 +1,79 @@
+"""Binding measurements, filtered the way that avoids BindingDB's two
+sharpest edges: censored affinity values, and target joins that fan out on
+multichain complexes.
+
+Ki/IC50/Kd/EC50 are occasionally reported as ">X" or "<X" rather than an
+exact value (an assay hit its ceiling or floor). exact_only=True, the
+default, keeps only rows where that endpoint's qualifier is '=', so a
+censored bound is never silently treated as a real affinity.
+
+Filtering by target uses EXISTS against target_chains rather than a JOIN,
+so a target whose UniProt ID appears on more than one chain of the same
+complex still returns each measurement once, not once per matching chain.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from .connection import connect
+from .releases import latest
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+Endpoint = Literal["ki", "ic50", "kd", "ec50"]
+_ENDPOINTS: tuple[Endpoint, ...] = ("ki", "ic50", "kd", "ec50")
+
+
+def measurements(
+    release: str | None = None,
+    uniprot_id: str | None = None,
+    endpoint: Endpoint = "ki",
+    exact_only: bool = True,
+    limit: int | None = None,
+) -> "pd.DataFrame":
+    """Binding measurements for one endpoint, most potent first.
+
+    uniprot_id matches either UniProt (SwissProt or TrEMBL) primary ID on
+    any chain of the target. A multichain complex needs the accession on
+    only one chain to match, and matches once regardless of how many chains
+    it appears on.
+
+    exact_only (default True) keeps only rows where this endpoint's
+    qualifier is '='. Set False to also see censored ">"/"<" bounds,
+    which come back with their qualifier column intact rather than a bare
+    number that looks exact but isn't.
+
+    release defaults to the manifest's current latest().
+    """
+    if endpoint not in _ENDPOINTS:
+        raise ValueError(f"endpoint must be one of {_ENDPOINTS}, got {endpoint!r}")
+    release = release or latest()
+    value_col, qual_col = f"{endpoint}_nm_value", f"{endpoint}_nm_qualifier"
+
+    con = connect(release)
+    try:
+        where: list[str] = [f"{value_col} IS NOT NULL"]
+        params: list[str | int] = []
+        if exact_only:
+            where.append(f"{qual_col} = '='")
+        if uniprot_id is not None:
+            where.append(
+                "EXISTS (SELECT 1 FROM target_chains c WHERE "
+                "c.reactant_set_id = measurements.reactant_set_id AND "
+                "(c.uniprot_swissprot_primary_id = ? OR c.uniprot_trembl_primary_id = ?))"
+            )
+            params.extend([uniprot_id, uniprot_id])
+
+        sql = (
+            "SELECT * FROM measurements "
+            f"WHERE {' AND '.join(where)} "
+            f"ORDER BY {value_col} ASC"
+        )
+        if limit is not None:
+            sql += " LIMIT ?"
+            params.append(int(limit))
+        return con.execute(sql, params).df()
+    finally:
+        con.close()

scigantic_bindingdb/releases.py

@@ -0,0 +1,105 @@
+"""Release metadata: what's mirrored, and what each release supports.
+
+Reads a small manifest at s3://scigantic-bindingdb/_MANIFEST.json. Unlike
+scigantic-chembl's manifest, this one is not yet regenerated by a cron --
+BindingDB releases monthly and re-mirroring here is still a manual step, so
+the manifest is hand-published alongside each mirror run. The mechanism is
+kept identical to scigantic-chembl's on purpose, so a cron can be added later
+without changing this module or anything that calls it.
+
+The manifest is fetched once per process and cached. If it can't be fetched
+(no network, a bucket hiccup), calls fall back to the snapshot below rather
+than failing outright: worst case is that the package is only as fresh as
+this package version, not broken.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+import warnings
+from dataclasses import dataclass
+from typing import Any, cast
+
+from ._constants import BUCKET, REGION
+
+_MANIFEST_URL = f"https://{BUCKET}.s3.{REGION}.amazonaws.com/_MANIFEST.json"
+_TIMEOUT_SECONDS = 5
+
+# Last-known-good snapshot, shipped with this package version. Only used if
+# the live manifest can't be fetched.
+_FALLBACK_LATEST = "202608"
+_FALLBACK_RELEASES = {
+    "202608": {"raw": True, "chembl_bridge": True, "dti_pairs": True},
+}
+
+
+class UnknownReleaseError(LookupError):
+    """Raised when a release isn't mirrored at all."""
+
+
+class ReleaseCapabilityError(LookupError):
+    """Raised when a release doesn't carry the artifact a call asked for."""
+
+
+@dataclass(frozen=True)
+class ReleaseInfo:
+    release: str
+    raw: bool
+    chembl_bridge: bool
+    dti_pairs: bool
+
+
+_cache: dict[str, Any] | None = None
+
+
+def _manifest() -> dict[str, Any]:
+    global _cache
+    if _cache is not None:
+        return _cache
+    try:
+        with urllib.request.urlopen(_MANIFEST_URL, timeout=_TIMEOUT_SECONDS) as response:
+            _cache = json.loads(response.read())
+    except (urllib.error.URLError, TimeoutError, ValueError) as exc:
+        # HTTPError (a URLError subclass) carries an open response body; left
+        # unclosed it raises its own ResourceWarning on garbage collection,
+        # on top of the one we're about to emit deliberately below.
+        if isinstance(exc, urllib.error.HTTPError):
+            exc.close()
+        warnings.warn(
+            f"could not fetch the live release manifest ({exc!r}); falling back "
+            "to the snapshot shipped with this package version, which may be stale",
+            stacklevel=3,
+        )
+        _cache = {"latest": _FALLBACK_LATEST, "releases": _FALLBACK_RELEASES}
+    return _cache
+
+
+def releases() -> list[ReleaseInfo]:
+    """List every release the mirror carries, and what each one supports."""
+    data = _manifest()
+    return [ReleaseInfo(release=name, **caps) for name, caps in data["releases"].items()]
+
+
+def latest() -> str:
+    """The release the archive treats as its current default."""
+    return cast(str, _manifest()["latest"])
+
+
+def _validate_release(release: str) -> None:
+    data = _manifest()
+    if release not in data["releases"]:
+        known = ", ".join(data["releases"])
+        raise UnknownReleaseError(f"{release!r} is not mirrored. Known releases: {known}.")
+
+
+def _require(release: str, capability: str) -> None:
+    _validate_release(release)
+    data = _manifest()
+    if not data["releases"][release][capability]:
+        raise ReleaseCapabilityError(
+            f"{release!r} has no {capability.replace('_', ' ')}. Call releases() to "
+            "see what each release supports, or use query() against the raw "
+            "parquet tables instead."
+        )

scigantic_bindingdb-0.2.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: scigantic-bindingdb
+Version: 0.2.0
+Summary: Query BindingDB directly from a public S3 mirror with DuckDB, including a ChEMBL cross-reference bridge table and a ready drug-target-interaction training table.
+Author: Scigantic
+License: MIT-0
+Project-URL: Homepage, https://scigantic.com
+Project-URL: Repository, https://github.com/Scigantic/scigantic-bindingdb
+Project-URL: Issues, https://github.com/Scigantic/scigantic-bindingdb/issues
+Keywords: bindingdb,cheminformatics,duckdb,drug-discovery,binding-affinity
+Classifier: License :: OSI Approved :: MIT No Attribution License (MIT-0)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+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: Typing :: Typed
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: duckdb>=0.10
+Requires-Dist: pandas>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">scigantic-bindingdb</h1>
+
+<p align="center">
+    <a href="https://github.com/Scigantic/scigantic-bindingdb/actions/workflows/ci.yml">
+        <img alt="CI" src="https://github.com/Scigantic/scigantic-bindingdb/actions/workflows/ci.yml/badge.svg" /></a>
+    <a href="https://pypi.org/project/scigantic-bindingdb/">
+        <img alt="PyPI" src="https://img.shields.io/pypi/v/scigantic-bindingdb" /></a>
+    <a href="https://pypi.org/project/scigantic-bindingdb/">
+        <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/scigantic-bindingdb" /></a>
+    <a href="https://github.com/Scigantic/scigantic-bindingdb/blob/main/LICENSE">
+        <img alt="License" src="https://img.shields.io/github/license/Scigantic/scigantic-bindingdb" /></a>
+</p>
+
+Query BindingDB directly from a public S3 mirror with DuckDB.
+
+```python
+import scigantic_bindingdb as bindingdb
+
+df = bindingdb.query("""
+    SELECT reactant_set_id, ligand_smiles, ki_nm_value
+    FROM measurements
+    WHERE ki_nm_value IS NOT NULL
+    LIMIT 5
+""")
+```
+
+That query runs against `s3://scigantic-bindingdb` over DuckDB's httpfs extension. Nothing is downloaded first, and there's no local database file sitting on disk afterward.
+
+## Installation
+
+```console
+$ pip install scigantic-bindingdb
+```
+
+## What's different about BindingDB
+
+Every row is one binding measurement (Ki, IC50, Kd or EC50) between one ligand and one protein target, rather than ChEMBL's assay-centric bioactivity record. BindingDB ships no relational database, just a flat TSV; the mirror normalizes it into `measurements` (one row per measurement), `target_chains` (one row per protein chain of the target, since BindingDB's raw format repeats a column block once per chain in a multimer) and `target_chain_names`.
+
+## Measurements, filtered the way that avoids the two sharp edges
+
+```python
+df = bindingdb.measurements(uniprot_id="P00533", endpoint="ki")  # EGFR
+```
+
+Two things this does that a raw query on `measurements` doesn't do for you:
+
+**Censored values stay out unless you ask for them.** Ki/IC50/Kd/EC50 are occasionally reported as `>X` or `<X` rather than an exact value, the same idea as ChEMBL's `standard_relation`. `exact_only=True`, the default, keeps only rows where that endpoint's qualifier is `=`:
+
+```python
+df = bindingdb.measurements(uniprot_id="P00533", endpoint="ic50", exact_only=False)  # include censored bounds too
+```
+
+**Target filtering doesn't fan out on multichain complexes.** `uniprot_id` matches against `target_chains` with an `EXISTS` check, not a `JOIN`, so a target whose accession appears on more than one chain of the same complex still returns each measurement once.
+
+`bindingdb.query()` still reaches the raw tables directly for anything this leaves out.
+
+## Cross-referencing ChEMBL
+
+BindingDB ingests ChEMBL as one of its own curated source feeds (51.3% of measurements in the 202608 release), and ChEMBL separately absorbs some BindingDB patent-derived bioactivity data, so the two archives are not independent corpora. `derived/bindingdb_chembl_bridge.parquet`, built once at mirror time, joins measurements to [scigantic-chembl](https://github.com/Scigantic/scigantic-chembl) by BindingDB's own `chembl_id` column where present (authoritative) and falls back to an exact InChIKey match where it's missing:
+
+```python
+df = bindingdb.chembl_bridge(reactant_set_id="50000001")
+```
+
+`with_names=True` (the default) also reaches into the live `scigantic-chembl` mirror for the matched compound's ChEMBL preferred name, a second public-bucket read over the same connection: not a mount-level dependency between the two archives, just a query-time join across two buckets that are both public and read-only here.
+
+## Drug-target-interaction pairs
+
+BindingDB is the dataset most DTI/proteochemometric tooling (like [DeepPurpose](https://github.com/kexinhuang12345/DeepPurpose)) is built around, specifically because it ships a full protein sequence alongside every affinity measurement, something ChEMBL's bioactivity tables don't do as directly. `derived/dti_pairs.parquet` is BindingDB reshaped into the (ligand, target, affinity) triples a model trains on, done once rather than re-derived by every caller:
+
+```python
+df = bindingdb.dti_pairs(endpoint="ki", single_chain_only=True)
+```
+
+```
+  reactant_set_id  ligand_smiles       target_sequence  uniprot_id  endpoint  affinity_nm  p_affinity
+           764556  Cc1ncoc1-c1nnc...   MASLSQLSSHLN...      P35462        ki         1.74    8.759451
+```
+
+Only exact measurements (never a censored `>X`/`<X` bound treated as a real label), and `p_affinity` is already computed as `-log10(affinity_nm * 1e-9)`, the same transform as ChEMBL's `pchembl_value`. 2,589,053 pairs across the four endpoints in the 202608 release, 1,163,672 distinct ligands, 9,219 distinct UniProt targets.
+
+Multichain targets are represented by chain 1's sequence only, standard practice for DTI benchmarks. Pass `single_chain_only=True` to drop the 5.7% of rows where that simplifies an actual multi-protein complex, if single-chain purity matters for your model. See `derived/DTI_README.md` in the mirror for the exact filters applied.
+
+## Working offline
+
+Off by default, since zero setup is the whole point. Turn it on to run the same queries repeatedly without re-fetching from S3:
+
+```python
+import scigantic_bindingdb as bindingdb
+
+bindingdb.enable_cache()
+df = bindingdb.chembl_bridge()  # downloads the bridge table once, then reads from disk
+```
+
+`chembl_bridge()` and `dti_pairs()` each need exactly one derived file, so caching downloads that one file to `~/.cache/scigantic-bindingdb` (override with `enable_cache(cache_dir=...)` or the `SCIGANTIC_BINDINGDB_CACHE` environment variable) and reuses it after that.
+
+`connect()`, `query()` and `measurements()` don't participate in this: `connect()` registers five core tables as views on every call, so caching them there would mean any call eagerly downloads everything regardless of what the query actually touches. Cache one table yourself if you want it locally: `bindingdb.cache_resolve("202608/parquet/measurements.parquet")` downloads it and returns the local path, usable directly in `read_parquet(...)`.
+
+## What's mirrored
+
+```python
+bindingdb.releases()
+```
+
+| release | raw tables | ChEMBL bridge | DTI pairs |
+|---|---|---|---|
+| 202608 | yes | yes | yes |
+
+This table isn't hardcoded. `releases()` reads a small manifest published alongside each mirror run. If it can't be reached, calls fall back to the snapshot shipped with whatever version you have installed and print a warning, rather than failing outright.
+
+Not mirrored yet: BindingDB's 3D SDF structures and precomputed similarity/substructure search (no fingerprint corpus has been built for this archive). `bindingdb.query()` still reaches every raw table the mirror carries.
+
+## Command line
+
+```console
+$ scigantic-bindingdb info
+$ scigantic-bindingdb query "SELECT count(*) FROM measurements" --release 202608
+```
+
+## License
+
+MIT-0. See [LICENSE](LICENSE).

scigantic_bindingdb-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+scigantic_bindingdb/__init__.py,sha256=Mi46LufFt4rdagj_ng8Y9tGMA8bffiAoDAu4-ad0tM4,1050
+scigantic_bindingdb/__main__.py,sha256=rMnNg3rwz8DD2ZVM0ylfdeYfSLyHULSVg4aICcCN5eQ,190
+scigantic_bindingdb/_constants.py,sha256=8EJUA6yIHAILlf1W8lnO45HkqW_qZwYX_OjiAUeUN88,216
+scigantic_bindingdb/cache.py,sha256=2NPs0A_BCcgSYgSChrdw6kIrMLKZsxa7TP88-6awNnE,3802
+scigantic_bindingdb/chembl_bridge.py,sha256=Oi2R1tLprKZ3jlx7igxHFJpKtjTGsSn6WMYENdDgiyw,3577
+scigantic_bindingdb/cli.py,sha256=BOTUtDcFah2vE-m6JemcoGZmhMx0_ZPA6OQ3v2-_19A,1655
+scigantic_bindingdb/connection.py,sha256=V4SlUJ0Ys_ZFBAH_G3ZTArsQCHNnTcSDlSo7nzNpc28,2844
+scigantic_bindingdb/dti_pairs.py,sha256=Hurw3UQtTseVDClHoJjRmehyz_lGpg2vq4ibP9YSRCE,2790
+scigantic_bindingdb/measurements.py,sha256=uOLOKHsKT9y6VJw3-sLoVd4a-e6EBBVdqwtbNWmjvp8,2897
+scigantic_bindingdb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scigantic_bindingdb/releases.py,sha256=0kbGo2wTKB6hvBli5fQsmihqy59Nc8qEfBeUa0syi9k,3652
+scigantic_bindingdb-0.2.0.dist-info/licenses/LICENSE,sha256=RiBhEtE0qZ65CeSf05VqMHWAhMh0ETETZAj4TEtscWE,904
+scigantic_bindingdb-0.2.0.dist-info/METADATA,sha256=vymmP5sGoetAJeOg-l_GMA4slyq28WWfVaWa_nncBog,8419
+scigantic_bindingdb-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+scigantic_bindingdb-0.2.0.dist-info/entry_points.txt,sha256=IuFxRQdzRACD7prBaS_gRgcfWFRK7RdJAynBc2eMU0o,69
+scigantic_bindingdb-0.2.0.dist-info/top_level.txt,sha256=1FMpDQXbzsrl91ICHFlMrUKUH6iE-Cew56k6wt1VRKk,20
+scigantic_bindingdb-0.2.0.dist-info/RECORD,,

scigantic_bindingdb-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scigantic_bindingdb-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scigantic-bindingdb = scigantic_bindingdb.cli:main

scigantic_bindingdb-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,16 @@
+MIT No Attribution
+
+Copyright 2026 Scigantic
+
+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.
+
+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.

scigantic_bindingdb-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scigantic_bindingdb