omicsync 0.1.0__py3-none-any.whl

omicsync/loaders/csv.py

@@ -0,0 +1,147 @@
+"""Generic CSV/TSV loader for omicsync."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Dict, Optional, Union
+
+import pandas as pd
+
+from omicsync.core.dataset import OmicsDataset
+from omicsync.core.modality import make_modality, OmicsModality
+from omicsync.utils.logging import get_logger
+from omicsync.utils.validation import validate_modality_type
+
+logger = get_logger("loaders.csv")
+
+
+def _detect_separator(path: Union[str, Path]) -> str:
+    path = Path(path)
+    suffix = path.suffix.lower()
+    if suffix in (".tsv", ".txt"):
+        return "\t"
+    if suffix == ".csv":
+        return ","
+    # Peek at first line to detect
+    with open(path, "r", encoding="utf-8") as fh:
+        first_line = fh.readline()
+    if first_line.count("\t") > first_line.count(","):
+        return "\t"
+    return ","
+
+
+def load_csv(
+    path: Union[str, Path],
+    modality_type: str,
+    sample_col: Optional[str] = "sample_id",
+    feature_orientation: str = "samples_as_rows",
+    source: str = "csv",
+    **kwargs,
+) -> OmicsModality:
+    """Load a single CSV/TSV file into an :class:`~omicsync.core.modality.OmicsModality`.
+
+    Parameters
+    ----------
+    path:
+        Path to the CSV or TSV file.
+    modality_type:
+        One of ``"rna"``, ``"mutations"``, ``"methylation"``, ``"cnv"``,
+        ``"protein"``.
+    sample_col:
+        Name of the column that contains sample IDs when
+        ``feature_orientation="samples_as_rows"``.  Set to ``None`` to use the
+        existing index.  Ignored when ``feature_orientation="samples_as_columns"``.
+    feature_orientation:
+        ``"samples_as_rows"`` (default) — rows are samples, columns are
+        features.  ``"samples_as_columns"`` — transpose after reading.
+    source:
+        Source label stored in the modality metadata.
+    **kwargs:
+        Additional keyword arguments forwarded to :func:`pandas.read_csv`.
+
+    Returns
+    -------
+    OmicsModality
+        The appropriate modality subclass.
+
+    Raises
+    ------
+    FileNotFoundError
+        If *path* does not exist.
+    ValueError
+        If *modality_type* or *feature_orientation* is invalid.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    validate_modality_type(modality_type)
+    if feature_orientation not in ("samples_as_rows", "samples_as_columns"):
+        raise ValueError(
+            f"Unknown feature_orientation {feature_orientation!r}. "
+            "Valid: 'samples_as_rows', 'samples_as_columns'."
+        )
+
+    sep = kwargs.pop("sep", _detect_separator(path))
+    df = pd.read_csv(path, sep=sep, **kwargs)
+
+    if feature_orientation == "samples_as_rows":
+        if sample_col is not None:
+            if sample_col not in df.columns:
+                raise ValueError(
+                    f"sample_col={sample_col!r} not found in columns: {df.columns.tolist()[:10]}..."
+                )
+            df = df.set_index(sample_col)
+    else:
+        if sample_col is not None and sample_col in df.columns:
+            df = df.set_index(sample_col)
+        df = df.T
+
+    df = df.apply(pd.to_numeric, errors="coerce")
+
+    logger.info(
+        "load_csv: loaded %s modality from %s — shape %s.",
+        modality_type,
+        path.name,
+        df.shape,
+    )
+    return make_modality(df, modality_type=modality_type, source=source)
+
+
+def load_multimodal_csv(
+    paths_dict: Dict[str, Union[str, Path]],
+    modality_types: Optional[Dict[str, str]] = None,
+    study_id: str = "custom",
+    **kwargs,
+) -> OmicsDataset:
+    """Load multiple CSV/TSV files into an :class:`~omicsync.core.dataset.OmicsDataset`.
+
+    Parameters
+    ----------
+    paths_dict:
+        Mapping from modality name to file path.
+    modality_types:
+        Mapping from modality name to modality_type string.  If ``None``,
+        the modality name itself is used as the type.
+    study_id:
+        Study identifier for the resulting dataset.
+    **kwargs:
+        Forwarded to :func:`load_csv` for every modality.
+
+    Returns
+    -------
+    OmicsDataset
+
+    Raises
+    ------
+    ValueError
+        If a modality name cannot be resolved to a valid modality type.
+    """
+    modalities: Dict[str, OmicsModality] = {}
+    for name, path in paths_dict.items():
+        mtype = (modality_types or {}).get(name, name)
+        logger.info("load_multimodal_csv: loading %r from %s.", name, path)
+        modalities[name] = load_csv(path, modality_type=mtype, **kwargs)
+
+    return OmicsDataset(modalities, study_id=study_id)

