aabatlas 0.1.0__tar.gz

aabatlas-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+data/
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+/python-package/dist/
+/python-package/build/
+.pytest_cache/
+
+# R
+.Rhistory
+.RData
+.Rproj.user/
+*.Rcheck/
+*.tar.gz
+
+# OS
+.DS_Store
+Thumbs.db

aabatlas-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandre Marques
+
+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.

aabatlas-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: aabatlas
+Version: 0.1.0
+Summary: Client for the antibodyome-atlas, a curated catalog of autoantibody profiling datasets and papers
+Project-URL: Homepage, https://github.com/ahcm088/antibodyome-atlas
+Project-URL: Issues, https://github.com/ahcm088/antibodyome-atlas/issues
+Author-email: Alexandre Marques <marquesufcg@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ArrayExpress,GEO,autoantibody,bioinformatics,proteomics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.5
+Requires-Dist: requests>=2.31
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# aabatlas
+
+Python client for the [antibodyome-atlas](https://github.com/ahcm088/antibodyome-atlas), a curated catalog of autoantibody profiling datasets and papers. See `schema/README.md` in the atlas repo for the data model. Mirrors the R client, [AAbAtlas](../r-package).
+
+## Install
+
+Not yet on PyPI. Until then, install from GitHub:
+
+```bash
+pip install "git+https://github.com/ahcm088/antibodyome-atlas.git#subdirectory=python-package"
+```
+
+## Usage
+
+```python
+import aabatlas
+
+# browse
+ds = aabatlas.list_datasets()
+ds[(ds["record_type"] == "DATASET") & (ds["total_sample_n"] > 100)][["atlas_id", "title", "total_sample_n"]]
+
+# one record, with its publication and platforms resolved
+rec = aabatlas.get_dataset("AAB-000004")
+rec["title"]
+rec["publication"]["citation"]
+
+# citation ready to paste into a manuscript
+aabatlas.get_citation("AAB-000004")
+
+# download the underlying file
+aabatlas.download("AAB-000004")
+```
+
+By default every function reads the latest curated data (`ref="main"`). Pin a release tag for reproducibility in a publication:
+
+```python
+aabatlas.list_datasets(ref="v1.0.0")
+```

aabatlas-0.1.0/README.md

@@ -0,0 +1,38 @@
+# aabatlas
+
+Python client for the [antibodyome-atlas](https://github.com/ahcm088/antibodyome-atlas), a curated catalog of autoantibody profiling datasets and papers. See `schema/README.md` in the atlas repo for the data model. Mirrors the R client, [AAbAtlas](../r-package).
+
+## Install
+
+Not yet on PyPI. Until then, install from GitHub:
+
+```bash
+pip install "git+https://github.com/ahcm088/antibodyome-atlas.git#subdirectory=python-package"
+```
+
+## Usage
+
+```python
+import aabatlas
+
+# browse
+ds = aabatlas.list_datasets()
+ds[(ds["record_type"] == "DATASET") & (ds["total_sample_n"] > 100)][["atlas_id", "title", "total_sample_n"]]
+
+# one record, with its publication and platforms resolved
+rec = aabatlas.get_dataset("AAB-000004")
+rec["title"]
+rec["publication"]["citation"]
+
+# citation ready to paste into a manuscript
+aabatlas.get_citation("AAB-000004")
+
+# download the underlying file
+aabatlas.download("AAB-000004")
+```
+
+By default every function reads the latest curated data (`ref="main"`). Pin a release tag for reproducibility in a publication:
+
+```python
+aabatlas.list_datasets(ref="v1.0.0")
+```

aabatlas-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aabatlas"
+version = "0.1.0"
+description = "Client for the antibodyome-atlas, a curated catalog of autoantibody profiling datasets and papers"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Alexandre Marques", email = "marquesufcg@gmail.com" }]
+keywords = ["autoantibody", "proteomics", "bioinformatics", "GEO", "ArrayExpress"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "requests>=2.31",
+    "pandas>=1.5",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/ahcm088/antibodyome-atlas"
+Issues = "https://github.com/ahcm088/antibodyome-atlas/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aabatlas"]

aabatlas-0.1.0/src/aabatlas/__init__.py

@@ -0,0 +1,18 @@
+"""Client for the antibodyome-atlas."""
+from ._source import raw_url
+from .citation import get_citation
+from .datasets import get_dataset, list_datasets, list_link_status, list_platforms, list_publications
+from .download import download
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "list_datasets",
+    "list_publications",
+    "list_platforms",
+    "list_link_status",
+    "get_dataset",
+    "get_citation",
+    "download",
+    "raw_url",
+]

aabatlas-0.1.0/src/aabatlas/_source.py

@@ -0,0 +1,40 @@
+"""Internal: fetch and parse the atlas's GitHub-hosted JSON manifests."""
+from __future__ import annotations
+
+import pandas as pd
+import requests
+
+_FILES = ("datasets", "publications", "platforms", "link_status", "seeds")
+_USER_AGENT = "aabatlas-python/0.1 (+https://github.com/ahcm088/antibodyome-atlas)"
+
+
+def raw_url(file: str, ref: str = "main") -> str:
+    """Build the raw GitHub URL for one of the atlas's metadata files.
+
+    Parameters
+    ----------
+    file:
+        One of "datasets", "publications", "platforms", "link_status", "seeds".
+    ref:
+        Git ref (branch, tag, or commit SHA) to read from. Defaults to
+        "main" (the latest curated data). Pin to a release tag (e.g.
+        "v1.0.0") for reproducible results in a publication.
+    """
+    if file not in _FILES:
+        raise ValueError(f"file must be one of {_FILES}, got {file!r}")
+    return f"https://raw.githubusercontent.com/ahcm088/antibodyome-atlas/{ref}/metadata/{file}.json"
+
+
+def fetch(file: str, ref: str = "main") -> pd.DataFrame:
+    """Fetch and parse one of the atlas's JSON manifests as a DataFrame.
+
+    Nested fields (e.g. ``conditions``, ``platforms``, ``source_ids``) come
+    back as object-dtype columns holding Python lists/dicts.
+    """
+    url = raw_url(file, ref=ref)
+    resp = requests.get(url, timeout=30, headers={"User-Agent": _USER_AGENT})
+    resp.raise_for_status()
+    data = resp.json()
+    if not data:
+        return pd.DataFrame()
+    return pd.DataFrame(data)

aabatlas-0.1.0/src/aabatlas/citation.py

@@ -0,0 +1,25 @@
+"""Citation helper."""
+from __future__ import annotations
+
+from typing import Any
+
+from .datasets import get_dataset
+
+
+def get_citation(atlas_id: str, ref: str = "main") -> dict[str, Any]:
+    """Get the citation for a dataset, ready to paste into a manuscript.
+
+    Returns a dict with ``atlas_id``, ``dataset_link``, ``citation``,
+    ``doi``, ``pubmed_link``, ``publisher_link``. Publication fields are
+    ``None`` if the record has no associated publication.
+    """
+    record = get_dataset(atlas_id, ref=ref)
+    pub = record.get("publication") or {}
+    return {
+        "atlas_id": record["atlas_id"],
+        "dataset_link": record["dataset_link"],
+        "citation": pub.get("citation"),
+        "doi": pub.get("doi"),
+        "pubmed_link": pub.get("pubmed_link"),
+        "publisher_link": pub.get("publisher_link"),
+    }

aabatlas-0.1.0/src/aabatlas/datasets.py

@@ -0,0 +1,84 @@
+"""List and resolve atlas records."""
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from ._source import fetch
+
+
+def list_datasets(ref: str = "main") -> pd.DataFrame:
+    """List all datasets/papers in the atlas.
+
+    Columns match ``schema/dataset.schema.json`` in the atlas repo
+    (``atlas_id``, ``record_type``, ``title``, ``organism``, ``conditions``,
+    ``total_sample_n``, ``platforms``, ``dataset_link``,
+    ``curated_availability``, etc.). List/dict-valued fields come back as
+    Python objects in object-dtype columns.
+    """
+    return fetch("datasets", ref=ref)
+
+
+def list_publications(ref: str = "main") -> pd.DataFrame:
+    """List all publications referenced by atlas datasets."""
+    return fetch("publications", ref=ref)
+
+
+def list_platforms(ref: str = "main") -> pd.DataFrame:
+    """List all assay platforms referenced by atlas datasets.
+
+    Per-study protein/feature counts live on the dataset record
+    (``list_datasets()["platforms"]``), not here -- see ``schema/README.md``
+    in the atlas repo for why.
+    """
+    return fetch("platforms", ref=ref)
+
+
+def list_link_status(ref: str = "main") -> pd.DataFrame:
+    """List the link-reachability check history.
+
+    One row per automated check, appended over time by the atlas's
+    scheduled link checker. ``reachable`` is the raw HTTP signal;
+    ``likely_bot_blocked`` flags 403/429 responses from publisher anti-bot
+    defenses, which are not necessarily dead links.
+    """
+    return fetch("link_status", ref=ref)
+
+
+def get_dataset(atlas_id: str, ref: str = "main") -> dict[str, Any]:
+    """Get a single dataset record, with its publication and platforms resolved.
+
+    Returns a dict with the dataset's fields plus two resolved keys:
+    ``publication`` (a dict, or ``None`` if the record has no associated
+    publication) and ``platforms_detail`` (a list combining each
+    ``platforms[].platform_id`` from the dataset with the matching row from
+    ``list_platforms()``, keeping ``n_proteins_reported``).
+    """
+    ds = list_datasets(ref=ref)
+    match = ds[ds["atlas_id"] == atlas_id]
+    if match.empty:
+        raise ValueError(f"No dataset found with atlas_id: {atlas_id}")
+    record = match.iloc[0].to_dict()
+
+    pub_id = record.get("publication_id")
+    if pub_id:
+        pubs = list_publications(ref=ref)
+        pub_match = pubs[pubs["publication_id"] == pub_id]
+        record["publication"] = pub_match.iloc[0].to_dict() if not pub_match.empty else None
+    else:
+        record["publication"] = None
+
+    platforms = record.get("platforms") or []
+    detail = []
+    if platforms:
+        all_platforms = list_platforms(ref=ref)
+        for p in platforms:
+            merged = dict(p)
+            prow = all_platforms[all_platforms["platform_id"] == p["platform_id"]]
+            if not prow.empty:
+                merged.update({k: v for k, v in prow.iloc[0].to_dict().items() if k != "platform_id"})
+            detail.append(merged)
+    record["platforms_detail"] = detail
+
+    return record

aabatlas-0.1.0/src/aabatlas/download.py

@@ -0,0 +1,48 @@
+"""Download a dataset's data file."""
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import requests
+
+from .datasets import get_dataset
+
+_USER_AGENT = "aabatlas-python/0.1 (+https://github.com/ahcm088/antibodyome-atlas)"
+
+
+def download(atlas_id: str, destdir: str = ".", destfile: str | None = None, ref: str = "main") -> Path:
+    """Download whatever is at the record's ``dataset_link``.
+
+    For records with ``record_type == "DATASET"`` this is usually a
+    repository landing page (e.g. a GEO accession page) rather than a
+    direct file: check ``curated_availability`` first, and note that some
+    repositories require navigating from that page to the actual
+    supplementary files by hand.
+
+    Returns the local file path.
+    """
+    record = get_dataset(atlas_id, ref=ref)
+
+    status = (record.get("curated_availability") or {}).get("data_status")
+    if status in ("unavailable", "upon_request"):
+        warnings.warn(
+            f"curated_availability.data_status for {atlas_id} is {status!r} -- "
+            "the data itself may not be directly downloadable. Proceeding to fetch dataset_link anyway."
+        )
+
+    url = record["dataset_link"]
+    if destfile is None:
+        destfile = Path(urlsplit(url).path).name or f"{atlas_id}.html"
+
+    path = Path(destdir) / destfile
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    resp = requests.get(url, timeout=60, headers={"User-Agent": _USER_AGENT}, stream=True)
+    resp.raise_for_status()
+    with open(path, "wb") as f:
+        for chunk in resp.iter_content(chunk_size=8192):
+            f.write(chunk)
+
+    return path

aabatlas-0.1.0/tests/conftest.py

@@ -0,0 +1,15 @@
+import pytest
+import requests
+
+from aabatlas._source import raw_url
+
+
+@pytest.fixture
+def atlas_or_skip():
+    try:
+        resp = requests.get(raw_url("datasets"), timeout=10)
+        ok = resp.status_code == 200
+    except requests.RequestException:
+        ok = False
+    if not ok:
+        pytest.skip("metadata/datasets.json not reachable at ref 'main' (repo not pushed yet, or offline)")

aabatlas-0.1.0/tests/test_datasets.py

@@ -0,0 +1,39 @@
+import pytest
+
+import aabatlas
+
+
+def test_raw_url_builds_the_expected_url():
+    assert aabatlas.raw_url("datasets", ref="v1.0.0") == (
+        "https://raw.githubusercontent.com/ahcm088/antibodyome-atlas/v1.0.0/metadata/datasets.json"
+    )
+    with pytest.raises(ValueError):
+        aabatlas.raw_url("nope")
+
+
+def test_list_datasets_returns_expected_columns(atlas_or_skip):
+    ds = aabatlas.list_datasets()
+    assert len(ds) > 0
+    for col in ("atlas_id", "record_type", "title", "dataset_link"):
+        assert col in ds.columns
+
+
+def test_get_dataset_resolves_publication_and_platforms(atlas_or_skip):
+    ds = aabatlas.list_datasets()
+    target = ds[ds["publication_id"].notna()]["atlas_id"].iloc[0]
+    record = aabatlas.get_dataset(target)
+    assert record["atlas_id"] == target
+    assert record["publication"] is not None
+
+
+def test_get_dataset_raises_on_unknown_atlas_id(atlas_or_skip):
+    with pytest.raises(ValueError, match="No dataset found"):
+        aabatlas.get_dataset("AAB-999999")
+
+
+def test_get_citation_returns_expected_keys(atlas_or_skip):
+    ds = aabatlas.list_datasets()
+    target = ds[ds["publication_id"].notna()]["atlas_id"].iloc[0]
+    cite = aabatlas.get_citation(target)
+    for key in ("atlas_id", "citation", "doi"):
+        assert key in cite