microarray 0.1.0__py3-none-any.whl

microarray/preprocessing/_summarize.py

@@ -0,0 +1,318 @@
+"""Probeset summarization methods including median polish."""
+
+import warnings
+
+import numpy as np
+import pandas as pd
+from anndata import AnnData
+
+from ._robust import tukey_biweight_summary
+
+
+def median_polish(
+    X: np.ndarray,
+    eps: float = 0.01,
+    max_iter: int = 10,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, float, bool]:
+    """Apply Tukey's median polish algorithm to a matrix.
+
+    Median polish is a robust method for additive decomposition of a matrix:
+        X = global_effect + row_effects + col_effects + residuals
+
+    The algorithm iteratively:
+    1. Subtracts row medians from each row
+    2. Subtracts column medians from each column
+    3. Continues until convergence or max iterations
+
+    Parameters
+    ----------
+    X
+        Input matrix of shape (n_rows, n_cols) to decompose.
+    eps
+        Convergence threshold. Algorithm stops when relative change in
+        sum of absolute residuals is less than eps.
+    max_iter
+        Maximum number of iterations.
+
+    Returns:
+    -------
+    residuals
+        Residual matrix after removing effects, shape (n_rows, n_cols).
+    row_effects
+        Effect for each row, shape (n_rows,).
+    col_effects
+        Effect for each column, shape (n_cols,).
+    global_effect
+        Global effect (scalar).
+    converged
+        True if algorithm converged within max_iter iterations.
+
+    Examples:
+    --------
+    >>> X = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+    >>> res, row_eff, col_eff, global_eff, converged = median_polish(X)
+
+    Notes:
+    -----
+    For RMA summarization, the column effects + global effect represent
+    the expression value for each sample.
+
+    Reference:
+        Tukey, J.W. (1977). Exploratory Data Analysis. Addison-Wesley.
+    """
+    # Initialize
+    n_rows, n_cols = X.shape
+    residuals = X.copy().astype(float)
+    row_effects = np.zeros(n_rows)
+    col_effects = np.zeros(n_cols)
+    global_effect = 0.0
+
+    # Track convergence
+    prev_sar = np.sum(np.abs(residuals))
+    converged = False
+
+    for _iteration in range(max_iter):
+        # Row sweep: subtract row medians
+        row_medians = np.median(residuals, axis=1)
+        residuals -= row_medians[:, np.newaxis]
+        row_effects += row_medians
+
+        # Update column effects and global effect
+        col_median = np.median(col_effects)
+        col_effects -= col_median
+        global_effect += col_median
+
+        # Column sweep: subtract column medians
+        col_medians = np.median(residuals, axis=0)
+        residuals -= col_medians
+        col_effects += col_medians
+
+        # Update row effects and global effect
+        row_median = np.median(row_effects)
+        row_effects -= row_median
+        global_effect += row_median
+
+        # Check convergence
+        current_sar = np.sum(np.abs(residuals))
+
+        if current_sar == 0:
+            converged = True
+            break
+
+        relative_change = abs(current_sar - prev_sar) / current_sar
+
+        if relative_change < eps:
+            converged = True
+            break
+
+        prev_sar = current_sar
+
+    return residuals, row_effects, col_effects, global_effect, converged
+
+
+def summarize_probesets(
+    adata: AnnData,
+    method: str = "medpolish",
+    output_level: str = "gene",
+    copy: bool = True,
+) -> AnnData | None:
+    """Summarize probe-level data to gene-level using median polish or simple median.
+
+    Groups probes by gene (using `.var['gene_id']`) and applies summarization
+    to reduce multiple probes per gene to a single expression value per gene.
+
+    Parameters
+    ----------
+    adata
+        AnnData object with shape (n_samples, n_probes).
+        Must contain 'gene_id' column in `.var`.
+    method
+        Summarization method:
+        - 'medpolish': Tukey's median polish (default, used in RMA)
+        - 'median': Simple median across probes
+        - 'mas': Tukey biweight (used in MAS5)
+    output_level
+        Output granularity:
+        - 'gene': Return gene-level AnnData (n_samples, n_genes)
+        - 'probe': Keep probe-level, store effects in `.layers`
+    copy
+        If True, return a new AnnData object. If False and output_level='gene',
+        must return new object (raises ValueError).
+
+    Returns:
+    -------
+    AnnData or None
+        If `output_level='gene'`, returns gene-level AnnData object.
+        If `output_level='probe'` and `copy=True`, returns probe-level AnnData
+        with summarization stored in `.layers['medpolish_effects']`.
+        If `output_level='probe'` and `copy=False`, modifies in place and returns None.
+        Summarization metadata is stored in `.uns['summarization']`.
+
+    Raises:
+    ------
+    ValueError
+        If 'gene_id' column is missing from `.var`.
+        If `output_level='gene'` and `copy=False` (cannot modify shape in place).
+
+    Examples:
+    --------
+    >>> # Summarize to gene level
+    >>> adata_genes = ma.pp.summarize_probesets(adata, output_level="gene")
+    >>> print(adata_genes.shape)  # (n_samples, n_genes)
+
+    >>> # Keep probe level but store median polish effects
+    >>> adata_probes = ma.pp.summarize_probesets(adata, output_level="probe")
+
+    Notes:
+    -----
+    For median polish:
+    - Each probeset forms a (n_probes_in_set, n_samples) matrix
+    - Median polish decomposes: X = global + row_eff + col_eff + residuals
+    - Gene expression = col_eff + global (one value per sample)
+
+    Probes without gene annotation (gene_id is None or empty) are excluded
+    from gene-level output but retained in probe-level output.
+    """
+    if "gene_id" not in adata.var.columns:
+        raise ValueError(
+            "AnnData.var must contain 'gene_id' column for probeset summarization. "
+            "Load data with annotation_db_path to get gene annotations."
+        )
+
+    if output_level not in ["gene", "probe"]:
+        raise ValueError(f"output_level must be 'gene' or 'probe', got '{output_level}'")
+
+    if output_level == "gene" and not copy:
+        raise ValueError(
+            "Cannot modify AnnData in place when changing from probe to gene level. "
+            "Set copy=True for gene-level output."
+        )
+
+    if method not in ["medpolish", "median", "mas"]:
+        raise ValueError(f"method must be 'medpolish', 'median', or 'mas', got '{method}'")
+
+    adata_work = adata.copy() if copy else adata
+
+    # Get probe-to-gene mapping
+    gene_ids = adata_work.var["gene_id"].values
+    unique_genes = pd.Series(gene_ids).dropna().unique()
+
+    n_samples = adata_work.n_obs
+    n_genes = len(unique_genes)
+
+    if n_genes == 0:
+        raise ValueError("No valid gene IDs found in .var['gene_id']")
+
+    # Store summarization metadata
+    convergence_info = []
+
+    if output_level == "gene":
+        # Create gene-level expression matrix
+        X_genes = np.zeros((n_samples, n_genes))
+        var_data = {
+            "gene_id": [],
+            "n_probes": [],
+            "converged": [] if method == "medpolish" else None,
+        }
+
+        for i, gene_id in enumerate(unique_genes):
+            # Get probes for this gene
+            probe_mask = gene_ids == gene_id
+            probe_indices = np.where(probe_mask)[0]
+            n_probes_in_set = len(probe_indices)
+
+            # Extract probeset intensities: (n_probes, n_samples)
+            probeset_data = adata_work.X[:, probe_indices].T
+
+            if method == "medpolish":
+                if n_probes_in_set == 1:
+                    # Single probe: no summarization needed
+                    gene_expr = probeset_data[0, :]
+                    converged = True
+                else:
+                    # Apply median polish
+                    residuals, row_eff, col_eff, global_eff, converged = median_polish(
+                        probeset_data, eps=0.01, max_iter=10
+                    )
+                    # Gene expression = column effects + global effect
+                    gene_expr = col_eff + global_eff
+
+                var_data["converged"].append(converged)
+                if not converged:
+                    warnings.warn(
+                        f"Median polish did not converge for gene '{gene_id}' ({n_probes_in_set} probes)",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+
+            elif method == "median":
+                # Simple median across probes
+                gene_expr = np.median(probeset_data, axis=0)
+                converged = True
+
+            elif method == "mas":
+                # Tukey biweight summarization
+                gene_expr, _ = tukey_biweight_summary(probeset_data)
+                converged = True
+
+            X_genes[:, i] = gene_expr
+            var_data["gene_id"].append(gene_id)
+            var_data["n_probes"].append(n_probes_in_set)
+            convergence_info.append(converged)
+
+        # Create new gene-level AnnData
+        var_df = pd.DataFrame(var_data)
+        if method != "medpolish":
+            var_df = var_df.drop(columns=["converged"])
+
+        adata_out = AnnData(
+            X=X_genes,
+            obs=adata_work.obs.copy(),
+            var=var_df,
+            uns=adata_work.uns.copy(),
+        )
+
+        # Store summarization info
+        adata_out.uns["summarization"] = {
+            "method": method,
+            "output_level": output_level,
+            "n_genes": n_genes,
+            "n_probes_original": adata_work.n_vars,
+            "convergence_rate": sum(convergence_info) / len(convergence_info) if convergence_info else 1.0,
+        }
+
+        return adata_out
+
+    else:  # output_level == 'probe'
+        # Keep probe level, optionally store effects in layers
+        if method == "medpolish":
+            # Store median polish effects for each probe
+            effects = np.zeros_like(adata_work.X)
+
+            for gene_id in unique_genes:
+                probe_mask = gene_ids == gene_id
+                probe_indices = np.where(probe_mask)[0]
+                n_probes_in_set = len(probe_indices)
+
+                probeset_data = adata_work.X[:, probe_indices].T
+
+                if n_probes_in_set == 1:
+                    # Single probe: effect = original value
+                    effects[:, probe_indices[0]] = probeset_data[0, :]
+                else:
+                    residuals, row_eff, col_eff, global_eff, converged = median_polish(
+                        probeset_data, eps=0.01, max_iter=10
+                    )
+                    # Store column effects + global for each probe
+                    for _j, probe_idx in enumerate(probe_indices):
+                        effects[:, probe_idx] = col_eff + global_eff
+
+            adata_work.layers["medpolish_effects"] = effects
+
+        adata_work.uns["summarization"] = {
+            "method": method,
+            "output_level": output_level,
+            "n_genes": n_genes,
+        }
+
+        return adata_work if copy else None

microarray/tools/__init__.py

@@ -0,0 +1,26 @@
+"""Tools for microarray data analysis.
+
+This module provides analytical tools for microarray data, including:
+- Dimension reduction (MDS)
+- Biomart-based feature annotation
+"""
+
+from microarray.tools._biomart import BiomartDataset, annotate
+from microarray.tools._empirical_bayes import ebayes, squeeze_var
+from microarray.tools._linear_models import lm_fit
+from microarray.tools._mds import mds
+from microarray.tools._pca import pca
+from microarray.tools._score import score
+from microarray.tools._toptable import top_table
+
+__all__ = [
+    "mds",
+    "pca",
+    "BiomartDataset",
+    "annotate",
+    "ebayes",
+    "squeeze_var",
+    "lm_fit",
+    "score",
+    "top_table",
+]