microarray 0.1.0__py3-none-any.whl

microarray/preprocessing/_rma.py

@@ -0,0 +1,243 @@
+"""RMA (Robust Multi-array Average) normalization pipeline."""
+
+import warnings
+
+import numpy as np
+from anndata import AnnData
+
+from microarray.preprocessing._background import rma_background_correct
+from microarray.preprocessing._log2 import _is_log_transformed, log2
+from microarray.preprocessing._normalize import normalize_quantile
+from microarray.preprocessing._summarize import summarize_probesets
+
+
+def rma(
+    adata: AnnData,
+    background_correct: bool = True,
+    normalize: bool = True,
+    log_transform: bool = True,
+    summarize: bool = True,
+    output_level: str = "gene",
+    copy: bool = True,
+) -> AnnData | None:
+    """Apply RMA (Robust Multi-array Average) normalization to microarray data.
+
+    RMA is a widely-used preprocessing method for Affymetrix microarrays that
+    combines background correction, quantile normalization, log transformation,
+    and robust summarization.
+
+    The standard RMA pipeline consists of:
+    1. Background correction using a convolution model
+    2. Quantile normalization across samples
+    3. Log2 transformation
+    4. Probeset summarization using median polish
+
+    Parameters
+    ----------
+    adata
+        AnnData object with shape (n_samples, n_probes).
+        Should contain raw intensity values from multiple CEL files.
+        Use `microarray.io.cel_batch_to_anndata()` to load data.
+    background_correct
+        If True, apply RMA background correction.
+    normalize
+        If True, apply quantile normalization across samples.
+        Requires n_samples > 1; skipped with warning for single sample.
+    log_transform
+        If True, apply log2 transformation to intensities.
+    summarize
+        If True, apply median polish summarization to probesets.
+        Requires 'gene_id' column in `.var`.
+    output_level
+        Output granularity when summarize=True:
+        - 'gene': Return gene-level data (n_samples, n_genes)
+        - 'probe': Keep probe-level data with effects in `.layers`
+        Ignored if summarize=False.
+    copy
+        If True, return a new AnnData object. If False, may modify in place
+        (except when output_level='gene', which always returns new object).
+
+    Returns:
+    -------
+    AnnData or None
+        Processed AnnData object if `copy=True`.
+        If `copy=False` and `output_level='probe'`, modifies in place and returns None.
+        Full RMA parameters and history are stored in `.uns['rma']`.
+
+    Raises:
+    ------
+    ValueError
+        If input validation fails (e.g., empty data, incompatible parameters).
+
+    Examples:
+    --------
+    >>> # Standard RMA with gene-level output
+    >>> import microarray as ma
+    >>> adata = ma.io.cel_batch_to_anndata(
+    ...     cel_paths=["sample1.CEL", "sample2.CEL"], cdf_path="chip.cdf", annotation_db_path="annotations.db"
+    ... )
+    >>> adata_rma = ma.pp.rma(adata)
+    >>> print(adata_rma.shape)  # (2, n_genes)
+
+    >>> # Partial RMA: only background correction and normalization
+    >>> adata_norm = ma.pp.rma(adata, background_correct=True, normalize=True, log_transform=True, summarize=False)
+    >>> print(adata_norm.shape)  # (2, n_probes) - still probe-level
+
+    >>> # RMA with probe-level output
+    >>> adata_probes = ma.pp.rma(adata, output_level="probe")
+
+    Notes:
+    -----
+    RMA was developed for Affymetrix oligonucleotide arrays and is one of
+    the most widely-used preprocessing methods due to its robustness and
+    performance in reducing technical variation.
+
+    The method assumes:
+    - Multiple samples are being processed together (for normalization)
+    - Data are from PM (perfect match) probes
+    - Probes are grouped into probesets representing genes/transcripts
+
+    References:
+    ----------
+    .. [1] Irizarry, R.A., Hobbs, B., Collin, F., et al. (2003).
+           Exploration, normalization, and summaries of high density
+           oligonucleotide array probe level data.
+           Biostatistics, 4(2), 249-264.
+
+    .. [2] Bolstad, B.M., Irizarry, R.A., Astrand, M., Speed, T.P. (2003).
+           A comparison of normalization methods for high density
+           oligonucleotide array data based on variance and bias.
+           Bioinformatics, 19(2), 185-193.
+    """
+    # Validate input
+    _validate_rma_input(adata, summarize)
+
+    # Check if already processed
+    if _is_likely_processed(adata):
+        warnings.warn(
+            "Input data appears to already be processed (values in log scale or "
+            "normalized). Applying RMA to already-processed data may give "
+            "incorrect results.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    # Initialize result
+    adata_result = adata.copy() if copy else adata
+
+    # Track which steps were applied
+    steps_applied = []
+
+    # Step 1: Background correction
+    if background_correct:
+        rma_background_correct(adata_result, copy=False)
+        steps_applied.append("background_correction")
+
+    # Step 2: Quantile normalization
+    if normalize:
+        if adata_result.n_obs == 1:
+            warnings.warn(
+                "Skipping quantile normalization: only 1 sample provided. Normalization requires multiple samples.",
+                UserWarning,
+                stacklevel=2,
+            )
+        else:
+            normalize_quantile(adata_result, copy=False)
+            steps_applied.append("quantile_normalization")
+
+    # Step 3: Log transformation
+    if log_transform:
+        # Check if already log-transformed
+        if not _is_log_transformed(adata_result):
+            log2(adata_result, copy=False)
+            steps_applied.append("log2_transform")
+        else:
+            warnings.warn(
+                "Data appears to already be log-transformed. Skipping log transformation.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+    # Step 4: Probeset summarization
+    if summarize:
+        if "gene_id" not in adata_result.var.columns:
+            warnings.warn(
+                "Cannot summarize probesets: 'gene_id' column missing from .var. "
+                "Load data with annotation_db_path to enable summarization. "
+                "Skipping summarization step.",
+                UserWarning,
+                stacklevel=2,
+            )
+        else:
+            # Note: summarize_probesets returns new AnnData for gene-level output
+            result_or_none = summarize_probesets(
+                adata_result,
+                method="medpolish",
+                output_level=output_level,
+                copy=False if output_level == "probe" else True,
+            )
+            # If gene-level, we get a new object; if probe-level with copy=False, we get None
+            if result_or_none is not None:
+                adata_result = result_or_none
+            steps_applied.append("median_polish_summarization")
+
+    # Store RMA parameters and history
+    adata_result.uns["rma"] = {
+        "background_correct": background_correct,
+        "normalize": normalize,
+        "log_transform": log_transform,
+        "summarize": summarize,
+        "output_level": output_level if summarize else "probe",
+        "steps_applied": steps_applied,
+        "n_samples": adata.n_obs,
+        "n_probes_input": adata.n_vars,
+        "n_features_output": adata_result.n_vars,
+    }
+
+    return adata_result if copy else None
+
+
+def _validate_rma_input(adata: AnnData, summarize: bool) -> None:
+    """Validate input AnnData for RMA processing."""
+    if adata is None:
+        raise ValueError("adata cannot be None")
+
+    if adata.X is None:
+        raise ValueError("AnnData.X must contain intensity values")
+
+    if adata.n_obs < 1:
+        raise ValueError("AnnData must contain at least one sample")
+
+    if adata.n_vars < 1:
+        raise ValueError("AnnData must contain at least one probe")
+
+    # Check for negative values (indicates already processed data)
+    if np.any(adata.X < 0):
+        warnings.warn(
+            "Input data contains negative values. RMA expects raw positive intensities.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    # Check for NaN or inf values
+    if np.any(~np.isfinite(adata.X)):
+        raise ValueError("Input data contains NaN or infinite values. RMA requires finite intensity values.")
+
+
+def _is_likely_processed(adata: AnnData) -> bool:
+    """Check if data appears to already be processed.
+
+    Checks for signs of normalization or log transformation.
+    """
+    # Check for log transformation
+    if _is_log_transformed(adata):
+        return True
+
+    # Check if normalization metadata exists
+    if "normalization" in adata.uns:
+        return True
+
+    if "rma" in adata.uns:
+        return True
+
+    return False

microarray/preprocessing/_robust.py

@@ -0,0 +1,170 @@
+"""Robust statistical methods for microarray preprocessing.
+
+This module provides robust statistical methods used in expression estimation,
+particularly in the MAS5 algorithm.
+"""
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def tukey_biweight(
+    x: NDArray[np.floating],
+    c: float = 5.0,
+    epsilon: float = 0.0001,
+    max_iter: int = 50,
+    tol: float = 1e-7,
+) -> float:
+    """Compute Tukey's biweight (bisquare) robust mean.
+
+    This function calculates a robust estimate of the mean using Tukey's biweight
+    algorithm. It downweights outliers based on their distance from the median,
+    providing more robust estimates than the arithmetic mean.
+
+    The algorithm computes weights based on standardized residuals:
+    - w_i = (1 - u_i^2)^2 for |u_i| <= 1
+    - w_i = 0 for |u_i| > 1
+
+    where u_i = (x_i - m) / (c * s + epsilon), m is the median, and s is the
+    median absolute deviation (MAD).
+
+    Parameters
+    ----------
+    x : NDArray[np.floating]
+        Input array of values, 1-dimensional.
+    c : float, default=5.0
+        Tuning constant that controls the downweighting of outliers.
+        Larger values assign more weight to outliers. Common values:
+        - c=5: standard for expression summarization (MAS5)
+        - c=6: more permissive
+        - c=4.685: asymptotically 95% efficiency for normal data
+    epsilon : float, default=0.0001
+        Small constant added to prevent division by zero when MAD is very small.
+    max_iter : int, default=50
+        Maximum number of iterations for refinement (currently single-pass).
+    tol : float, default=1e-7
+        Convergence tolerance (currently unused, reserved for iterative version).
+
+    Returns:
+    -------
+    float
+        The Tukey biweight estimate of the mean.
+
+    Notes:
+    -----
+    This implementation follows the Affymetrix MAS5 algorithm as implemented in
+    the affy R package (tukey.biweight.R). The single-pass version is used,
+    which computes weights based on deviations from the median.
+
+    For data with no variability (all values identical), the function returns
+    the common value.
+
+    References:
+    ----------
+    .. [1] Mosteller, F., and Tukey, J. W. (1977), Data Analysis and Regression:
+           A Second Course in Statistics. Addison-Wesley.
+    .. [2] Affymetrix (2002). Statistical Algorithms Description Document.
+
+    Examples:
+    --------
+    >>> import numpy as np
+    >>> from microarray.preprocessing import tukey_biweight
+    >>> x = np.array([1.0, 2.0, 3.0, 4.0, 5.0, 100.0])  # one outlier
+    >>> tukey_biweight(x)
+    2.9998...
+    >>> np.mean(x)  # regular mean is heavily influenced
+    19.166...
+    """
+    x = np.asarray(x, dtype=np.float64)
+
+    if x.ndim != 1:
+        raise ValueError(f"Input must be 1-dimensional, got shape {x.shape}")
+
+    if len(x) == 0:
+        raise ValueError("Input array is empty")
+
+    # Compute median and median absolute deviation
+    m = np.median(x)
+    s = np.median(np.abs(x - m))
+
+    # Handle case where all values are identical (s = 0)
+    if s < epsilon:
+        return float(m)
+
+    # Compute standardized residuals
+    u = (x - m) / (c * s + epsilon)
+
+    # Compute weights: w = (1 - u^2)^2 for |u| <= 1, else 0
+    w = np.zeros_like(u)
+    mask = np.abs(u) <= 1
+    w[mask] = (1 - u[mask] ** 2) ** 2
+
+    # Compute weighted mean
+    if np.sum(w) == 0:
+        # All points are outliers, fall back to median
+        return float(m)
+
+    t_bi = np.sum(w * x) / np.sum(w)
+    return float(t_bi)
+
+
+def tukey_biweight_summary(
+    x: NDArray[np.floating],
+    c: float = 5.0,
+    epsilon: float = 0.0001,
+) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+    """Apply Tukey biweight to summarize across probes for each sample.
+
+    This function is designed for probeset summarization, where each column
+    represents a sample and each row represents a probe. It applies the
+    Tukey biweight algorithm to each column independently.
+
+    Parameters
+    ----------
+    x : NDArray[np.floating]
+        Input array of shape (n_probes, n_samples).
+    c : float, default=5.0
+        Tuning constant for Tukey biweight.
+    epsilon : float, default=0.0001
+        Small constant to prevent division by zero.
+
+    Returns:
+    -------
+    exprs : NDArray[np.floating]
+        Array of shape (n_samples,) containing the biweight estimates.
+    se_exprs : NDArray[np.floating]
+        Array of shape (n_samples,) containing NaN values (standard errors
+        not computed in this implementation, following affy R package).
+
+    Notes:
+    -----
+    This function matches the behavior of tukeybiweight() in the affy R package,
+    which returns NA for standard errors.
+
+    Examples:
+    --------
+    >>> import numpy as np
+    >>> from microarray.preprocessing import tukey_biweight_summary
+    >>> # 5 probes, 3 samples
+    >>> x = np.array(
+    ...     [[1.0, 10.0, 100.0], [2.0, 11.0, 101.0], [3.0, 12.0, 102.0], [4.0, 13.0, 103.0], [5.0, 14.0, 104.0]]
+    ... )
+    >>> exprs, se = tukey_biweight_summary(x)
+    >>> exprs.shape
+    (3,)
+    """
+    x = np.asarray(x, dtype=np.float64)
+
+    if x.ndim != 2:
+        raise ValueError(f"Input must be 2-dimensional, got shape {x.shape}")
+
+    n_samples = x.shape[1]
+    exprs = np.empty(n_samples, dtype=np.float64)
+
+    for i in range(n_samples):
+        exprs[i] = tukey_biweight(x[:, i], c=c, epsilon=epsilon)
+
+    # Standard errors not computed (following affy R package behavior)
+    se_exprs = np.full(n_samples, np.nan, dtype=np.float64)
+
+    return exprs, se_exprs