baseqdb 0.9.0__tar.gz → 0.10.0__tar.gz

{baseqdb-0.9.0 → baseqdb-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: baseqdb
-Version: 0.9.0
+Version: 0.10.0
 Summary: Your baSeq datasets, analyses and results from Python, with lamindb's names
 Project-URL: Homepage, https://baseq.bio
 Project-URL: Documentation, https://baseq.bio/docs/python-and-r.html
@@ -34,6 +34,8 @@ bq.Analysis.filter(kind="bulk").to_dataframe()  # the analyses you can open, new
 ds = bq.Dataset.get("kTIqMTTm89P2gbNU0000")     # one version, by its uid
 folder = ds.cache()                             # its files, downloaded once
 sheet = ds.sample_sheet                         # a DataFrame
+bq.Gene.standardize(["ENSG00000109906.15"])     # ['ZBTB16']: genes named as baSeq names them
+genes = bq.Gene.df("human")                     # every gene: id, symbol, biotype
 
 analysis = ds.analyses[0]
 analysis.steps.to_dataframe()                   # each step, its settings, when it ran

{baseqdb-0.9.0 → baseqdb-0.10.0}/README.md

@@ -13,6 +13,8 @@ bq.Analysis.filter(kind="bulk").to_dataframe()  # the analyses you can open, new
 ds = bq.Dataset.get("kTIqMTTm89P2gbNU0000")     # one version, by its uid
 folder = ds.cache()                             # its files, downloaded once
 sheet = ds.sample_sheet                         # a DataFrame
+bq.Gene.standardize(["ENSG00000109906.15"])     # ['ZBTB16']: genes named as baSeq names them
+genes = bq.Gene.df("human")                     # every gene: id, symbol, biotype
 
 analysis = ds.analyses[0]
 analysis.steps.to_dataframe()                   # each step, its settings, when it ran

{baseqdb-0.9.0 → baseqdb-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "baseqdb"
-version = "0.9.0"
+version = "0.10.0"
 description = "Your baSeq datasets, analyses and results from Python, with lamindb's names"
 readme = "README.md"
 requires-python = ">=3.10"

{baseqdb-0.9.0 → baseqdb-0.10.0}/src/baseqdb/__init__.py

@@ -8,6 +8,7 @@ Python, with lamindb's names; and, with a key that may add data, new datasets an
     ds = bq.Dataset.get("kTIqMTTm89P2gbNU0000")     # one version, by its uid
     folder = ds.cache()                             # its files, downloaded once
     bq.Dataset(["counts.tsv"], name=ds.name, kind="bulk").save()   # its next version
+    bq.Gene.standardize(["ENSG00000109906.15", "fkbp5"])            # ['ZBTB16', 'FKBP5'], as baSeq names them
 
     bq.track()                                      # this script as one run: what it reads, adds and saves
     bq.Record("dge.csv").save()                     # a file of the run
@@ -18,9 +19,10 @@ with it, what it found said at the end. `baseqdb init` writes that guide into a
 Docs: https://baseq.bio/docs/python-and-r.html
 """
 from baseqdb._client import VERSION as __version__, BaseqError, login, me
+from baseqdb._genes import Gene
 from baseqdb._records import (Analysis, Dataset, File, Files, Finding, GeneHit, Record, Results, Run, Step, Table,
                               Tables)
 from baseqdb._track import finish, track
 
 __all__ = ["login", "me", "BaseqError", "Dataset", "File", "Files", "Analysis", "Step", "Finding", "GeneHit", "Table",
-           "Tables", "Record", "Run", "Results", "track", "finish", "__version__"]
+           "Tables", "Record", "Run", "Results", "Gene", "track", "finish", "__version__"]

{baseqdb-0.9.0 → baseqdb-0.10.0}/src/baseqdb/_client.py

@@ -9,7 +9,7 @@ from pathlib import Path
 import httpx
 
 DEFAULT_URL = "https://baseq.bio"
-VERSION = "0.9.0"
+VERSION = "0.10.0"
 RUN_HEADER = "X-Baseq-Run"
 RUN_FILE = Path(".baseqdb") / "run"     # an agent's task, begun with `baseqdb track`, for every command in the folder
 _state: dict = {"client": None, "base": None, "run": None}
@@ -231,6 +231,29 @@ def download(path: str, target: Path, sha256: str | None = None, read: dict | No
     return target
 
 
+def download_current(path: str, target: Path, **params) -> Path:
+    """``path`` saved as ``target``, and again only when baSeq has changed it: the copy's ETag goes with the request,
+    and the copy stays when the answer is 304 (Not Modified)."""
+    tag_file = target.with_name(target.name + ".etag")
+    headers = {}
+    if target.is_file() and tag_file.is_file():
+        headers["If-None-Match"] = tag_file.read_text(encoding="utf-8").strip()
+    http, base = _http()
+    response = http.get(base + path, params={k: v for k, v in params.items() if v is not None}, headers=headers)
+    if response.status_code == 304:
+        return target
+    _raise(response)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    part = target.with_name(target.name + ".part")
+    part.write_bytes(response.content)
+    os.replace(part, target)
+    if response.headers.get("ETag"):
+        tag_file.write_text(response.headers["ETag"], encoding="utf-8")
+    else:
+        tag_file.unlink(missing_ok=True)
+    return target
+
+
 def cache_dir() -> Path:
     """Where downloads are kept: BASEQDB_CACHE, or ~/.cache/baseqdb."""
     return Path(os.environ.get("BASEQDB_CACHE") or Path.home() / ".cache" / "baseqdb")

baseqdb-0.10.0/src/baseqdb/_genes.py

@@ -0,0 +1,72 @@
+"""Gene names, with bionty's names: ``Gene.standardize`` gives a table's genes their symbols (or Ensembl ids) as baSeq
+names them, and ``Gene.df`` is every gene of one organism, kept on this computer. Both from the gene reference baSeq
+uses: Ensembl release 114, for human, mouse, cattle, zebrafish and salmon."""
+from __future__ import annotations
+
+import re
+
+from baseqdb import _client as _c
+from baseqdb._records import _pandas
+
+PART = 50_000           # names a request, the most the API takes
+_LONGEST = 120          # no gene's name is longer: a longer one is kept as written without asking
+RETURN_FIELDS = ("symbol", "ensembl_gene_id")
+
+
+def _text(value) -> str | None:
+    """A name as text, or None for a missing value (None, NaN, pandas' NA)."""
+    if value is None:
+        return None
+    try:
+        if value != value:
+            return None
+    except TypeError:
+        return None
+    return str(value)
+
+
+class Gene:
+    """Genes as baSeq's gene reference has them (Ensembl 114: human, mouse, cattle, zebrafish and salmon)."""
+
+    @staticmethod
+    def standardize(names, return_field: str = "symbol", return_mapper: bool = False, organism: str | None = None):
+        """Each name as baSeq names the gene, as bionty's ``Gene.standardize``: its symbol, or with
+        ``return_field="ensembl_gene_id"`` its Ensembl id. A name may be an Ensembl id with or without its version
+        (ENSG00000109906.15 is ZBTB16), a symbol in any case, or another of its names; a symbol several genes share
+        means the one on the primary assembly. A name the reference does not have, or one that several genes share,
+        is kept as written. The names tell their organism, as an analysis's genes do; ``organism`` ("human",
+        "mouse", "cattle", "zebrafish" or "salmon") says it when they cannot.
+
+        A list in the order of ``names`` (a list, a pandas Index or Series; one name gives one name), or with
+        ``return_mapper=True`` a dict of the names that changed."""
+        if return_field not in RETURN_FIELDS:
+            raise ValueError(f"return_field is {' or '.join(map(repr, RETURN_FIELDS))}, not {return_field!r}")
+        single = isinstance(names, str)
+        given = [names] if single else list(names)
+        texts = [_text(v) for v in given]
+        asked = [t for t in dict.fromkeys(texts) if t and len(t) <= _LONGEST]
+        named: dict[str, str] = {}
+        for i in range(0, len(asked), PART):
+            part = asked[i:i + PART]
+            answer = _c.post("/genes/standardize", json={"names": part, "organism": organism,
+                                                         "return_field": return_field})
+            organism = organism or answer["organism"] or None    # the later parts as the first was told
+            named.update(zip(part, answer["names"]))
+        changed = [named[t] if t in named and named[t] != t else None for t in texts]
+        if return_mapper:
+            return {v: new for v, new in zip(given, changed) if new is not None}
+        out = [v if new is None else new for v, new in zip(given, changed)]
+        return out[0] if single else out
+
+    @staticmethod
+    def df(organism: str):
+        """Every gene of one organism baSeq's reference has, as a pandas DataFrame, as bionty's
+        ``Gene.public(organism).df()``: ensembl_gene_id, symbol (missing when Ensembl gives none), biotype, and
+        primary_assembly (False for a copy on a haplotype or a patch). Downloaded once and kept in baseqdb's cache
+        (genes/), for as long as the reference stays the same."""
+        pd = _pandas()
+        key = re.sub(r"[^a-z0-9]+", "_", str(organism).strip().lower()).strip("_") or "organism"
+        path = _c.download_current("/genes", _c.cache_dir() / "genes" / f"{key}.tsv", organism=organism)
+        table = pd.read_csv(path, sep="\t", dtype=str, keep_default_na=False, na_values=[""])
+        table["primary_assembly"] = table["primary_assembly"] == "1"
+        return table

{baseqdb-0.9.0 → baseqdb-0.10.0}/src/baseqdb/guide.md

@@ -60,6 +60,12 @@ data this way before asking the person which dataset they mean. In R, the same n
 `Dataset$get(uid)$cache()`, `ds$sample_sheet`, `Dataset$filter(condition = "dexamethasone")`, `Dataset$search("dex")`,
 `Analysis$filter()`.
 
+## Gene names
+
+Count tables often name genes by their Ensembl id. `bq.Gene.standardize(names)` gives each its symbol as baSeq names
+it (with `return_field="ensembl_gene_id"`, the other way round), and `bq.Gene.df("human")` is every gene of an
+organism; in R, `Gene$standardize()` and `Gene$df()`. A finding names its genes by symbol, as `--gene` does.
+
 ## Adding
 
 A new version of a dataset: the name and kind of one the person has, with a key that may add data.