microarray 0.1.0__py3-none-any.whl

microarray/preprocessing/_normalize.py

@@ -0,0 +1,1292 @@
+"""Normalization methods for microarray data."""
+
+import warnings
+
+import numpy as np
+from anndata import AnnData
+
+
+def normalize_quantile(
+    adata: AnnData,
+    copy: bool = False,
+) -> AnnData | None:
+    """Apply quantile normalization to microarray intensity data.
+
+    Quantile normalization makes the distribution of intensities identical
+    across all samples by:
+    1. Sorting intensity values for each sample
+    2. Replacing sorted values with the mean across samples at each rank
+    3. Restoring the original order within each sample
+
+    This ensures all samples have the same empirical distribution, removing
+    systematic technical variation while preserving biological differences.
+
+    Parameters
+    ----------
+    adata
+        AnnData object with shape (n_samples, n_probes).
+        Must contain intensity values in `.X`.
+    copy
+        If True, return a copy of the AnnData object. If False, modify in place.
+
+    Returns:
+    -------
+    AnnData or None
+        If `copy=True`, returns normalized AnnData object.
+        If `copy=False`, modifies `adata` in place and returns None.
+        The normalized intensities are stored in `.X`.
+        Normalization metadata is stored in `.uns['normalization']`.
+
+    Examples:
+    --------
+    >>> import microarray as ma
+    >>> adata = ma.io.cel_batch_to_anndata(cel_files, cdf_path, annotation_db)
+    >>> adata_norm = ma.pp.normalize_quantile(adata, copy=True)
+
+    Notes:
+    -----
+    Quantile normalization requires multiple samples. For a single sample,
+    a warning is issued and the data is returned unchanged.
+
+    The algorithm preserves the rank order of probes within each sample
+    while making the marginal distributions identical across samples.
+
+    Reference:
+        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.
+    """
+    adata = adata.copy() if copy else adata
+
+    # Validate input
+    if adata.X is None:
+        raise ValueError("AnnData object must have .X attribute with intensity values")
+
+    n_samples, n_probes = adata.shape
+
+    # Check for single sample case
+    if n_samples == 1:
+        warnings.warn(
+            "Quantile normalization requires multiple samples for proper normalization. "
+            "With only 1 sample, data is returned unchanged.",
+            UserWarning,
+            stacklevel=2,
+        )
+        adata.uns["normalization"] = {
+            "method": "quantile",
+            "n_samples": n_samples,
+            "applied": False,
+            "reason": "single_sample",
+        }
+        return adata if copy else None
+
+    # Get intensity matrix (samples × probes)
+    X = adata.X.copy()
+
+    # Step 1: Sort each sample (column)
+    X_sorted = np.sort(X, axis=1)
+
+    # Step 2: Compute mean across samples at each rank
+    rank_means = np.mean(X_sorted, axis=0)
+
+    # Step 3: Get ranks for each sample to restore original order
+    # argsort gives indices that would sort the array
+    # argsort(argsort) gives the rank of each element
+    ranks = np.argsort(np.argsort(X, axis=1), axis=1)
+
+    # Step 4: Replace with rank means
+    X_normalized = rank_means[ranks]
+
+    # Update AnnData
+    adata.X = X_normalized
+    adata.uns["normalization"] = {
+        "method": "quantile",
+        "n_samples": n_samples,
+        "n_probes": n_probes,
+        "applied": True,
+    }
+
+    return adata if copy else None
+
+
+def normalize_constant(
+    adata: AnnData,
+    refindex: int = 0,
+    method: str = "mean",
+    target_value: float | None = None,
+    copy: bool = False,
+) -> AnnData | None:
+    """Apply constant (scale) normalization to microarray intensity data.
+
+    Constant normalization is a simple scaling method that multiplies each array
+    by a constant to make a summary statistic (mean or median) equal across arrays
+    or to a specific target value.
+
+    Parameters
+    ----------
+    adata
+        AnnData object with shape (n_samples, n_probes).
+        Must contain intensity values in `.X`.
+    refindex
+        Index of the reference sample (0-based). Default is 0 (first sample).
+        Only used when target_value is None.
+    method
+        Function to compute the scaling constant: "mean" or "median".
+        Default is "mean".
+    target_value
+        If specified, scale all samples to this target value instead of scaling
+        to a reference sample. Commonly used in MAS5 (target=500).
+    copy
+        If True, return a copy of the AnnData object. If False, modify in place.
+
+    Returns:
+    -------
+    AnnData or None
+        If `copy=True`, returns normalized AnnData object.
+        If `copy=False`, modifies `adata` in place and returns None.
+        The normalized intensities are stored in `.X`.
+        Normalization metadata is stored in `.uns['normalize_constant']`.
+
+    Examples:
+    --------
+    >>> import microarray as ma
+    >>> adata = ma.io.cel_batch_to_anndata(cel_files, cdf_path, annotation_db)
+    >>> adata_norm = ma.pp.normalize_constant(adata, method="median", copy=True)
+
+    Notes:
+    -----
+    This is the simplest normalization method and assumes that most genes are
+    not differentially expressed and that technical variation affects all probes
+    uniformly. It may not be appropriate when there are global shifts in
+    expression levels between samples.
+
+    The normalization formula for each sample i is:
+        X_norm[i] = X[i] * (ref_constant / sample_constant[i])
+
+    Reference
+    -------
+    See normalize.constant in the affy Bioconductor package documentation.
+    """
+    adata = adata.copy() if copy else adata
+
+    # Validate input
+    if adata.X is None:
+        raise ValueError("AnnData object must have .X attribute with intensity values")
+
+    if method not in ["mean", "median"]:
+        raise ValueError(f"method must be 'mean' or 'median', got '{method}'")
+
+    n_samples, n_probes = adata.shape
+
+    if refindex < 0 or refindex >= n_samples:
+        raise ValueError(f"refindex must be between 0 and {n_samples - 1}, got {refindex}")
+
+    # Get intensity matrix (samples × probes)
+    X = adata.X.copy()
+
+    # Compute constants for each sample
+    if method == "mean":
+        constants = np.mean(X, axis=1)
+    else:  # median
+        constants = np.median(X, axis=1)
+
+    # Determine reference constant
+    if target_value is not None:
+        ref_constant = target_value
+    else:
+        # Get reference constant from specified sample
+        ref_constant = constants[refindex]
+
+    # Avoid division by zero
+    if np.any(constants == 0):
+        warnings.warn(
+            "Some samples have zero constant value. These samples will not be normalized.",
+            UserWarning,
+            stacklevel=2,
+        )
+        constants = np.where(constants == 0, 1.0, constants)
+
+    # Compute scaling factors
+    scale_factors = ref_constant / constants
+
+    # Apply scaling to each sample
+    X_normalized = X * scale_factors[:, np.newaxis]
+
+    # Update AnnData
+    adata.X = X_normalized
+    adata.uns["normalize_constant"] = {
+        "method": method,
+        "refindex": refindex if target_value is None else None,
+        "target_value": float(target_value) if target_value is not None else None,
+        "ref_constant": float(ref_constant),
+        "scale_factors": scale_factors.tolist(),
+        "n_samples": n_samples,
+        "n_probes": n_probes,
+        "applied": True,
+    }
+
+    return adata if copy else None
+
+
+def normalize_quantile_robust(
+    adata: AnnData,
+    weights: np.ndarray | None = None,
+    remove_extreme: str = "none",
+    n_remove: int = 0,
+    use_median: bool = False,
+    use_log2: bool = False,
+    copy: bool = False,
+) -> AnnData | None:
+    """Apply robust quantile normalization with optional weighting and outlier removal.
+
+    This is an enhanced version of quantile normalization that supports chip weighting
+    and outlier removal options. It can be useful when some arrays are of lower quality
+    or when extreme outliers should be excluded from the normalization process.
+
+    Parameters
+    ----------
+    adata
+        AnnData object with shape (n_samples, n_probes).
+        Must contain intensity values in `.X`.
+    weights
+        Optional array of weights for each sample (length n_samples).
+        Larger weights give more influence in computing the target distribution.
+        If None, all samples are weighted equally.
+    remove_extreme
+        Method for identifying extreme samples to remove:
+        - "none": no removal (default)
+        - "variance": remove samples with highest variance
+        - "mean": remove samples with extreme mean values
+        - "both": remove samples with extreme variance or mean
+    n_remove
+        Number of extreme samples to remove (default 0).
+        Only used if remove_extreme is not "none".
+    use_median
+        If True, use weighted median for target distribution.
+        If False, use weighted mean (default).
+    use_log2
+        If True, work on log2 scale and compute geometric mean.
+        If False, work on original scale (default).
+    copy
+        If True, return a copy of the AnnData object. If False, modify in place.
+
+    Returns:
+    -------
+    AnnData or None
+        If `copy=True`, returns normalized AnnData object.
+        If `copy=False`, modifies `adata` in place and returns None.
+        The normalized intensities are stored in `.X`.
+        Normalization metadata is stored in `.uns['normalize_quantile_robust']`.
+
+    Examples:
+    --------
+    >>> import microarray as ma
+    >>> import numpy as np
+    >>> adata = ma.io.cel_batch_to_anndata(cel_files, cdf_path, annotation_db)
+    >>> # Remove 2 samples with highest variance
+    >>> adata_norm = ma.pp.normalize_quantile_robust(adata, remove_extreme="variance", n_remove=2, copy=True)
+    >>> # Use weighted normalization
+    >>> weights = np.array([1.0, 0.8, 1.0, 0.9, 1.0])  # lower weight for quality issues
+    >>> adata_norm = ma.pp.normalize_quantile_robust(adata, weights=weights, copy=True)
+
+    Notes:
+    -----
+    This method is marked as experimental in the affy R package. Use with caution.
+
+    When remove_extreme is used, the extreme samples are identified but still
+    normalized. They are simply excluded from computing the target distribution.
+
+    Reference
+    -------
+    See normalize.quantiles.robust in the affy Bioconductor package documentation.
+    """
+    adata = adata.copy() if copy else adata
+
+    # Validate input
+    if adata.X is None:
+        raise ValueError("AnnData object must have .X attribute with intensity values")
+
+    if remove_extreme not in ["none", "variance", "mean", "both"]:
+        raise ValueError(f"remove_extreme must be one of 'none', 'variance', 'mean', 'both', got '{remove_extreme}'")
+
+    n_samples, n_probes = adata.shape
+
+    # Warn about experimental status
+    warnings.warn(
+        "Robust quantile normalization is marked as experimental. Use with caution and validate results.",
+        UserWarning,
+        stacklevel=2,
+    )
+
+    # Check for single sample case
+    if n_samples == 1:
+        warnings.warn(
+            "Quantile normalization requires multiple samples. With only 1 sample, data is returned unchanged.",
+            UserWarning,
+            stacklevel=2,
+        )
+        adata.uns["normalize_quantile_robust"] = {
+            "method": "quantile_robust",
+            "n_samples": n_samples,
+            "applied": False,
+            "reason": "single_sample",
+        }
+        return adata if copy else None
+
+    # Get intensity matrix (samples × probes)
+    X = adata.X.copy()
+
+    # Apply log2 transformation if requested
+    if use_log2:
+        X = np.log2(X + 1)  # Add 1 to avoid log(0)
+
+    # Initialize weights if not provided
+    if weights is None:
+        weights = np.ones(n_samples)
+    else:
+        weights = np.array(weights)
+        if len(weights) != n_samples:
+            raise ValueError(f"weights must have length {n_samples}, got {len(weights)}")
+
+    # Identify samples to exclude from target distribution
+    exclude_mask = np.zeros(n_samples, dtype=bool)
+
+    if remove_extreme != "none" and n_remove > 0:
+        if n_remove >= n_samples:
+            raise ValueError(f"n_remove ({n_remove}) must be less than n_samples ({n_samples})")
+
+        if remove_extreme in ["variance", "both"]:
+            variances = np.var(X, axis=1)
+            variance_ranks = np.argsort(variances)[::-1]  # highest first
+            exclude_mask[variance_ranks[:n_remove]] = True
+
+        if remove_extreme in ["mean", "both"]:
+            means = np.mean(X, axis=1)
+            # Remove most extreme (furthest from overall median)
+            median_mean = np.median(means)
+            mean_distances = np.abs(means - median_mean)
+            mean_ranks = np.argsort(mean_distances)[::-1]  # highest first
+            exclude_mask[mean_ranks[:n_remove]] = True
+
+    # Get samples to include in target distribution
+    include_mask = ~exclude_mask
+    n_included = np.sum(include_mask)
+
+    if n_included == 0:
+        raise ValueError("All samples would be excluded. Reduce n_remove.")
+
+    # Sort each sample
+    X_sorted = np.sort(X, axis=1)
+
+    # Compute weighted target distribution
+    if use_median:
+        # Weighted median is more complex; use simple median for now
+        rank_targets = np.median(X_sorted[include_mask], axis=0)
+    else:
+        # Weighted mean
+        included_weights = weights[include_mask]
+        included_sorted = X_sorted[include_mask]
+        weight_sum = np.sum(included_weights)
+        rank_targets = np.sum(included_sorted * included_weights[:, np.newaxis], axis=0) / weight_sum
+
+    # Get ranks for each sample to restore original order
+    ranks = np.argsort(np.argsort(X, axis=1), axis=1)
+
+    # Replace with rank targets
+    X_normalized = rank_targets[ranks]
+
+    # Reverse log2 transformation if applied
+    if use_log2:
+        X_normalized = np.power(2, X_normalized) - 1
+        X_normalized = np.maximum(X_normalized, 0)  # Ensure non-negative
+
+    # Update AnnData
+    adata.X = X_normalized
+    adata.uns["normalize_quantile_robust"] = {
+        "method": "quantile_robust",
+        "n_samples": n_samples,
+        "n_probes": n_probes,
+        "n_included": int(n_included),
+        "n_excluded": int(np.sum(exclude_mask)),
+        "remove_extreme": remove_extreme,
+        "n_remove": n_remove,
+        "use_median": use_median,
+        "use_log2": use_log2,
+        "excluded_indices": np.where(exclude_mask)[0].tolist(),
+        "applied": True,
+    }
+
+    return adata if copy else None
+
+
+def _lowess_fit(x: np.ndarray, y: np.ndarray, span: float = 2 / 3) -> np.ndarray:
+    """Simple LOWESS (Locally Weighted Scatterplot Smoothing) implementation.
+
+    Parameters
+    ----------
+    x
+        Independent variable values (sorted).
+    y
+        Dependent variable values.
+    span
+        Fraction of data to use for local regression (0 < span <= 1).
+
+    Returns:
+    -------
+    np.ndarray
+        Smoothed y values.
+    """
+    n = len(x)
+    y_smooth = np.zeros(n)
+    k = int(np.ceil(span * n))
+
+    for i in range(n):
+        # Get local neighborhood
+        distances = np.abs(x - x[i])
+        nearest = np.argsort(distances)[:k]
+
+        # Compute weights using tricube kernel
+        max_dist = distances[nearest[-1]]
+        if max_dist > 0:
+            weights = (1 - (distances[nearest] / max_dist) ** 3) ** 3
+        else:
+            weights = np.ones(k)
+
+        # Weighted linear regression
+        X_local = np.column_stack([np.ones(k), x[nearest]])
+        W = np.diag(weights)
+        try:
+            beta = np.linalg.lstsq(X_local.T @ W @ X_local, X_local.T @ W @ y[nearest], rcond=None)[0]
+            y_smooth[i] = beta[0] + beta[1] * x[i]
+        except np.linalg.LinAlgError:
+            # Fallback to weighted mean if regression fails
+            y_smooth[i] = np.average(y[nearest], weights=weights)
+
+    return y_smooth
+
+
+def normalize_loess(
+    adata: AnnData,
+    subset: int = 5000,
+    span: float = 2 / 3,
+    iterations: int = 1,
+    epsilon: float = 0.01,
+    copy: bool = False,
+) -> AnnData | None:
+    """Apply loess (locally weighted scatterplot smoothing) normalization.
+
+    Loess normalization uses MA plots (M vs A, where M = log-intensity difference
+    and A = average log-intensity) to normalize arrays against a reference. It
+    fits a smooth curve to correct for intensity-dependent biases.
+
+    Parameters
+    ----------
+    adata
+        AnnData object with shape (n_samples, n_probes).
+        Must contain intensity values in `.X`.
+    subset
+        Number of probes to use for fitting the loess curve.
+        Using a subset improves computational efficiency.
+        If subset >= n_probes, all probes are used.
+        Default is 5000.
+    span
+        Fraction of data points to use for local regression (0 < span <= 1).
+        Larger values produce smoother curves. Default is 2/3.
+    iterations
+        Number of normalization iterations. Default is 1.
+        More iterations can improve convergence but increase computation time.
+    epsilon
+        Convergence threshold. If maximum change between iterations
+        is less than epsilon, stop early. Default is 0.01.
+    copy
+        If True, return a copy of the AnnData object. If False, modify in place.
+
+    Returns:
+    -------
+    AnnData or None
+        If `copy=True`, returns normalized AnnData object.
+        If `copy=False`, modifies `adata` in place and returns None.
+        The normalized intensities are stored in `.X`.
+        Normalization metadata is stored in `.uns['normalize_loess']`.
+
+    Examples:
+    --------
+    >>> import microarray as ma
+    >>> adata = ma.io.cel_batch_to_anndata(cel_files, cdf_path, annotation_db)
+    >>> adata_norm = ma.pp.normalize_loess(adata, subset=3000, iterations=2, copy=True)
+
+    Notes:
+    -----
+    This method normalizes all arrays to have the same relationship between
+    intensity and average intensity, removing intensity-dependent bias.
+
+    The algorithm:
+    1. Compute reference as median array
+    2. For each array, compute M = log(array) - log(reference)
+       and A = (log(array) + log(reference)) / 2
+    3. Fit loess curve M ~ A on subset of probes
+    4. Apply correction to all probes via interpolation
+    5. Repeat until convergence or max iterations reached
+
+    For large datasets, using a subset of probes significantly improves speed
+    while maintaining normalization quality.
+
+    Reference
+    -------
+    Yang, Y.H., et al. (2002). Normalization for cDNA microarray data:
+    a robust composite method addressing single and multiple slide systematic
+    variation. Nucleic Acids Research, 30(4), e15.
+    """
+    adata = adata.copy() if copy else adata
+
+    # Validate input
+    if adata.X is None:
+        raise ValueError("AnnData object must have .X attribute with intensity values")
+
+    if span <= 0 or span > 1:
+        raise ValueError(f"span must be between 0 and 1, got {span}")
+
+    if iterations < 1:
+        raise ValueError(f"iterations must be at least 1, got {iterations}")
+
+    n_samples, n_probes = adata.shape
+
+    if n_samples == 1:
+        warnings.warn(
+            "Loess normalization requires multiple samples. With only 1 sample, data is returned unchanged.",
+            UserWarning,
+            stacklevel=2,
+        )
+        adata.uns["normalize_loess"] = {
+            "method": "loess",
+            "n_samples": n_samples,
+            "applied": False,
+            "reason": "single_sample",
+        }
+        return adata if copy else None
+
+    # Work on log scale (add small constant to avoid log(0))
+    X_log = np.log2(adata.X + 1)
+    X_normalized = X_log.copy()
+
+    # Determine subset for fitting
+    n_subset = min(subset, n_probes)
+    if n_subset < n_probes:
+        # Randomly select subset
+        np.random.seed(42)
+        subset_indices = np.random.choice(n_probes, n_subset, replace=False)
+        subset_indices = np.sort(subset_indices)
+    else:
+        subset_indices = np.arange(n_probes)
+
+    # Iterative normalization
+    for _ in range(iterations):
+        X_prev = X_normalized.copy()
+
+        # Compute reference (median across samples)
+        reference = np.median(X_normalized, axis=0)
+
+        # Normalize each sample against reference
+        for i in range(n_samples):
+            # Compute M and A for subset
+            M_subset = X_normalized[i, subset_indices] - reference[subset_indices]
+            A_subset = (X_normalized[i, subset_indices] + reference[subset_indices]) / 2
+
+            # Sort by A for loess fitting
+            sort_idx = np.argsort(A_subset)
+            A_sorted = A_subset[sort_idx]
+            M_sorted = M_subset[sort_idx]
+
+            # Fit loess curve
+            M_smooth = _lowess_fit(A_sorted, M_sorted, span=span)
+
+            # Interpolate to all probes
+            A_all = (X_normalized[i, :] + reference) / 2
+            M_correction = np.interp(A_all, A_sorted, M_smooth)
+
+            # Apply correction
+            X_normalized[i, :] = X_normalized[i, :] - M_correction
+
+        # Check convergence
+        max_change = np.max(np.abs(X_normalized - X_prev))
+        if max_change < epsilon:
+            break
+
+    # Convert back to original scale
+    X_normalized = np.power(2, X_normalized) - 1
+    X_normalized = np.maximum(X_normalized, 0)  # Ensure non-negative
+
+    # Update AnnData
+    adata.X = X_normalized
+    adata.uns["normalize_loess"] = {
+        "method": "loess",
+        "n_samples": n_samples,
+        "n_probes": n_probes,
+        "subset": n_subset,
+        "span": span,
+        "iterations": iterations,
+        "iterations_performed": iterations,
+        "epsilon": epsilon,
+        "converged": max_change < epsilon if iterations > 1 else None,
+        "applied": True,
+    }
+
+    return adata if copy else None
+
+
+def normalize_invariantset(
+    adata: AnnData,
+    baseline_type: str = "mean",
+    baseline_index: int | None = None,
+    prd_td: tuple[float, float] = (0.003, 0.007),
+    max_iterations: int = 10,
+    copy: bool = False,
+) -> AnnData | None:
+    """Apply invariant set normalization.
+
+    This method identifies a set of invariant probes (probes that show consistent
+    expression across samples) and uses them to fit a normalization curve via
+    smoothing splines. The curve is then applied to all probes.
+
+    Parameters
+    ----------
+    adata
+        AnnData object with shape (n_samples, n_probes).
+        Must contain intensity values in `.X`.
+    baseline_type
+        Method for creating baseline array:
+        - "mean": arithmetic mean across samples
+        - "median": median across samples
+        - "pseudo-mean": trimmed mean (10% trim)
+        - "pseudo-median": weighted median
+        - None: use array at baseline_index
+        Default is "mean".
+    baseline_index
+        Index of sample to use as baseline (0-based).
+        Only used if baseline_type is None.
+    prd_td
+        Tuple of (lower, upper) thresholds for identifying invariant probes
+        based on rank consistency. Default is (0.003, 0.007).
+    max_iterations
+        Maximum iterations for identifying invariant set. Default is 10.
+    copy
+        If True, return a copy of the AnnData object. If False, modify in place.
+
+    Returns:
+    -------
+    AnnData or None
+        If `copy=True`, returns normalized AnnData object.
+        If `copy=False`, modifies `adata` in place and returns None.
+        The normalized intensities are stored in `.X`.
+        Normalization metadata is stored in `.uns['normalize_invariantset']`.
+
+    Examples:
+    --------
+    >>> import microarray as ma
+    >>> adata = ma.io.cel_batch_to_anndata(cel_files, cdf_path, annotation_db)
+    >>> adata_norm = ma.pp.normalize_invariantset(adata, baseline_type="median", copy=True)
+
+    Notes:
+    -----
+    The algorithm iteratively identifies probes that have consistent ranks
+    across arrays. These invariant probes are assumed to not be differentially
+    expressed and are used to learn the normalization transformation.
+
+    A smoothing spline is fit to the invariant probes' intensities in the
+    (baseline, sample) space, and this curve is used to normalize all probes.
+
+    Reference
+    -------
+    Li, C. and Wong, W.H. (2001). Model-based analysis of oligonucleotide
+    arrays: expression index computation and outlier detection.
+    Proceedings of the National Academy of Sciences, 98(1), 31-36.
+    """
+    from scipy.interpolate import UnivariateSpline
+
+    adata = adata.copy() if copy else adata
+
+    # Validate input
+    if adata.X is None:
+        raise ValueError("AnnData object must have .X attribute with intensity values")
+
+    valid_baseline_types = ["mean", "median", "pseudo-mean", "pseudo-median", None]
+    if baseline_type not in valid_baseline_types:
+        raise ValueError(f"baseline_type must be one of {valid_baseline_types}, got '{baseline_type}'")
+
+    n_samples, n_probes = adata.shape
+
+    if n_samples == 1:
+        warnings.warn(
+            "Invariant set normalization requires multiple samples. With only 1 sample, data is returned unchanged.",
+            UserWarning,
+            stacklevel=2,
+        )
+        adata.uns["normalize_invariantset"] = {
+            "method": "invariantset",
+            "n_samples": n_samples,
+            "applied": False,
+            "reason": "single_sample",
+        }
+        return adata if copy else None
+
+    # Work on log scale
+    X_log = np.log2(adata.X + 1)
+
+    # Create baseline
+    if baseline_type is None:
+        if baseline_index is None:
+            raise ValueError("baseline_index must be provided when baseline_type is None")
+        if baseline_index < 0 or baseline_index >= n_samples:
+            raise ValueError(f"baseline_index must be between 0 and {n_samples - 1}, got {baseline_index}")
+        baseline = X_log[baseline_index, :]
+    elif baseline_type == "mean":
+        baseline = np.mean(X_log, axis=0)
+    elif baseline_type == "median":
+        baseline = np.median(X_log, axis=0)
+    elif baseline_type == "pseudo-mean":
+        # Trimmed mean (remove top and bottom 10%)
+        from scipy.stats import trim_mean
+
+        baseline = trim_mean(X_log, proportiontocut=0.1, axis=0)
+    elif baseline_type == "pseudo-median":
+        # Use median for simplicity
+        baseline = np.median(X_log, axis=0)
+
+    X_normalized = X_log.copy()
+    invariant_indices_list = []
+
+    # Normalize each sample
+    for i in range(n_samples):
+        sample = X_log[i, :]
+
+        # Iteratively identify invariant set
+        invariant_mask = np.ones(n_probes, dtype=bool)
+
+        for iter_num in range(max_iterations):
+            # Compute M and A
+            M = sample[invariant_mask] - baseline[invariant_mask]
+            # A = (sample[invariant_mask] + baseline[invariant_mask]) / 2
+
+            # Compute rank-based criterion
+            M_abs = np.abs(M)
+            ranks = np.argsort(np.argsort(M_abs))  # Ranks of |M|
+            rank_fraction = ranks / len(ranks)
+
+            # Keep probes with small |M| ranks (between prd_td thresholds)
+            keep_local = (rank_fraction >= prd_td[0]) & (rank_fraction <= prd_td[1])
+
+            # Update invariant mask
+            temp_mask = np.zeros(n_probes, dtype=bool)
+            temp_mask[np.where(invariant_mask)[0][keep_local]] = True
+
+            # Check convergence
+            if np.array_equal(temp_mask, invariant_mask):
+                break
+
+            invariant_mask = temp_mask
+
+            # Ensure we have enough invariant probes
+            if np.sum(invariant_mask) < 10:
+                warnings.warn(
+                    f"Sample {i}: Only {np.sum(invariant_mask)} invariant probes found. "
+                    "Using previous mask or all probes.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+                # Revert to previous mask if we have too few probes
+                if iter_num > 0:
+                    break
+                else:
+                    # Use all probes on first iteration if we have too few
+                    invariant_mask = np.ones(n_probes, dtype=bool)
+                    break
+
+        invariant_indices_list.append(np.where(invariant_mask)[0].tolist())
+
+        # Check if we have enough probes for spline fitting
+        n_invariant = np.sum(invariant_mask)
+        if n_invariant < 5:
+            warnings.warn(
+                f"Sample {i}: Too few invariant probes ({n_invariant}). Skipping normalization for this sample.",
+                UserWarning,
+                stacklevel=2,
+            )
+            # Keep original values for this sample
+            continue
+
+        # Fit smoothing spline to invariant probes
+        baseline_inv = baseline[invariant_mask]
+        sample_inv = sample[invariant_mask]
+
+        # Sort by baseline for spline fitting
+        sort_idx = np.argsort(baseline_inv)
+        baseline_sorted = baseline_inv[sort_idx]
+        sample_sorted = sample_inv[sort_idx]
+
+        # Fit smoothing spline
+        try:
+            # Use smoothing spline (s=None for automatic smoothing parameter)
+            spline = UnivariateSpline(baseline_sorted, sample_sorted, s=None, k=3)
+
+            # Apply normalization: correct sample to match baseline
+            # Correction is: normalized = baseline + (sample - spline(baseline))
+            # But this is equivalent to: normalized = sample - (spline(baseline) - baseline)
+            spline_values = spline(baseline)
+            correction = spline_values - baseline
+            X_normalized[i, :] = sample - correction
+
+        except Exception as e:  # noqa: BLE001
+            warnings.warn(
+                f"Sample {i}: Spline fitting failed ({e}). Using linear interpolation instead.",
+                UserWarning,
+                stacklevel=2,
+            )
+            # Fallback to linear interpolation
+            if len(baseline_sorted) >= 2:
+                correction = np.interp(baseline, baseline_sorted, sample_sorted - baseline_sorted)
+                X_normalized[i, :] = sample - correction
+            else:
+                # Not enough points, skip normalization
+                warnings.warn(
+                    f"Sample {i}: Not enough points for interpolation. Skipping.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
+    # Convert back to original scale
+    X_normalized = np.power(2, X_normalized) - 1
+    X_normalized = np.maximum(X_normalized, 0)  # Ensure non-negative
+
+    # Update AnnData
+    adata.X = X_normalized
+    adata.uns["normalize_invariantset"] = {
+        "method": "invariantset",
+        "n_samples": n_samples,
+        "n_probes": n_probes,
+        "baseline_type": baseline_type,
+        "baseline_index": baseline_index,
+        "prd_td": prd_td,
+        "max_iterations": max_iterations,
+        "n_invariant_per_sample": [len(indices) for indices in invariant_indices_list],
+        "applied": True,
+    }
+
+    return adata if copy else None
+
+
+def normalize_qspline(
+    adata: AnnData,
+    target: np.ndarray | None = None,
+    samples: float | int = 0.02,
+    fit_iters: int = 5,
+    smooth: bool = True,
+    spar: float | None = None,
+    copy: bool = False,
+) -> AnnData | None:
+    """Apply cubic spline (qspline) normalization using quantile mapping.
+
+    This method fits cubic splines to map sample quantiles to target quantiles,
+    providing a smooth transformation that normalizes the intensity distribution.
+    Multiple spline fits with offsets are averaged to reduce variability.
+
+    Parameters
+    ----------
+    adata
+        AnnData object with shape (n_samples, n_probes).
+        Must contain intensity values in `.X`.
+    target
+        Target distribution to normalize towards (length n_probes).
+        If None, uses the geometric mean of all samples (default).
+    samples
+        Number of quantile points to use for spline fitting.
+        If < 1, interpreted as sampling rate (e.g., 0.02 = 2% of data).
+        If >= 1, interpreted as number of quantile points.
+        Default is 0.02 (2% sampling rate).
+    fit_iters
+        Number of spline interpolations with offsets to average.
+        More iterations provide smoother results. Default is 5.
+    smooth
+        If True, use smoothing splines. If False, use interpolating splines.
+        Default is True.
+    spar
+        Smoothing parameter for splines (0 to 1).
+        If None, automatically determined. Only used if smooth=True.
+    copy
+        If True, return a copy of the AnnData object. If False, modify in place.
+
+    Returns:
+    -------
+    AnnData or None
+        If `copy=True`, returns normalized AnnData object.
+        If `copy=False`, modifies `adata` in place and returns None.
+        The normalized intensities are stored in `.X`.
+        Normalization metadata is stored in `.uns['normalize_qspline']`.
+
+    Examples:
+    --------
+    >>> import microarray as ma
+    >>> adata = ma.io.cel_batch_to_anndata(cel_files, cdf_path, annotation_db)
+    >>> adata_norm = ma.pp.normalize_qspline(adata, samples=0.05, copy=True)
+
+    Notes:
+    -----
+    Qspline normalization is flexible and can handle complex intensity-dependent
+    biases. It's particularly useful when the transformation between samples is
+    nonlinear.
+
+    The algorithm:
+    1. Compute target distribution (geometric mean if not provided)
+    2. For each sample and each iteration:
+       - Select quantile points (with offset for each iteration)
+       - Fit cubic spline mapping sample quantiles to target quantiles
+       - Apply spline transformation
+       - Average across iterations
+    3. Apply averaged transformation to all probe intensities
+
+    Reference
+    -------
+    Workman, C., et al. (2002). A new non-linear normalization method for
+    reducing variability in DNA microarray experiments.
+    Genome Biology, 3(9), research0048.
+    """
+    from scipy.interpolate import CubicSpline, UnivariateSpline
+
+    adata = adata.copy() if copy else adata
+
+    # Validate input
+    if adata.X is None:
+        raise ValueError("AnnData object must have .X attribute with intensity values")
+
+    if samples <= 0:
+        raise ValueError(f"samples must be positive, got {samples}")
+
+    if fit_iters < 1:
+        raise ValueError(f"fit_iters must be at least 1, got {fit_iters}")
+
+    n_samples, n_probes = adata.shape
+
+    if n_samples == 1:
+        warnings.warn(
+            "Qspline normalization requires multiple samples. With only 1 sample, data is returned unchanged.",
+            UserWarning,
+            stacklevel=2,
+        )
+        adata.uns["normalize_qspline"] = {
+            "method": "qspline",
+            "n_samples": n_samples,
+            "applied": False,
+            "reason": "single_sample",
+        }
+        return adata if copy else None
+
+    # Work on log scale
+    X_log = np.log2(adata.X + 1)
+
+    # Compute target distribution if not provided (geometric mean)
+    if target is None:
+        # Geometric mean = exp(mean(log(x)))
+        # On log scale: mean of log values
+        target = np.mean(X_log, axis=0)
+        target_provided = False
+    else:
+        target = np.log2(np.array(target) + 1)
+        target_provided = True
+        if len(target) != n_probes:
+            raise ValueError(f"target must have length {n_probes}, got {len(target)}")
+
+    # Determine number of quantile points
+    if samples < 1:
+        n_quantiles = max(int(samples * n_probes), 10)
+    else:
+        n_quantiles = int(samples)
+
+    # Normalize each sample
+    X_normalized = np.zeros_like(X_log)
+
+    for i in range(n_samples):
+        sample = X_log[i, :]
+        sample_transformed = np.zeros((fit_iters, n_probes))
+
+        # Multiple iterations with offsets
+        for iter_num in range(fit_iters):
+            # Compute quantile points with offset
+            offset = iter_num / fit_iters
+            quantile_levels = np.linspace(offset, 1 - offset / 2, n_quantiles)
+            quantile_levels = np.clip(quantile_levels, 0.001, 0.999)
+
+            # Get sample and target quantiles
+            sample_quantiles = np.quantile(sample, quantile_levels)
+            target_quantiles = np.quantile(target, quantile_levels)
+
+            # Ensure quantiles are sorted and remove duplicates
+            sort_idx = np.argsort(sample_quantiles)
+            sample_quantiles = sample_quantiles[sort_idx]
+            target_quantiles = target_quantiles[sort_idx]
+
+            # Remove duplicate sample quantiles (keep unique values only)
+            unique_mask = np.concatenate([[True], np.diff(sample_quantiles) > 1e-10])
+            sample_quantiles = sample_quantiles[unique_mask]
+            target_quantiles = target_quantiles[unique_mask]
+
+            # Check if we have enough unique quantiles for spline
+            if len(sample_quantiles) < 4:
+                # Not enough unique points for cubic spline, use linear interpolation
+                sample_transformed[iter_num, :] = np.interp(sample, sample_quantiles, target_quantiles)
+                continue
+
+            # Fit spline
+            if smooth and spar is not None:
+                # Smoothing spline
+                try:
+                    spline = UnivariateSpline(
+                        sample_quantiles,
+                        target_quantiles,
+                        s=spar * len(sample_quantiles),
+                        k=3,
+                    )
+                except Exception:  # noqa: BLE001
+                    # Fallback to cubic spline
+                    warnings.warn(
+                        "Smoothing spline fitting failed. Falling back to cubic spline.",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+                    spline = CubicSpline(sample_quantiles, target_quantiles)
+            elif smooth:
+                # Auto-smoothing spline
+                try:
+                    spline = UnivariateSpline(sample_quantiles, target_quantiles, s=None, k=3)
+                except Exception:  # noqa: BLE001
+                    warnings.warn(
+                        "Auto-smoothing spline fitting failed. Falling back to cubic spline.",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+                    spline = CubicSpline(sample_quantiles, target_quantiles)
+            else:
+                # Interpolating cubic spline
+                spline = CubicSpline(sample_quantiles, target_quantiles)
+
+            # Apply transformation
+            # Clip to avoid extrapolation issues
+            sample_clipped = np.clip(sample, sample_quantiles[0], sample_quantiles[-1])
+            sample_transformed[iter_num, :] = spline(sample_clipped)
+
+        # Average across iterations
+        X_normalized[i, :] = np.mean(sample_transformed, axis=0)
+
+    # Convert back to original scale
+    X_normalized = np.power(2, X_normalized) - 1
+    X_normalized = np.maximum(X_normalized, 0)  # Ensure non-negative
+
+    # Update AnnData
+    adata.X = X_normalized
+    adata.uns["normalize_qspline"] = {
+        "method": "qspline",
+        "n_samples": n_samples,
+        "n_probes": n_probes,
+        "n_quantiles": n_quantiles,
+        "samples": samples,
+        "fit_iters": fit_iters,
+        "smooth": smooth,
+        "spar": spar,
+        "target_provided": target_provided,
+        "applied": True,
+    }
+
+    return adata if copy else None
+
+
+def _select_rank_invariant_subset(X: np.ndarray, subset_size: int) -> np.ndarray:
+    """Select probes with small rank-range across samples (maffy.subset).
+
+    Parameters
+    ----------
+    X
+        Intensity matrix (n_samples, n_probes).
+    subset_size
+        Number of probes to select.
+
+    Returns:
+    -------
+    np.ndarray
+        Boolean mask of selected probes.
+    """
+    n_samples, n_probes = X.shape
+
+    # Compute ranks for each sample
+    ranks = np.zeros_like(X)
+    for i in range(n_samples):
+        ranks[i, :] = np.argsort(np.argsort(X[i, :]))
+
+    # Compute rank range for each probe
+    rank_ranges = np.max(ranks, axis=0) - np.min(ranks, axis=0)
+
+    # Select probes with smallest rank range
+    subset_indices = np.argsort(rank_ranges)[:subset_size]
+    mask = np.zeros(n_probes, dtype=bool)
+    mask[subset_indices] = True
+
+    return mask
+
+
+def normalize_contrasts(
+    adata: AnnData,
+    span: float = 2 / 3,
+    choose_subset: bool = True,
+    subset_size: int = 5000,
+    copy: bool = False,
+) -> AnnData | None:
+    """Apply contrast-based normalization with rank-invariant probe selection.
+
+    This method transforms the data to contrasts (differences from the first sample),
+    applies loess smoothing to each contrast dimension, and transforms back.
+    It optionally selects a subset of rank-invariant probes for fitting efficiency.
+
+    Parameters
+    ----------
+    adata
+        AnnData object with shape (n_samples, n_probes).
+        Must contain intensity values in `.X`.
+    span
+        Fraction of data points to use for loess regression (0 < span <= 1).
+        Larger values produce smoother curves. Default is 2/3.
+    choose_subset
+        If True, automatically select subset of rank-invariant probes.
+        If False, use all probes. Default is True.
+    subset_size
+        Number of probes to use in subset (if choose_subset=True).
+        Default is 5000.
+    copy
+        If True, return a copy of the AnnData object. If False, modify in place.
+
+    Returns:
+    -------
+    AnnData or None
+        If `copy=True`, returns normalized AnnData object.
+        If `copy=False`, modifies `adata` in place and returns None.
+        The normalized intensities are stored in `.X`.
+        Normalization metadata is stored in `.uns['normalize_contrasts']`.
+
+    Examples:
+    --------
+    >>> import microarray as ma
+    >>> adata = ma.io.cel_batch_to_anndata(cel_files, cdf_path, annotation_db)
+    >>> adata_norm = ma.pp.normalize_contrasts(adata, subset_size=3000, copy=True)
+
+    Notes:
+    -----
+    This is a complex method that normalizes using contrast transformations.
+    It can be computationally expensive for large datasets.
+
+    The algorithm:
+    1. Transform to log scale
+    2. Optionally select rank-invariant subset of probes
+    3. Compute contrasts: C[i] = X[i] - X[0] for i > 0
+    4. For each contrast, smooth using loess
+    5. Apply corrections and transform back
+
+    This implementation uses a simplified approach compared to the full
+    multivariate loess in the R affy package, making it more practical
+    for large datasets.
+
+    Reference
+    -------
+    See normalize.contrasts in the affy Bioconductor package and related
+    maffy package documentation.
+    """
+    adata = adata.copy() if copy else adata
+
+    # Validate input
+    if adata.X is None:
+        raise ValueError("AnnData object must have .X attribute with intensity values")
+
+    if span <= 0 or span > 1:
+        raise ValueError(f"span must be between 0 and 1, got {span}")
+
+    n_samples, n_probes = adata.shape
+
+    if n_samples == 1:
+        warnings.warn(
+            "Contrast normalization requires multiple samples. With only 1 sample, data is returned unchanged.",
+            UserWarning,
+            stacklevel=2,
+        )
+        adata.uns["normalize_contrasts"] = {
+            "method": "contrasts",
+            "n_samples": n_samples,
+            "applied": False,
+            "reason": "single_sample",
+        }
+        return adata if copy else None
+
+    if n_samples > 20:
+        warnings.warn(
+            f"Contrast normalization with {n_samples} samples may be slow. "
+            "Consider using a simpler method like quantile or loess normalization.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    # Work on log scale
+    X_log = np.log2(adata.X + 1)
+
+    # Select subset if requested
+    if choose_subset and subset_size < n_probes:
+        subset_mask = _select_rank_invariant_subset(X_log, subset_size)
+        n_subset = np.sum(subset_mask)
+    else:
+        subset_mask = np.ones(n_probes, dtype=bool)
+        n_subset = n_probes
+
+    # Use first sample as reference
+    reference = X_log[0, :]
+
+    # Compute average intensity across all samples for each probe
+    A_all = np.mean(X_log, axis=0)
+
+    X_normalized = X_log.copy()
+
+    # Normalize each sample (except reference)
+    for i in range(1, n_samples):
+        # Compute contrast (difference from reference)
+        contrast = X_log[i, :] - reference
+
+        # Get subset for fitting
+        contrast_subset = contrast[subset_mask]
+        A_subset = A_all[subset_mask]
+
+        # Sort by A for loess fitting
+        sort_idx = np.argsort(A_subset)
+        A_sorted = A_subset[sort_idx]
+        contrast_sorted = contrast_subset[sort_idx]
+
+        # Fit loess curve to contrast
+        contrast_smooth = _lowess_fit(A_sorted, contrast_sorted, span=span)
+
+        # Interpolate to all probes
+        contrast_correction = np.interp(A_all, A_sorted, contrast_smooth)
+
+        # Apply correction: normalized = sample - (fitted_contrast - original_contrast)
+        # This adjusts the sample to have the smoothed contrast relationship
+        X_normalized[i, :] = X_log[i, :] - (contrast_correction - contrast)
+
+    # Convert back to original scale
+    X_normalized = np.power(2, X_normalized) - 1
+    X_normalized = np.maximum(X_normalized, 0)  # Ensure non-negative
+
+    # Update AnnData
+    adata.X = X_normalized
+    adata.uns["normalize_contrasts"] = {
+        "method": "contrasts",
+        "n_samples": n_samples,
+        "n_probes": n_probes,
+        "span": span,
+        "choose_subset": choose_subset,
+        "subset_size": subset_size,
+        "n_subset_used": n_subset,
+        "reference_index": 0,
+        "applied": True,
+    }
+
+    return adata if copy else None