omicsync 0.1.0__py3-none-any.whl

omicsync/normalisation/rna.py

@@ -0,0 +1,182 @@
+"""RNA-seq normalisation methods."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+from omicsync.utils.logging import get_logger
+
+logger = get_logger("normalisation.rna")
+
+
+def log1p_normalise(df: pd.DataFrame) -> pd.DataFrame:
+    """Apply log1p transform to all values.
+
+    Parameters
+    ----------
+    df:
+        Expression matrix (samples × features). Values must be non-negative.
+
+    Returns
+    -------
+    pandas.DataFrame
+        log1p-transformed matrix with same index and columns.
+    """
+    result = np.log1p(df.values.astype(float))
+    logger.info("log1p_normalise: applied to %s.", df.shape)
+    return pd.DataFrame(result, index=df.index, columns=df.columns)
+
+
+def tpm_to_log1p(df: pd.DataFrame) -> pd.DataFrame:
+    """Apply log1p to a TPM expression matrix.
+
+    Parameters
+    ----------
+    df:
+        TPM expression matrix (samples × genes).
+
+    Returns
+    -------
+    pandas.DataFrame
+        log1p(TPM) matrix.
+    """
+    logger.info("tpm_to_log1p: applying log1p to TPM matrix %s.", df.shape)
+    return log1p_normalise(df)
+
+
+def counts_to_tpm(df: pd.DataFrame, gene_lengths: pd.Series) -> pd.DataFrame:
+    """Convert raw counts to TPM using gene lengths.
+
+    Parameters
+    ----------
+    df:
+        Raw count matrix (samples × genes).
+    gene_lengths:
+        Gene lengths in base pairs, indexed by gene ID matching *df* columns.
+
+    Returns
+    -------
+    pandas.DataFrame
+        TPM matrix.
+
+    Raises
+    ------
+    ValueError
+        If gene lengths are missing for any column in *df*.
+    """
+    missing = df.columns.difference(gene_lengths.index)
+    if len(missing) > 0:
+        raise ValueError(
+            f"Gene lengths missing for {len(missing)} genes: {missing[:5].tolist()}..."
+        )
+    lengths = gene_lengths.reindex(df.columns).values.astype(float)
+    rpk = df.values.astype(float) / (lengths / 1e3)
+    scaling = rpk.sum(axis=1, keepdims=True) / 1e6
+    tpm = rpk / np.where(scaling == 0, 1.0, scaling)
+    logger.info("counts_to_tpm: converted %s to TPM.", df.shape)
+    return pd.DataFrame(tpm, index=df.index, columns=df.columns)
+
+
+def quantile_normalise(df: pd.DataFrame) -> pd.DataFrame:
+    """Quantile normalise a matrix so each sample has the same distribution.
+
+    Parameters
+    ----------
+    df:
+        Expression matrix (samples × features).
+
+    Returns
+    -------
+    pandas.DataFrame
+        Quantile-normalised matrix.
+    """
+    data = df.values.astype(float).copy()
+    n_samples, n_features = data.shape
+
+    sort_indices = np.argsort(data, axis=1)
+    sorted_data = np.sort(data, axis=1)
+    row_means = sorted_data.mean(axis=0)
+
+    result = np.empty_like(data)
+    for i in range(n_samples):
+        result[i, sort_indices[i]] = row_means
+
+    logger.info("quantile_normalise: applied to %s.", df.shape)
+    return pd.DataFrame(result, index=df.index, columns=df.columns)
+
+
+def z_score(df: pd.DataFrame, axis: int = 0) -> pd.DataFrame:
+    """Z-score normalise the expression matrix.
+
+    Parameters
+    ----------
+    df:
+        Expression matrix.
+    axis:
+        ``0`` to z-score per feature (column), ``1`` to z-score per sample (row).
+
+    Returns
+    -------
+    pandas.DataFrame
+        Z-scored matrix. Constant features/samples are set to 0.
+    """
+    data = df.values.astype(float)
+    mu = np.nanmean(data, axis=axis, keepdims=True)
+    sd = np.nanstd(data, axis=axis, keepdims=True)
+    sd = np.where(sd == 0, 1.0, sd)
+    result = (data - mu) / sd
+    logger.info("z_score: applied along axis=%d to %s.", axis, df.shape)
+    return pd.DataFrame(result, index=df.index, columns=df.columns)
+
+
+def detect_and_normalise(df: pd.DataFrame) -> pd.DataFrame:
+    """Auto-detect RNA value type and apply appropriate normalisation.
+
+    Heuristic:
+
+    * If max value > 50 and median > 5 → assume raw counts, apply log1p.
+    * If max value in [0.1, 50] and median < 5 → assume TPM, apply log1p.
+    * Otherwise → assume already normalised, return as-is.
+
+    Parameters
+    ----------
+    df:
+        RNA expression matrix (samples × features).
+
+    Returns
+    -------
+    pandas.DataFrame
+        Normalised matrix.
+    """
+    vals = df.values.ravel().astype(float)
+    finite = vals[np.isfinite(vals) & (vals >= 0)]
+    if len(finite) == 0:
+        logger.warning("detect_and_normalise: no finite non-negative values; skipping.")
+        return df
+
+    vmax = finite.max()
+    vmedian = np.median(finite)
+
+    if vmax > 50 and vmedian > 5:
+        logger.info(
+            "detect_and_normalise: detected raw counts (max=%.1f, median=%.2f); "
+            "applying log1p.",
+            vmax, vmedian,
+        )
+        return log1p_normalise(df)
+    elif vmax > 0.1:
+        logger.info(
+            "detect_and_normalise: detected TPM-like values (max=%.1f, median=%.2f); "
+            "applying log1p.",
+            vmax, vmedian,
+        )
+        return tpm_to_log1p(df)
+    else:
+        logger.info(
+            "detect_and_normalise: values appear already normalised "
+            "(max=%.4f, median=%.4f); returning as-is.",
+            vmax, vmedian,
+        )
+        return df

omicsync/utils/__init__.py

@@ -0,0 +1,32 @@
+"""Utility modules for omicsync."""
+
+from omicsync.utils.logging import get_logger, set_verbose
+from omicsync.utils.validation import (
+    validate_dataframe,
+    validate_modality_type,
+    check_value_range,
+    validate_sample_ids,
+)
+from omicsync.utils.barcode import (
+    parse_barcode,
+    truncate_to_participant,
+    truncate_to_sample,
+    is_tumour,
+    is_normal,
+    batch_parse,
+)
+
+__all__ = [
+    "get_logger",
+    "set_verbose",
+    "validate_dataframe",
+    "validate_modality_type",
+    "check_value_range",
+    "validate_sample_ids",
+    "parse_barcode",
+    "truncate_to_participant",
+    "truncate_to_sample",
+    "is_tumour",
+    "is_normal",
+    "batch_parse",
+]

omicsync/utils/barcode.py

@@ -0,0 +1,165 @@
+"""TCGA barcode parsing utilities."""
+
+from __future__ import annotations
+
+from typing import List, Sequence
+
+import pandas as pd
+
+# TCGA barcode structure:
+# TCGA-{TSS}-{Participant}-{Sample}{Vial}-{Portion}{Analyte}-{Plate}-{Centre}
+# e.g. TCGA-02-0001-01A-01R-0177-13
+#        0    1   2    3     4      5    6   (dash-split index)
+# Sample type codes: 01-09 = tumour; 10-19 = normal; 20-29 = control
+
+
+def parse_barcode(barcode: str) -> dict:
+    """Parse a TCGA barcode into its component fields.
+
+    Parameters
+    ----------
+    barcode:
+        A full TCGA aliquot barcode, e.g. ``"TCGA-02-0001-01A-01R-0177-13"``.
+
+    Returns
+    -------
+    dict
+        Keys: ``project``, ``tss``, ``participant``, ``sample``, ``vial``,
+        ``portion``, ``analyte``, ``plate``, ``centre``.  Missing trailing
+        fields are ``None``.
+
+    Raises
+    ------
+    ValueError
+        If the barcode does not start with ``"TCGA-"``.
+    """
+    barcode = barcode.strip()
+    if not barcode.upper().startswith("TCGA-"):
+        raise ValueError(f"Not a valid TCGA barcode: {barcode!r}")
+
+    parts = barcode.split("-")
+    result: dict = {
+        "project": parts[0] if len(parts) > 0 else None,
+        "tss": parts[1] if len(parts) > 1 else None,
+        "participant": parts[2] if len(parts) > 2 else None,
+        "sample": parts[3][:2] if len(parts) > 3 else None,
+        "vial": parts[3][2:] if len(parts) > 3 and len(parts[3]) > 2 else None,
+        "portion": parts[4][:2] if len(parts) > 4 else None,
+        "analyte": parts[4][2:] if len(parts) > 4 and len(parts[4]) > 2 else None,
+        "plate": parts[5] if len(parts) > 5 else None,
+        "centre": parts[6] if len(parts) > 6 else None,
+    }
+    return result
+
+
+def truncate_to_participant(barcode: str) -> str:
+    """Return the participant-level ID (first 12 characters).
+
+    Parameters
+    ----------
+    barcode:
+        Full or partial TCGA barcode.
+
+    Returns
+    -------
+    str
+        E.g. ``"TCGA-02-0001"``.
+    """
+    parts = barcode.strip().split("-")
+    if len(parts) < 3:
+        raise ValueError(
+            f"Barcode {barcode!r} does not contain enough fields to extract "
+            "a participant ID."
+        )
+    return "-".join(parts[:3])
+
+
+def truncate_to_sample(barcode: str) -> str:
+    """Return the sample-level ID (first 15–16 characters, through sample+vial).
+
+    Parameters
+    ----------
+    barcode:
+        Full or partial TCGA barcode.
+
+    Returns
+    -------
+    str
+        E.g. ``"TCGA-02-0001-01A"``.
+    """
+    parts = barcode.strip().split("-")
+    if len(parts) < 4:
+        raise ValueError(
+            f"Barcode {barcode!r} does not contain enough fields to extract "
+            "a sample ID."
+        )
+    return "-".join(parts[:4])
+
+
+def is_tumour(barcode: str) -> bool:
+    """Return ``True`` if the barcode represents a tumour sample (type 01-09).
+
+    Parameters
+    ----------
+    barcode:
+        Full or partial TCGA barcode.
+    """
+    parts = barcode.strip().split("-")
+    if len(parts) < 4:
+        return False
+    sample_code = parts[3][:2]
+    try:
+        return 1 <= int(sample_code) <= 9
+    except ValueError:
+        return False
+
+
+def is_normal(barcode: str) -> bool:
+    """Return ``True`` if the barcode represents a normal sample (type 10-19).
+
+    Parameters
+    ----------
+    barcode:
+        Full or partial TCGA barcode.
+    """
+    parts = barcode.strip().split("-")
+    if len(parts) < 4:
+        return False
+    sample_code = parts[3][:2]
+    try:
+        return 10 <= int(sample_code) <= 19
+    except ValueError:
+        return False
+
+
+def batch_parse(barcodes: Sequence[str]) -> pd.DataFrame:
+    """Parse a sequence of TCGA barcodes into a DataFrame.
+
+    Parameters
+    ----------
+    barcodes:
+        Iterable of TCGA barcode strings.
+
+    Returns
+    -------
+    pandas.DataFrame
+        One row per barcode; columns match the keys of :func:`parse_barcode`,
+        plus ``is_tumour`` and ``is_normal`` boolean columns.
+    """
+    rows = []
+    for bc in barcodes:
+        try:
+            row = parse_barcode(bc)
+        except ValueError:
+            row = {k: None for k in [
+                "project", "tss", "participant", "sample",
+                "vial", "portion", "analyte", "plate", "centre"
+            ]}
+        row["barcode"] = bc
+        row["is_tumour"] = is_tumour(bc)
+        row["is_normal"] = is_normal(bc)
+        rows.append(row)
+    df = pd.DataFrame(rows)
+    cols = ["barcode", "project", "tss", "participant", "sample", "vial",
+            "portion", "analyte", "plate", "centre", "is_tumour", "is_normal"]
+    return df[[c for c in cols if c in df.columns]]

omicsync/utils/logging.py

@@ -0,0 +1,44 @@
+"""Consistent logging setup for omicsync."""
+
+import logging
+from typing import Optional
+
+_logger = logging.getLogger("omicsync")
+
+if not _logger.handlers:
+    _handler = logging.StreamHandler()
+    _handler.setFormatter(
+        logging.Formatter("%(asctime)s [%(levelname)s] omicsync: %(message)s",
+                          datefmt="%H:%M:%S")
+    )
+    _logger.addHandler(_handler)
+    _logger.setLevel(logging.WARNING)
+
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    """Return the omicsync logger or a child logger.
+
+    Parameters
+    ----------
+    name:
+        Optional child name, e.g. ``"loaders.csv"``.
+
+    Returns
+    -------
+    logging.Logger
+    """
+    if name:
+        return logging.getLogger(f"omicsync.{name}")
+    return _logger
+
+
+def set_verbose(verbose: bool) -> None:
+    """Enable or disable verbose (INFO-level) logging.
+
+    Parameters
+    ----------
+    verbose:
+        ``True`` to enable INFO logging, ``False`` to restore WARNING level.
+    """
+    level = logging.INFO if verbose else logging.WARNING
+    _logger.setLevel(level)

omicsync/utils/validation.py

@@ -0,0 +1,152 @@
+"""Input validation helpers for omicsync."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+import numpy as np
+import pandas as pd
+
+from omicsync.utils.logging import get_logger
+
+logger = get_logger("utils.validation")
+
+VALID_MODALITY_TYPES = frozenset(
+    {"rna", "mutations", "methylation", "cnv", "protein"}
+)
+
+
+def validate_dataframe(
+    df: pd.DataFrame,
+    name: str,
+    min_samples: int = 1,
+    min_features: int = 1,
+) -> None:
+    """Validate that *df* is a non-empty DataFrame with the expected shape.
+
+    Parameters
+    ----------
+    df:
+        DataFrame to validate.
+    name:
+        Human-readable name used in error messages.
+    min_samples:
+        Minimum number of rows required.
+    min_features:
+        Minimum number of columns required.
+
+    Raises
+    ------
+    TypeError
+        If *df* is not a :class:`pandas.DataFrame`.
+    ValueError
+        If the DataFrame does not meet size requirements.
+    """
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError(f"{name} must be a pandas DataFrame, got {type(df).__name__}.")
+    if df.shape[0] < min_samples:
+        raise ValueError(
+            f"{name} must have at least {min_samples} sample(s); got {df.shape[0]}."
+        )
+    if df.shape[1] < min_features:
+        raise ValueError(
+            f"{name} must have at least {min_features} feature(s); got {df.shape[1]}."
+        )
+
+
+def validate_modality_type(modality_type: str) -> None:
+    """Raise :exc:`ValueError` if *modality_type* is not a recognised type.
+
+    Parameters
+    ----------
+    modality_type:
+        One of ``"rna"``, ``"mutations"``, ``"methylation"``, ``"cnv"``,
+        ``"protein"``.
+
+    Raises
+    ------
+    ValueError
+        If *modality_type* is unrecognised.
+    """
+    if modality_type not in VALID_MODALITY_TYPES:
+        raise ValueError(
+            f"Unknown modality_type {modality_type!r}. "
+            f"Valid types: {sorted(VALID_MODALITY_TYPES)}."
+        )
+
+
+def check_value_range(df: pd.DataFrame, modality_type: str) -> None:
+    """Warn if values in *df* look unusual for the given modality type.
+
+    Parameters
+    ----------
+    df:
+        Feature matrix (samples × features).
+    modality_type:
+        One of the recognised omicsync modality types.
+    """
+    values = df.values.ravel()
+    finite = values[np.isfinite(values)]
+    if len(finite) == 0:
+        logger.warning("DataFrame contains no finite values.")
+        return
+
+    vmin, vmax, vmean = finite.min(), finite.max(), finite.mean()
+
+    if modality_type == "rna":
+        if vmin < 0:
+            logger.warning(
+                "RNA modality: found negative values (min=%.4f). "
+                "Expected non-negative counts or expression values.",
+                vmin,
+            )
+    elif modality_type == "methylation":
+        if vmax > 1.05 or vmin < -1.05:
+            logger.warning(
+                "Methylation modality: values outside [-1, 1] detected "
+                "(min=%.4f, max=%.4f). Beta values should be in [0, 1]; "
+                "M-values typically in [-5, 5].",
+                vmin,
+                vmax,
+            )
+    elif modality_type == "mutations":
+        unique = np.unique(finite)
+        if not np.all(np.isin(unique, [0.0, 1.0])):
+            logger.warning(
+                "Mutation modality: non-binary values detected. "
+                "Consider calling binarise() first."
+            )
+    elif modality_type == "protein":
+        if abs(vmean) > 10:
+            logger.warning(
+                "Protein modality: mean value %.4f seems high. "
+                "Consider z-score normalisation.",
+                vmean,
+            )
+
+
+def validate_sample_ids(ids: Sequence) -> None:
+    """Check sample IDs for duplicates, NaN, and empty strings.
+
+    Parameters
+    ----------
+    ids:
+        Sequence of sample identifiers.
+
+    Raises
+    ------
+    ValueError
+        If any ID is NaN, empty, or duplicated.
+    """
+    seen: set = set()
+    duplicates: list = []
+    for idx, sid in enumerate(ids):
+        if sid is None or (isinstance(sid, float) and np.isnan(sid)):
+            raise ValueError(f"Sample ID at position {idx} is NaN/None.")
+        if isinstance(sid, str) and sid.strip() == "":
+            raise ValueError(f"Sample ID at position {idx} is an empty string.")
+        if sid in seen:
+            duplicates.append(sid)
+        seen.add(sid)
+    if duplicates:
+        raise ValueError(f"Duplicate sample IDs found: {duplicates[:10]}.")