omicsync 0.1.0__py3-none-any.whl

omicsync/core/modality.py

@@ -0,0 +1,398 @@
+"""OmicsModality base class and modality-specific subclasses."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Sequence
+
+import numpy as np
+import pandas as pd
+
+from omicsync.utils.logging import get_logger
+from omicsync.utils.validation import (
+    validate_dataframe,
+    validate_modality_type,
+    check_value_range,
+    validate_sample_ids,
+)
+
+logger = get_logger("core.modality")
+
+
+class OmicsModality:
+    """Container for a single omics modality (samples × features).
+
+    Parameters
+    ----------
+    data:
+        DataFrame indexed by sample IDs, columns are feature IDs.
+    modality_type:
+        One of ``"rna"``, ``"mutations"``, ``"methylation"``, ``"cnv"``,
+        ``"protein"``.
+    source:
+        Data source identifier, e.g. ``"tcga"``, ``"geo"``, ``"csv"``.
+    metadata:
+        Arbitrary key/value metadata stored alongside the data.
+
+    Raises
+    ------
+    ValueError
+        If *modality_type* is invalid or the DataFrame is malformed.
+    """
+
+    def __init__(
+        self,
+        data: pd.DataFrame,
+        modality_type: str,
+        source: str = "unknown",
+        metadata: Optional[Dict] = None,
+    ) -> None:
+        validate_modality_type(modality_type)
+        validate_dataframe(data, name=f"{modality_type} data")
+        validate_sample_ids(data.index.tolist())
+
+        self._data = data.copy()
+        self.modality_type = modality_type
+        self.source = source
+        self.metadata: Dict = metadata or {}
+
+        check_value_range(self._data, self.modality_type)
+        logger.info(
+            "Loaded %s modality from %s: %d samples × %d features.",
+            modality_type,
+            source,
+            self.n_samples,
+            self.n_features,
+        )
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def data(self) -> pd.DataFrame:
+        """The underlying data matrix (samples × features)."""
+        return self._data
+
+    @property
+    def n_samples(self) -> int:
+        """Number of samples (rows)."""
+        return self._data.shape[0]
+
+    @property
+    def n_features(self) -> int:
+        """Number of features (columns)."""
+        return self._data.shape[1]
+
+    @property
+    def sample_ids(self) -> pd.Index:
+        """Sample identifiers (row index)."""
+        return self._data.index
+
+    @property
+    def feature_ids(self) -> pd.Index:
+        """Feature identifiers (column index)."""
+        return self._data.columns
+
+    # ------------------------------------------------------------------
+    # Methods
+    # ------------------------------------------------------------------
+
+    def filter_features(
+        self,
+        min_variance: float = 0.0,
+        min_nonzero_frac: float = 0.0,
+    ) -> "OmicsModality":
+        """Remove low-information features in-place and return *self*.
+
+        Parameters
+        ----------
+        min_variance:
+            Drop features whose variance is below this threshold.
+        min_nonzero_frac:
+            Drop features where the fraction of non-zero values is below this.
+
+        Returns
+        -------
+        OmicsModality
+            *self*, for method chaining.
+        """
+        mask = np.ones(self.n_features, dtype=bool)
+
+        if min_variance > 0.0:
+            variances = self._data.var(axis=0, skipna=True)
+            mask &= variances.values >= min_variance
+
+        if min_nonzero_frac > 0.0:
+            nonzero_frac = (self._data != 0).mean(axis=0)
+            mask &= nonzero_frac.values >= min_nonzero_frac
+
+        n_before = self.n_features
+        self._data = self._data.loc[:, mask]
+        n_after = self.n_features
+        logger.info(
+            "%s: filtered features %d → %d (kept %.1f%%).",
+            self.modality_type,
+            n_before,
+            n_after,
+            100.0 * n_after / max(n_before, 1),
+        )
+        return self
+
+    def filter_samples(self, sample_ids: Sequence) -> "OmicsModality":
+        """Keep only the specified samples in-place and return *self*.
+
+        Parameters
+        ----------
+        sample_ids:
+            Iterable of sample IDs to retain.
+
+        Returns
+        -------
+        OmicsModality
+            *self*, for method chaining.
+
+        Raises
+        ------
+        ValueError
+            If none of the provided IDs are present in this modality.
+        """
+        requested = pd.Index(sample_ids)
+        common = self._data.index.intersection(requested)
+        if len(common) == 0:
+            raise ValueError(
+                f"None of the {len(requested)} requested sample IDs were found "
+                f"in {self.modality_type} modality."
+            )
+        n_before = self.n_samples
+        self._data = self._data.loc[common]
+        logger.info(
+            "%s: filtered samples %d → %d.",
+            self.modality_type,
+            n_before,
+            self.n_samples,
+        )
+        return self
+
+    def describe(self) -> Dict:
+        """Return a summary dictionary of this modality.
+
+        Returns
+        -------
+        dict
+            Keys: ``modality_type``, ``source``, ``n_samples``,
+            ``n_features``, ``value_min``, ``value_max``, ``value_mean``,
+            ``missing_frac``.
+        """
+        vals = self._data.values.ravel().astype(float)
+        finite = vals[np.isfinite(vals)]
+        return {
+            "modality_type": self.modality_type,
+            "source": self.source,
+            "n_samples": self.n_samples,
+            "n_features": self.n_features,
+            "value_min": float(finite.min()) if len(finite) else float("nan"),
+            "value_max": float(finite.max()) if len(finite) else float("nan"),
+            "value_mean": float(finite.mean()) if len(finite) else float("nan"),
+            "missing_frac": float(np.isnan(vals).mean()),
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}("
+            f"modality_type={self.modality_type!r}, "
+            f"shape=({self.n_samples}, {self.n_features}), "
+            f"source={self.source!r})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Modality-specific subclasses
+# ---------------------------------------------------------------------------
+
+
+class RNAModality(OmicsModality):
+    """Modality subclass for RNA expression data.
+
+    Validates that all values are non-negative.
+
+    Parameters
+    ----------
+    data:
+        DataFrame of RNA expression values (samples × genes).
+    source:
+        Data source identifier.
+    metadata:
+        Optional metadata dict.
+    """
+
+    def __init__(
+        self,
+        data: pd.DataFrame,
+        source: str = "unknown",
+        metadata: Optional[Dict] = None,
+    ) -> None:
+        super().__init__(data, modality_type="rna", source=source, metadata=metadata)
+        finite_vals = self._data.values[np.isfinite(self._data.values)]
+        if len(finite_vals) > 0 and finite_vals.min() < 0:
+            raise ValueError(
+                "RNAModality: data contains negative values. "
+                "RNA expression values must be non-negative (counts or TPM)."
+            )
+
+
+class MutationModality(OmicsModality):
+    """Modality subclass for somatic mutation data.
+
+    Parameters
+    ----------
+    data:
+        Binary or count-based mutation matrix (samples × genes).
+    source:
+        Data source identifier.
+    metadata:
+        Optional metadata dict.
+    """
+
+    def __init__(
+        self,
+        data: pd.DataFrame,
+        source: str = "unknown",
+        metadata: Optional[Dict] = None,
+    ) -> None:
+        super().__init__(
+            data, modality_type="mutations", source=source, metadata=metadata
+        )
+
+
+class MethylationModality(OmicsModality):
+    """Modality subclass for DNA methylation data.
+
+    Validates that beta values lie in [0, 1] if the data appears to be
+    beta values (i.e. all finite values are in [-6, 6] is permitted for
+    M-values, but pure beta must be in [0, 1]).
+
+    Parameters
+    ----------
+    data:
+        Methylation matrix (samples × CpG sites).
+    source:
+        Data source identifier.
+    metadata:
+        Optional metadata dict.
+    value_type:
+        ``"beta"`` (default) or ``"mvalue"``.  Beta values are validated
+        to lie in [0, 1]; M-values have no range constraint.
+    """
+
+    def __init__(
+        self,
+        data: pd.DataFrame,
+        source: str = "unknown",
+        metadata: Optional[Dict] = None,
+        value_type: str = "beta",
+    ) -> None:
+        if value_type not in ("beta", "mvalue"):
+            raise ValueError(
+                f"value_type must be 'beta' or 'mvalue', got {value_type!r}."
+            )
+        self.value_type = value_type
+        super().__init__(
+            data, modality_type="methylation", source=source, metadata=metadata
+        )
+        if value_type == "beta":
+            finite_vals = self._data.values[np.isfinite(self._data.values)]
+            if len(finite_vals) > 0:
+                if finite_vals.min() < -0.01 or finite_vals.max() > 1.01:
+                    raise ValueError(
+                        "MethylationModality (beta): values must be in [0, 1]. "
+                        f"Got min={finite_vals.min():.4f}, max={finite_vals.max():.4f}. "
+                        "If these are M-values, set value_type='mvalue'."
+                    )
+
+
+class CNVModality(OmicsModality):
+    """Modality subclass for copy-number variation data.
+
+    Parameters
+    ----------
+    data:
+        CNV matrix (samples × genes/segments).
+    source:
+        Data source identifier.
+    metadata:
+        Optional metadata dict.
+    """
+
+    def __init__(
+        self,
+        data: pd.DataFrame,
+        source: str = "unknown",
+        metadata: Optional[Dict] = None,
+    ) -> None:
+        super().__init__(data, modality_type="cnv", source=source, metadata=metadata)
+
+
+class ProteinModality(OmicsModality):
+    """Modality subclass for protein abundance data.
+
+    Parameters
+    ----------
+    data:
+        Protein abundance matrix (samples × proteins).
+    source:
+        Data source identifier.
+    metadata:
+        Optional metadata dict.
+    """
+
+    def __init__(
+        self,
+        data: pd.DataFrame,
+        source: str = "unknown",
+        metadata: Optional[Dict] = None,
+    ) -> None:
+        super().__init__(
+            data, modality_type="protein", source=source, metadata=metadata
+        )
+
+
+# Convenience mapping from modality_type string to subclass
+MODALITY_CLASSES: Dict[str, type] = {
+    "rna": RNAModality,
+    "mutations": MutationModality,
+    "methylation": MethylationModality,
+    "cnv": CNVModality,
+    "protein": ProteinModality,
+}
+
+
+def make_modality(
+    data: pd.DataFrame,
+    modality_type: str,
+    source: str = "unknown",
+    metadata: Optional[Dict] = None,
+    **kwargs,
+) -> OmicsModality:
+    """Instantiate the appropriate :class:`OmicsModality` subclass.
+
+    Parameters
+    ----------
+    data:
+        Feature matrix (samples × features).
+    modality_type:
+        One of the recognised modality types.
+    source:
+        Data source identifier.
+    metadata:
+        Optional metadata dict.
+    **kwargs:
+        Passed through to the subclass constructor.
+
+    Returns
+    -------
+    OmicsModality
+        The appropriate subclass instance.
+    """
+    validate_modality_type(modality_type)
+    cls = MODALITY_CLASSES[modality_type]
+    return cls(data, source=source, metadata=metadata, **kwargs)

omicsync/core/sample_index.py

@@ -0,0 +1,200 @@
+"""Sample ID harmonisation logic for multi-omics datasets."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Sequence, Union
+
+import numpy as np
+import pandas as pd
+
+from omicsync.utils.barcode import truncate_to_participant, truncate_to_sample
+from omicsync.utils.logging import get_logger
+
+logger = get_logger("core.sample_index")
+
+_LEVEL_FUNCS = {
+    "participant": truncate_to_participant,
+    "sample": truncate_to_sample,
+    "aliquot": lambda x: x,
+}
+
+
+class SampleIndex:
+    """Manages sample ID sets and harmonisation across modalities.
+
+    Parameters
+    ----------
+    sample_ids:
+        Initial set of sample identifiers (optional).
+    """
+
+    def __init__(self, sample_ids: Optional[Sequence] = None) -> None:
+        self._ids: pd.Index = (
+            pd.Index(sample_ids) if sample_ids is not None else pd.Index([])
+        )
+
+    @classmethod
+    def from_barcodes(
+        cls,
+        barcodes: Sequence[str],
+        level: str = "participant",
+    ) -> "SampleIndex":
+        """Create a :class:`SampleIndex` by truncating TCGA barcodes.
+
+        Parameters
+        ----------
+        barcodes:
+            Full TCGA aliquot barcodes.
+        level:
+            Truncation level: ``"participant"`` (default), ``"sample"``,
+            or ``"aliquot"`` (no truncation).
+
+        Returns
+        -------
+        SampleIndex
+
+        Raises
+        ------
+        ValueError
+            If *level* is not recognised.
+        """
+        if level not in _LEVEL_FUNCS:
+            raise ValueError(
+                f"Unknown barcode level {level!r}. "
+                f"Valid levels: {list(_LEVEL_FUNCS)}."
+            )
+        func = _LEVEL_FUNCS[level]
+        truncated = []
+        for bc in barcodes:
+            try:
+                truncated.append(func(bc))
+            except ValueError:
+                logger.warning("Could not parse barcode %r at level %r; keeping as-is.", bc, level)
+                truncated.append(bc)
+        idx = cls(truncated)
+        logger.info(
+            "SampleIndex: %d barcodes → %d unique IDs at level %r.",
+            len(barcodes),
+            len(set(truncated)),
+            level,
+        )
+        return idx
+
+    @staticmethod
+    def align(
+        list_of_sample_id_arrays: Sequence[Union[Sequence, pd.Index]],
+        strategy: str = "intersection",
+    ) -> pd.Index:
+        """Find common samples across multiple modalities.
+
+        Parameters
+        ----------
+        list_of_sample_id_arrays:
+            One array/index per modality.
+        strategy:
+            ``"intersection"`` (default) — samples present in every modality.
+            ``"union"`` — all samples seen across any modality.
+
+        Returns
+        -------
+        pandas.Index
+            Aligned sample IDs.
+
+        Raises
+        ------
+        ValueError
+            If *strategy* is unrecognised or the input list is empty.
+        """
+        if not list_of_sample_id_arrays:
+            raise ValueError("list_of_sample_id_arrays must not be empty.")
+        if strategy not in ("intersection", "union"):
+            raise ValueError(
+                f"Unknown strategy {strategy!r}. Valid: 'intersection', 'union'."
+            )
+
+        indices = [pd.Index(arr) for arr in list_of_sample_id_arrays]
+        if strategy == "intersection":
+            result = indices[0]
+            for idx in indices[1:]:
+                result = result.intersection(idx)
+        else:
+            result = indices[0]
+            for idx in indices[1:]:
+                result = result.union(idx)
+
+        logger.info(
+            "SampleIndex.align (%s): %d common samples from %d modalities.",
+            strategy,
+            len(result),
+            len(indices),
+        )
+        return result
+
+    @staticmethod
+    def match_fuzzy(
+        ids_a: Sequence[str],
+        ids_b: Sequence[str],
+    ) -> Dict[str, Optional[str]]:
+        """Match IDs across two sets, tolerating minor formatting differences.
+
+        Normalises by converting to uppercase and replacing dots with dashes
+        before matching.
+
+        Parameters
+        ----------
+        ids_a:
+            Reference ID set.
+        ids_b:
+            Query ID set.
+
+        Returns
+        -------
+        dict
+            Mapping from each ID in *ids_a* to the best matching ID in
+            *ids_b*, or ``None`` if no match found.
+        """
+
+        def _normalise(s: str) -> str:
+            return s.strip().upper().replace(".", "-")
+
+        norm_b: Dict[str, str] = {_normalise(b): b for b in ids_b}
+        result: Dict[str, Optional[str]] = {}
+        for a in ids_a:
+            key = _normalise(a)
+            result[a] = norm_b.get(key)
+        n_matched = sum(v is not None for v in result.values())
+        logger.info(
+            "Fuzzy match: %d/%d IDs matched.", n_matched, len(ids_a)
+        )
+        return result
+
+    def summarise(
+        self,
+        modality_sample_ids: Dict[str, Sequence],
+    ) -> pd.DataFrame:
+        """Report how many samples are present in each modality combination.
+
+        Parameters
+        ----------
+        modality_sample_ids:
+            Mapping from modality name to its sample IDs.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Rows are samples; columns are modality names; values are boolean
+            (``True`` = present).  An additional ``n_modalities`` column gives
+            the count of modalities present for each sample.
+        """
+        all_ids = set()
+        for ids in modality_sample_ids.values():
+            all_ids.update(ids)
+        df = pd.DataFrame(
+            {
+                name: pd.Index(all_ids).isin(ids)
+                for name, ids in modality_sample_ids.items()
+            },
+            index=pd.Index(sorted(all_ids), name="sample_id"),
+        )
+        df["n_modalities"] = df.sum(axis=1)
+        return df

omicsync/integration/__init__.py

@@ -0,0 +1,11 @@
+"""Integration methods for multi-omics data fusion."""
+
+from omicsync.integration.concat import simple_concat, weighted_concat, pca_concat
+from omicsync.integration.sklearn_compat import OmicsSyncTransformer
+
+__all__ = [
+    "simple_concat",
+    "weighted_concat",
+    "pca_concat",
+    "OmicsSyncTransformer",
+]