omicsync/loaders/geo.py

@@ -0,0 +1,111 @@
+"""GEO loader using GEOparse."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+from omicsync.core.modality import make_modality, OmicsModality
+from omicsync.utils.logging import get_logger
+
+logger = get_logger("loaders.geo")
+
+
+def load_geo(
+    accession: str,
+    modality_type: str,
+    destdir: str = ".",
+    silent: bool = True,
+    **kwargs,
+) -> OmicsModality:
+    """Download and parse a GEO series into an :class:`~omicsync.core.modality.OmicsModality`.
+
+    Requires ``GEOparse`` to be installed (``pip install GEOparse``).
+
+    Parameters
+    ----------
+    accession:
+        GEO series accession, e.g. ``"GSE12345"``.
+    modality_type:
+        One of ``"rna"``, ``"mutations"``, ``"methylation"``, ``"cnv"``,
+        ``"protein"``.
+    destdir:
+        Directory to download GEO files into.
+    silent:
+        Suppress GEOparse download progress output (default ``True``).
+    **kwargs:
+        Additional keyword arguments forwarded to
+        :func:`GEOparse.get_GEO`.
+
+    Returns
+    -------
+    OmicsModality
+
+    Raises
+    ------
+    ImportError
+        If ``GEOparse`` is not installed.
+    ValueError
+        If the series has no usable expression matrix.
+    """
+    try:
+        import GEOparse
+    except ImportError as exc:
+        raise ImportError(
+            "GEOparse is required for load_geo(). "
+            "Install it with: pip install GEOparse"
+        ) from exc
+
+    logger.info("load_geo: fetching %s from NCBI GEO.", accession)
+    gse = GEOparse.get_GEO(accession, destdir=destdir, silent=silent, **kwargs)
+
+    platforms = gse.gpls
+    if len(platforms) > 1:
+        logger.warning(
+            "load_geo: %s has %d platforms (%s). "
+            "Using first platform; consider filtering manually.",
+            accession,
+            len(platforms),
+            list(platforms.keys()),
+        )
+
+    # Build expression matrix from GSMs
+    gsms = gse.gsms
+    if not gsms:
+        raise ValueError(f"GEO series {accession} contains no samples (GSMs).")
+
+    frames = {}
+    for sample_name, gsm in gsms.items():
+        table = gsm.table
+        if table.empty:
+            logger.warning("load_geo: sample %s has an empty table; skipping.", sample_name)
+            continue
+        # Detect value column: prefer "VALUE", else first numeric column
+        value_col = "VALUE" if "VALUE" in table.columns else None
+        if value_col is None:
+            for col in table.columns:
+                if col != "ID_REF" and pd.api.types.is_numeric_dtype(table[col]):
+                    value_col = col
+                    break
+        if value_col is None:
+            logger.warning("load_geo: cannot find value column in sample %s.", sample_name)
+            continue
+        id_col = "ID_REF" if "ID_REF" in table.columns else table.columns[0]
+        frames[sample_name] = table.set_index(id_col)[value_col]
+
+    if not frames:
+        raise ValueError(f"No usable data found in GEO series {accession}.")
+
+    df = pd.DataFrame(frames).T
+    df.index.name = "sample_id"
+    df = df.apply(pd.to_numeric, errors="coerce")
+
+    logger.info(
+        "load_geo: loaded %s — %d samples × %d features.",
+        accession,
+        df.shape[0],
+        df.shape[1],
+    )
+    return make_modality(df, modality_type=modality_type, source=f"geo:{accession}")

omicsync/loaders/open_targets.py

@@ -0,0 +1,239 @@
+"""Open Targets Platform GraphQL API loader."""
+
+from __future__ import annotations
+
+import time
+from typing import Dict, List, Optional, Sequence
+
+import numpy as np
+import pandas as pd
+import requests
+
+from omicsync.core.dataset import OmicsDataset
+from omicsync.utils.logging import get_logger
+
+logger = get_logger("loaders.open_targets")
+
+_OT_GRAPHQL_URL = "https://api.platform.opentargets.org/api/v4/graphql"
+
+_ASSOCIATION_QUERY = """
+query targetDiseaseAssociations(
+    $diseaseIds: [String!],
+    $targetIds: [String!],
+    $size: Int!,
+    $cursor: String
+) {
+    associations: associatedTargets(
+        diseaseIds: $diseaseIds
+        size: $size
+        cursor: $cursor
+    ) {
+        count
+        cursor
+        rows {
+            target {
+                id
+                approvedSymbol
+            }
+            disease {
+                id
+                name
+            }
+            score
+            datatypeScores {
+                id
+                score
+            }
+        }
+    }
+}
+"""
+
+_DATATYPE_COLUMNS = {
+    "genetic_association": "genetic_association",
+    "somatic_mutation": "somatic_mutation",
+    "literature": "literature",
+    "rna_expression": "rna_expression",
+    "animal_model": "animal_model",
+    "affected_pathway": "affected_pathway",
+}
+
+
+def _graphql_request(
+    payload: Dict,
+    url: str = _OT_GRAPHQL_URL,
+    max_retries: int = 5,
+    backoff_factor: float = 1.0,
+) -> Dict:
+    """Execute a GraphQL query with exponential backoff."""
+    for attempt in range(max_retries):
+        try:
+            response = requests.post(url, json=payload, timeout=30)
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as exc:
+            if attempt == max_retries - 1:
+                raise RuntimeError(
+                    f"Open Targets API request failed after {max_retries} attempts: {exc}"
+                ) from exc
+            wait = backoff_factor * (2 ** attempt)
+            logger.warning(
+                "Open Targets request failed (attempt %d/%d); retrying in %.1fs.",
+                attempt + 1, max_retries, wait,
+            )
+            time.sleep(wait)
+    raise RuntimeError("Unreachable")  # pragma: no cover
+
+
+def load_open_targets_targets(
+    disease_ids: Optional[Sequence[str]] = None,
+    target_ids: Optional[Sequence[str]] = None,
+    evidence_types: Optional[Sequence[str]] = None,
+    score_threshold: float = 0.0,
+    page_size: int = 200,
+) -> pd.DataFrame:
+    """Query Open Targets Platform for target-disease associations.
+
+    Parameters
+    ----------
+    disease_ids:
+        EFO disease IDs to filter on, e.g. ``["EFO_0000305"]``.
+        At least one of *disease_ids* or *target_ids* must be provided.
+    target_ids:
+        Ensembl gene IDs to filter on, e.g. ``["ENSG00000141736"]``.
+    evidence_types:
+        Evidence types to include in results.  ``None`` returns all.
+        Valid keys: ``"genetic_association"``, ``"somatic_mutation"``,
+        ``"literature"``, ``"rna_expression"``, ``"animal_model"``,
+        ``"affected_pathway"``.
+    score_threshold:
+        Minimum overall association score (0–1).
+    page_size:
+        Results per API page.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Columns: ``target_id``, ``target_name``, ``disease_id``,
+        ``disease_name``, ``overall_score``, plus one column per evidence
+        datatype.
+
+    Raises
+    ------
+    ValueError
+        If neither *disease_ids* nor *target_ids* is provided.
+    """
+    if disease_ids is None and target_ids is None:
+        raise ValueError("Provide at least one of disease_ids or target_ids.")
+
+    rows: List[Dict] = []
+    cursor: Optional[str] = None
+    total_fetched = 0
+
+    while True:
+        variables: Dict = {"size": page_size}
+        if disease_ids:
+            variables["diseaseIds"] = list(disease_ids)
+        if cursor:
+            variables["cursor"] = cursor
+
+        result = _graphql_request({"query": _ASSOCIATION_QUERY, "variables": variables})
+
+        data = result.get("data", {}).get("associations", {})
+        page_rows = data.get("rows", [])
+        cursor = data.get("cursor")
+
+        for row in page_rows:
+            target = row.get("target", {})
+            disease = row.get("disease", {})
+            overall_score = row.get("score", 0.0) or 0.0
+
+            if overall_score < score_threshold:
+                continue
+
+            record: Dict = {
+                "target_id": target.get("id"),
+                "target_name": target.get("approvedSymbol"),
+                "disease_id": disease.get("id"),
+                "disease_name": disease.get("name"),
+                "overall_score": overall_score,
+            }
+
+            dt_scores = {s["id"]: s["score"] for s in row.get("datatypeScores", [])}
+            for col, key in _DATATYPE_COLUMNS.items():
+                record[col] = dt_scores.get(key, np.nan)
+
+            rows.append(record)
+
+        total_fetched += len(page_rows)
+        logger.info("load_open_targets_targets: fetched %d associations so far.", total_fetched)
+
+        if not cursor or len(page_rows) < page_size:
+            break
+
+    if not rows:
+        logger.warning("load_open_targets_targets: no associations returned.")
+        return pd.DataFrame(columns=[
+            "target_id", "target_name", "disease_id", "disease_name",
+            "overall_score", *list(_DATATYPE_COLUMNS.keys()),
+        ])
+
+    df = pd.DataFrame(rows)
+
+    if evidence_types is not None:
+        keep = set(evidence_types) & set(_DATATYPE_COLUMNS.keys())
+        if not keep:
+            logger.warning(
+                "load_open_targets_targets: none of %s are valid evidence types.", evidence_types
+            )
+        else:
+            df = df[df[list(keep)].notna().any(axis=1)]
+
+    logger.info(
+        "load_open_targets_targets: returned %d associations.", len(df)
+    )
+    return df.reset_index(drop=True)
+
+
+def add_open_targets_annotations(
+    dataset: OmicsDataset,
+    target_column: str = "gene_id",
+    disease_ids: Optional[Sequence[str]] = None,
+    **kwargs,
+) -> OmicsDataset:
+    """Annotate feature metadata in an OmicsDataset with Open Targets scores.
+
+    Queries Open Targets for each feature in the RNA modality (or any modality
+    whose feature IDs look like gene symbols or Ensembl IDs) and attaches the
+    association scores as feature-level metadata.
+
+    Parameters
+    ----------
+    dataset:
+        An :class:`~omicsync.core.dataset.OmicsDataset`.
+    target_column:
+        Column in the annotation DataFrame corresponding to gene identifiers.
+    disease_ids:
+        Disease IDs to query.  Forwarded to :func:`load_open_targets_targets`.
+    **kwargs:
+        Forwarded to :func:`load_open_targets_targets`.
+
+    Returns
+    -------
+    OmicsDataset
+        *dataset* with ``open_targets`` key added to each modality's metadata.
+    """
+    ot_df = load_open_targets_targets(disease_ids=disease_ids, **kwargs)
+
+    for name, mod in dataset._modalities.items():
+        feature_ids = mod.feature_ids.tolist()
+        ann = ot_df[ot_df["target_name"].isin(feature_ids)].copy()
+        mod.metadata["open_targets"] = ann
+        logger.info(
+            "add_open_targets_annotations: %d/%d features annotated for modality %r.",
+            len(ann["target_name"].unique()),
+            len(feature_ids),
+            name,
+        )
+
+    return dataset