microarray 0.1.0__tar.gz → 0.2.0__tar.gz

{microarray-0.1.0 → microarray-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microarray
-Version: 0.1.0
+Version: 0.2.0
 Summary: Microarray analysis tools
 Author: harryhaller001
 Author-email: harryhaller001 <harryhaller001@gmail.com>
@@ -17,12 +17,13 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Dist: adjusttext>=1.3
 Requires-Dist: anndata
-Requires-Dist: click
+Requires-Dist: geofetch>=0.12.10
 Requires-Dist: matplotlib
 Requires-Dist: requests
 Requires-Dist: scikit-learn
 Requires-Dist: scipy
 Requires-Dist: statsmodels
+Requires-Dist: tqdm>=4.67.3
 Requires-Dist: ipython ; extra == 'docs'
 Requires-Dist: myst-parser ; extra == 'docs'
 Requires-Dist: nbsphinx ; extra == 'docs'

{microarray-0.1.0 → microarray-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "uv-build>=0.9.28,<0.10" ]
 
 [project]
 name = "microarray"
-version = "0.1.0"
+version = "0.2.0"
 description = "Microarray analysis tools"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "MIT"
@@ -26,12 +26,13 @@ classifiers = [
 dependencies = [
     "adjusttext>=1.3",
     "anndata",
-    "click",
+    "geofetch>=0.12.10",
     "matplotlib",
     "requests",
     "scikit-learn",
     "scipy",
     "statsmodels",
+    "tqdm>=4.67.3",
 ]
 optional-dependencies.docs = [
     "ipython",                  # Required for syntax highlighing (https://github.com/spatialaudio/nbsphinx/issues/24)
@@ -104,4 +105,5 @@ report.ignore_errors = true
 html.directory = "coverage_report"
 
 [tool.ty]
-src.include = [ "src", "tests", "docs" ]
+src.include = [ "src", "docs" ]
+src.exclude = [ "tests", "examples" ]

microarray-0.2.0/src/microarray/datasets/__init__.py

@@ -0,0 +1,35 @@
+from microarray.datasets._arrayexpress import (
+    ArrayExpressError,
+    ArrayExpressMetadata,
+    ArrayExpressRemoteFile,
+    ArrayExpressStudyFiles,
+    get_arrayexpress,
+    parse_adf,
+    parse_arrayexpress_metadata,
+    parse_idf,
+    parse_sdrf,
+    query_arrayexpress,
+    read_arrayexpress,
+    read_arrayexpress_metadata,
+)
+from microarray.datasets._cdf_files import hgu133a_cdf, hgu133plus2_cdf
+from microarray.datasets._geo import read_geo, read_geo_metadata
+
+__all__ = [
+    "ArrayExpressError",
+    "ArrayExpressMetadata",
+    "ArrayExpressRemoteFile",
+    "ArrayExpressStudyFiles",
+    "get_arrayexpress",
+    "hgu133a_cdf",
+    "hgu133plus2_cdf",
+    "read_arrayexpress",
+    "parse_adf",
+    "parse_arrayexpress_metadata",
+    "parse_idf",
+    "parse_sdrf",
+    "query_arrayexpress",
+    "read_arrayexpress_metadata",
+    "read_geo",
+    "read_geo_metadata",
+]

microarray-0.2.0/src/microarray/datasets/_arrayexpress.py

@@ -0,0 +1,587 @@
+"""Utilities for fetching ArrayExpress studies via BioStudies.
+
+This module covers two tasks:
+1. Discover studies through the ArrayExpress search endpoint.
+2. Download study files (raw/processsed/MAGE-TAB) and parse MAGE-TAB metadata.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import re
+import zipfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+import pandas as pd
+import requests
+from anndata import AnnData, concat
+
+from microarray.datasets._utils import TIMEOUT, build_url, download_file_stream
+from microarray.io import CdfFile, read_cel
+
+_BIOSTUDIES_HOST = "www.ebi.ac.uk"
+_STUDIES_PATH = "/biostudies/api/v1/studies"
+_SEARCH_PATH = "/biostudies/api/v1/arrayexpress/search"
+
+_AE_ACCESSION_PATTERN = re.compile(r"^E-[A-Z0-9]+-[A-Z0-9]+$", re.IGNORECASE)
+
+ArrayExpressType = Literal["raw", "processed", "mage", "full"]
+
+
+class ArrayExpressError(RuntimeError):
+    """Raised when ArrayExpress/BioStudies requests fail."""
+
+
+@dataclass(frozen=True)
+class ArrayExpressRemoteFile:
+    """One remotely available file entry for a study."""
+
+    category: Literal["Raw Data", "Processed Data", "MAGE-TAB Files", "Array Designs"]
+    path: str
+    url: str
+
+    @property
+    def name(self) -> str:
+        """Return the basename of ``path`` for convenience."""
+        return os.path.basename(self.path)
+
+
+@dataclass(frozen=True)
+class ArrayExpressStudyFiles:
+    """Downloaded and categorized study files for one accession."""
+
+    accession: str
+    destination: str
+    data_type: ArrayExpressType
+    files: tuple[ArrayExpressRemoteFile, ...]
+    raw_archives: tuple[str, ...]
+    processed_archives: tuple[str, ...]
+    mage_tab_files: tuple[str, ...]
+    adf_files: tuple[str, ...]
+    raw_files: tuple[str, ...]
+    processed_files: tuple[str, ...]
+    idf: str | None
+    sdrf: str | None
+
+
+@dataclass(frozen=True)
+class ArrayExpressMetadata:
+    """Parsed MAGE-TAB metadata tables for a downloaded study."""
+
+    idf_map: dict[str, list[str]]
+    idf_table: pd.DataFrame
+    sdrf: pd.DataFrame | None
+    adf_tables: dict[str, pd.DataFrame]
+
+
+def _normalize_accession(accession: str) -> str:
+    value = str(accession).strip().upper()
+    if not _AE_ACCESSION_PATTERN.match(value):
+        raise ValueError(f"Invalid ArrayExpress accession '{accession}'. Expected format like 'E-MEXP-21'.")
+    return value
+
+
+def _normalize_type(value: ArrayExpressType | str) -> ArrayExpressType:
+    normalized = str(value).strip().lower()
+    options: tuple[ArrayExpressType, ...] = ("raw", "processed", "mage", "full")
+    if normalized not in options:
+        raise ValueError(f"Invalid type '{value}'. Expected one of {options}.")
+    return normalized  # type: ignore[return-value]
+
+
+def _request_json(url: str) -> dict[str, Any]:
+    response = requests.get(url, timeout=TIMEOUT)
+    if response.status_code != 200:
+        raise ArrayExpressError(
+            f"Error running query. Received HTTP {response.status_code} from BioStudies for URL '{url}'."
+        )
+
+    payload = response.json()
+    if not isinstance(payload, dict):
+        raise ArrayExpressError(f"Unexpected JSON payload type for URL '{url}'.")
+    return payload
+
+
+def query_arrayexpress(
+    keywords: str | None = None,
+    page: int = 1,
+    all_pages: bool = False,
+    page_size: int = 100,
+) -> pd.DataFrame:
+    """Search ArrayExpress studies through the BioStudies search API.
+
+    Args:
+            keywords: Free-text search query.
+            page: 1-based page index used for the initial request.
+            all_pages: If True, keep fetching subsequent pages until no hits are returned.
+            page_size: Number of rows fetched per page.
+
+    Returns:
+            DataFrame with search hits. By default this contains one page only.
+    """
+    if page < 1:
+        raise ValueError("'page' must be >= 1.")
+
+    base_query = {
+        "query": "" if keywords is None else keywords,
+        "pageSize": int(page_size),
+    }
+
+    current_page = int(page)
+    all_hits: list[dict[str, Any]] = []
+
+    while True:
+        query = dict(base_query)
+        query["page"] = current_page
+        url = build_url(hostname=_BIOSTUDIES_HOST, path=_SEARCH_PATH, query=query)
+        payload = _request_json(url)
+
+        hits = payload.get("hits", [])
+        if not isinstance(hits, list) or len(hits) == 0:
+            break
+
+        all_hits.extend(hit for hit in hits if isinstance(hit, dict))
+        if not all_pages:
+            break
+
+        current_page += 1
+
+    return pd.DataFrame(all_hits)
+
+
+def _iter_section_nodes(nodes: list[Any]) -> list[dict[str, Any]]:
+    flattened: list[dict[str, Any]] = []
+    for node in nodes:
+        if isinstance(node, dict):
+            flattened.append(node)
+        elif isinstance(node, list):
+            flattened.extend(_iter_section_nodes(node))
+    return flattened
+
+
+def _iter_assay_sections(study_payload: dict[str, Any]) -> list[dict[str, Any]]:
+    section = study_payload.get("section", {})
+    if not isinstance(section, dict):
+        return []
+
+    subsections = section.get("subsections", [])
+    if not isinstance(subsections, list):
+        return []
+
+    for node in _iter_section_nodes(subsections):
+        if node.get("type") == "Assays and Data":
+            assays = node.get("subsections", [])
+            if isinstance(assays, list):
+                return _iter_section_nodes(assays)
+    return []
+
+
+def _iter_links(payload_section: dict[str, Any]) -> list[dict[str, Any]]:
+    links = payload_section.get("links", [])
+    if not isinstance(links, list):
+        return []
+    return _iter_section_nodes(links)
+
+
+def _iter_array_design_accessions(study_payload: dict[str, Any]) -> list[str]:
+    values: list[str] = []
+    for assay in _iter_assay_sections(study_payload):
+        if assay.get("type") != "Array Designs":
+            continue
+        for link in _iter_links(assay):
+            accession = link.get("url")
+            if isinstance(accession, str) and accession.strip() != "":
+                values.append(accession.strip())
+    return values
+
+
+def _resolve_arrayexpress_cdf(accession: str, cdf_file: str | CdfFile | None) -> str | CdfFile:
+    if cdf_file is not None:
+        return cdf_file
+
+    from microarray.datasets._cdf_files import hgu133a_cdf, hgu133plus2_cdf
+
+    cdf_loaders: dict[str, Callable[[], CdfFile]] = {
+        "A-AFFY-2": hgu133a_cdf,
+        "A-AFFY-44": hgu133plus2_cdf,
+    }
+
+    study_url = build_url(hostname=_BIOSTUDIES_HOST, path=f"{_STUDIES_PATH}/{accession}")
+    study_payload = _request_json(study_url)
+    designs = _iter_array_design_accessions(study_payload)
+
+    for design in designs:
+        loader = cdf_loaders.get(design)
+        if loader is not None:
+            return loader()
+
+    raise ValueError(
+        f"Unable to infer CDF for accession '{accession}'. Please pass 'cdf_file' explicitly to read_arrayexpress()."
+    )
+
+
+def _normalize_file_key(value: object) -> str | None:
+    if value is None:
+        return None
+
+    raw = str(value).strip()
+    if raw == "" or raw.lower() == "nan":
+        return None
+
+    base = os.path.basename(raw)
+    lower = base.lower()
+    if lower.endswith(".gz"):
+        lower = lower[:-3]
+    if lower.endswith(".cel"):
+        lower = lower[:-4]
+
+    return lower
+
+
+def _collect_cel_paths_recursive(folder: Path) -> list[Path]:
+    cel_paths = [
+        path for path in folder.rglob("*") if path.is_file() and path.name.lower().endswith((".cel", ".cel.gz"))
+    ]
+    return sorted(cel_paths)
+
+
+def _collect_files(
+    study_payload: dict[str, Any],
+    files_base_url: str,
+    data_type: ArrayExpressType,
+) -> list[ArrayExpressRemoteFile]:
+    assays = _iter_assay_sections(study_payload)
+    selected: list[ArrayExpressRemoteFile] = []
+
+    for assay in assays:
+        assay_type = assay.get("type")
+        if assay_type not in {"Raw Data", "Processed Data", "MAGE-TAB Files", "Array Designs"}:
+            continue
+
+        files = assay.get("files", [])
+        if isinstance(files, list):
+            for file_item in _iter_section_nodes(files):
+                rel_path = file_item.get("path")
+                if not isinstance(rel_path, str) or rel_path.strip() == "":
+                    continue
+                url = f"{files_base_url.rstrip('/')}/Files/{rel_path.lstrip('/')}"
+                selected.append(ArrayExpressRemoteFile(category=assay_type, path=rel_path, url=url))
+
+        if assay_type == "Array Designs":
+            for link in _iter_links(assay):
+                accession = link.get("url")
+                if not isinstance(accession, str) or accession.strip() == "":
+                    continue
+                adf_name = f"{accession}.adf.txt"
+                adf_url = build_url(
+                    hostname=_BIOSTUDIES_HOST,
+                    path=f"/biostudies/files/{accession}/{adf_name}",
+                )
+                selected.append(ArrayExpressRemoteFile(category="Array Designs", path=adf_name, url=adf_url))
+
+    if data_type == "full":
+        return selected
+
+    category_map = {
+        "raw": "Raw Data",
+        "processed": "Processed Data",
+        "mage": "MAGE-TAB Files",
+    }
+    target = category_map[data_type]
+    return [entry for entry in selected if entry.category == target]
+
+
+def _extract_zip_file(archive_path: Path) -> list[str]:
+    extracted_paths: list[str] = []
+    with zipfile.ZipFile(archive_path) as archive:
+        for member in archive.infolist():
+            if member.is_dir():
+                continue
+            archive.extract(member, path=archive_path.parent)
+            extracted_paths.append(str(archive_path.parent / member.filename))
+    return extracted_paths
+
+
+def get_arrayexpress(
+    accession: str,
+    destination: str,
+    data_type: ArrayExpressType = "full",
+    extract: bool = True,
+    overwrite: bool = False,
+) -> ArrayExpressStudyFiles:
+    """Download one ArrayExpress study and return a file manifest.
+
+    Args:
+            accession: ArrayExpress accession (for example ``"E-MEXP-21"``).
+            destination: Local destination folder.
+            data_type: Download mode: ``"raw"``, ``"processed"``, ``"mage"``, or ``"full"``.
+            extract: Whether zip archives should be unpacked after download.
+            overwrite: Overwrite existing local files when True.
+
+    Returns:
+            A manifest describing downloaded files and extracted contents.
+    """
+    accession = _normalize_accession(accession)
+    data_type = _normalize_type(data_type)
+    destination_path = Path(destination).expanduser().resolve()
+    destination_path.mkdir(parents=True, exist_ok=True)
+
+    study_url = build_url(hostname=_BIOSTUDIES_HOST, path=f"{_STUDIES_PATH}/{accession}")
+    info_url = build_url(hostname=_BIOSTUDIES_HOST, path=f"{_STUDIES_PATH}/{accession}/info")
+    study_payload = _request_json(study_url)
+    info_payload = _request_json(info_url)
+
+    files_base_url = info_payload.get("httpLink")
+    if not isinstance(files_base_url, str) or files_base_url.strip() == "":
+        files_base_url = info_payload.get("ftpLink")
+
+    if not isinstance(files_base_url, str) or files_base_url.strip() == "":
+        raise ArrayExpressError(f"Missing httpLink/ftpLink in BioStudies info payload for accession '{accession}'.")
+
+    if files_base_url.startswith("ftp://"):
+        files_base_url = f"https://{files_base_url[len('ftp://') :]}"
+
+    remote_files = _collect_files(
+        study_payload=study_payload,
+        files_base_url=files_base_url,
+        data_type=data_type,
+    )
+
+    raw_archives: list[str] = []
+    processed_archives: list[str] = []
+    mage_tab_files: list[str] = []
+    adf_files: list[str] = []
+    raw_files: list[str] = []
+    processed_files: list[str] = []
+
+    for remote_file in remote_files:
+        local_path = destination_path / remote_file.path
+        local_path.parent.mkdir(parents=True, exist_ok=True)
+        download_file_stream(url=remote_file.url, output_file=str(local_path), overwrite=overwrite)
+
+        if remote_file.category == "Raw Data":
+            raw_archives.append(str(local_path))
+        elif remote_file.category == "Processed Data":
+            processed_archives.append(str(local_path))
+        elif remote_file.category == "MAGE-TAB Files":
+            mage_tab_files.append(str(local_path))
+        elif remote_file.category == "Array Designs":
+            adf_files.append(str(local_path))
+
+        if extract and local_path.suffix.lower() == ".zip":
+            extracted = _extract_zip_file(local_path)
+            if remote_file.category == "Raw Data":
+                raw_files.extend(extracted)
+            elif remote_file.category == "Processed Data":
+                processed_files.extend(extracted)
+
+    sdrf = next((x for x in mage_tab_files if x.lower().endswith("sdrf.txt")), None)
+    idf = next((x for x in mage_tab_files if x.lower().endswith("idf.txt")), None)
+
+    return ArrayExpressStudyFiles(
+        accession=accession,
+        destination=str(destination_path),
+        data_type=data_type,
+        files=tuple(remote_files),
+        raw_archives=tuple(raw_archives),
+        processed_archives=tuple(processed_archives),
+        mage_tab_files=tuple(mage_tab_files),
+        adf_files=tuple(adf_files),
+        raw_files=tuple(raw_files),
+        processed_files=tuple(processed_files),
+        idf=idf,
+        sdrf=sdrf,
+    )
+
+
+def parse_idf(idf_file: str) -> tuple[dict[str, list[str]], pd.DataFrame]:
+    """Parse an IDF file and return key/value structures.
+
+    Args:
+            idf_file: Path to ``*.idf.txt`` file.
+
+    Returns:
+            Tuple of ``(idf_map, idf_table)`` where ``idf_map`` stores key to list of values,
+            and ``idf_table`` is a normalized long-form dataframe with columns ``key``,
+            ``value_index``, and ``value``.
+    """
+    idf_map: dict[str, list[str]] = {}
+    rows: list[dict[str, Any]] = []
+
+    with open(idf_file, encoding="utf-8") as handle:
+        for line in handle:
+            stripped = line.rstrip("\n")
+            if stripped.strip() == "":
+                continue
+            parts = stripped.split("\t")
+            key = parts[0].strip()
+            values = [value for value in parts[1:] if value != ""]
+            idf_map[key] = values
+            for idx, value in enumerate(values):
+                rows.append({"key": key, "value_index": idx, "value": value})
+
+    return idf_map, pd.DataFrame(rows)
+
+
+def parse_sdrf(sdrf_file: str, deduplicate_array_data_file: bool = True) -> pd.DataFrame:
+    """Parse an SDRF file into a DataFrame.
+
+    Args:
+            sdrf_file: Path to ``*.sdrf.txt`` file.
+            deduplicate_array_data_file: Drop duplicated rows by "Array Data File" when available.
+
+    Returns:
+            DataFrame with SDRF contents.
+    """
+    sdrf = pd.read_csv(sdrf_file, sep="\t", dtype=str, keep_default_na=False)
+    if deduplicate_array_data_file and "Array Data File" in sdrf.columns:
+        sdrf = sdrf.drop_duplicates(subset=["Array Data File"], keep="first")
+    return sdrf.reset_index(drop=True)
+
+
+def _find_adf_header_line(adf_text: str) -> int:
+    with io.StringIO(adf_text) as handle:
+        for idx, line in enumerate(handle):
+            lowered = line.lower()
+            if "reporter name" in lowered:
+                return idx
+            if all(token in lowered for token in ["block", "row", "column"]):
+                return idx
+    raise ValueError("Unable to detect ADF table header.")
+
+
+def parse_adf(adf_file: str) -> pd.DataFrame:
+    """Parse an ADF file by skipping pre-table metadata lines.
+
+    Args:
+            adf_file: Path to ``*.adf.txt`` file.
+
+    Returns:
+            DataFrame with parsed ADF rows.
+    """
+    text = Path(adf_file).read_text(encoding="utf-8", errors="replace")
+    skiprows = _find_adf_header_line(text)
+    return pd.read_csv(adf_file, sep="\t", dtype=str, keep_default_na=False, skiprows=skiprows)
+
+
+def parse_arrayexpress_metadata(files: ArrayExpressStudyFiles) -> ArrayExpressMetadata:
+    """Parse IDF/SDRF/ADF files from a downloaded study manifest.
+
+    Args:
+            files: Result from :func:`get_arrayexpress`.
+
+    Returns:
+            Parsed metadata bundle.
+    """
+    if files.idf is None:
+        raise FileNotFoundError("IDF file was not found in downloaded MAGE-TAB files.")
+
+    idf_map, idf_table = parse_idf(files.idf)
+    sdrf = parse_sdrf(files.sdrf) if files.sdrf is not None else None
+
+    adf_tables: dict[str, pd.DataFrame] = {}
+    for adf_file in files.adf_files:
+        adf_tables[adf_file] = parse_adf(adf_file)
+
+    return ArrayExpressMetadata(idf_map=idf_map, idf_table=idf_table, sdrf=sdrf, adf_tables=adf_tables)
+
+
+def read_arrayexpress_metadata(accession: str, cache_dir: str) -> pd.DataFrame:
+    """Fetch and return sample-level metadata (SDRF) for an ArrayExpress study.
+
+    Args:
+            accession: ArrayExpress accession (for example ``"E-MTAB-1944"``).
+            cache_dir: Local cache root directory used for downloaded study files.
+
+    Returns:
+            A DataFrame with SDRF sample metadata.
+    """
+    accession = _normalize_accession(accession)
+    study_dir = Path(cache_dir).expanduser().resolve() / accession
+    study_dir.mkdir(parents=True, exist_ok=True)
+
+    sdrf = next((str(path) for path in sorted(study_dir.glob("*.sdrf.txt"))), None)
+    if sdrf is None:
+        files = get_arrayexpress(
+            accession=accession,
+            destination=str(study_dir),
+            data_type="mage",
+            extract=False,
+            overwrite=False,
+        )
+        sdrf = files.sdrf
+
+    if sdrf is None:
+        raise FileNotFoundError(f"SDRF file was not found for ArrayExpress accession '{accession}'.")
+
+    return parse_sdrf(sdrf)
+
+
+def read_arrayexpress(
+    accession: str,
+    cache_dir: str,
+    cdf_file: str | CdfFile | None = None,
+    verbose: bool = True,
+) -> AnnData:
+    """Fetch ArrayExpress raw CEL files and return an AnnData object with merged metadata.
+
+    Args:
+            accession: ArrayExpress accession (for example ``"E-MTAB-1944"``).
+            cache_dir: Local cache root directory used for downloaded study files.
+            cdf_file: Optional CDF file path or CdfFile object. If omitted, infer from Array Design accession.
+            verbose: If True, show progress while reading CEL files.
+
+    Returns:
+            Probe-level AnnData with sample metadata merged into ``adata.obs``.
+    """
+    accession = _normalize_accession(accession)
+    study_dir = Path(cache_dir).expanduser().resolve() / accession
+    study_dir.mkdir(parents=True, exist_ok=True)
+
+    metadata = read_arrayexpress_metadata(accession=accession, cache_dir=cache_dir)
+
+    cel_paths = _collect_cel_paths_recursive(study_dir)
+    if len(cel_paths) == 0:
+        get_arrayexpress(
+            accession=accession,
+            destination=str(study_dir),
+            data_type="raw",
+            extract=True,
+            overwrite=False,
+        )
+        cel_paths = _collect_cel_paths_recursive(study_dir)
+
+    if len(cel_paths) == 0:
+        raise FileNotFoundError(f"No CEL files were found for ArrayExpress accession '{accession}'.")
+
+    resolved_cdf = _resolve_arrayexpress_cdf(accession=accession, cdf_file=cdf_file)
+
+    batch: list[AnnData] = []
+    iterator = cel_paths if not verbose else cel_paths
+    for cel_path in iterator:
+        batch.append(read_cel(str(cel_path), resolved_cdf))
+
+    adata = concat(batch, axis=0, merge="same", join="outer")
+
+    obs = adata.obs.copy()
+    obs["_obs_file_key"] = [(_normalize_file_key(index) or "") for index in obs.index]
+
+    meta = metadata.copy()
+    array_data_col = next((col for col in meta.columns if col.lower() == "array data file"), None)
+    if array_data_col is None:
+        adata.obs = obs.drop(columns=["_obs_file_key"], errors="ignore")
+        return adata
+
+    meta["_meta_file_key"] = meta[array_data_col].map(lambda x: _normalize_file_key(x) or "")
+    meta_by_file = meta.loc[meta["_meta_file_key"] != ""].drop_duplicates("_meta_file_key").set_index("_meta_file_key")
+
+    merged = obs.join(meta_by_file, on="_obs_file_key", rsuffix="_meta")
+    merged = merged.drop(columns=["_obs_file_key"], errors="ignore")
+    merged = merged.drop(columns=["_meta_file_key"], errors="ignore")
+    adata.obs = merged
+
+    return adata