microarray 0.1.0__py3-none-any.whl

microarray/tools/_linear_models.py

@@ -0,0 +1,387 @@
+"""Linear model fitting for microarray differential expression analysis.
+
+This module provides functions for fitting linear models to microarray gene
+expression data, supporting both standard least squares and robust regression.
+"""
+
+import re
+import warnings
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+from anndata import AnnData
+from scipy import linalg
+
+
+def lm_fit(
+    adata: AnnData,
+    groupby: str | np.ndarray,
+    method: Literal["ls", "robust"] = "ls",
+    copy: bool = True,
+    return_fit: bool = False,
+) -> AnnData | dict | None:
+    """Fit linear models for each gene across arrays.
+
+    Fits a linear model to the expression data for each gene (row), using the
+    provided design matrix. This is the first step in limma-style differential
+    expression analysis.
+
+    Parameters
+    ----------
+    adata : AnnData
+        Annotated data object containing normalized expression values in `.X`.
+        Rows are samples, columns are features/genes (following AnnData convention).
+    groupby : str
+        Column in `adata.obs` used to define groups. A design matrix is built
+        internally as one-hot encoded group indicators (no intercept).
+
+        For backward compatibility, a NumPy array is also accepted and treated as
+        a precomputed design matrix.
+    method : {"ls", "robust"}, default="ls"
+        Fitting method:
+        - "ls": Standard least squares using QR decomposition
+        - "robust": Robust regression using iteratively reweighted least squares (IRLS)
+    copy : bool, default=True
+        Whether to copy the AnnData object. If False, modifies in place.
+
+    return_fit : bool, default=False
+        If True, return the fit dictionary. Otherwise, store fit results in
+        `adata.uns['lm_fit']` and return `adata` if `copy=True` else None.
+
+    Returns:
+    -------
+    AnnData | dict | None
+        Returns fit dictionary only when `return_fit=True`.
+        Otherwise returns `adata` if `copy=True`, else None.
+
+        The fit object is stored in `adata.uns['lm_fit']` and contains:
+        - coefficients: np.ndarray of shape (n_genes, n_coefficients)
+            Estimated coefficients for each gene and design column
+        - stdev_unscaled: np.ndarray of shape (n_genes, n_coefficients)
+            Unscaled standard errors (before multiplying by sigma)
+        - sigma: np.ndarray of shape (n_genes,)
+            Residual standard deviation for each gene
+        - df_residual: np.ndarray of shape (n_genes,)
+            Residual degrees of freedom for each gene
+        - cov_coefficients: np.ndarray of shape (n_coefficients, n_coefficients)
+            Covariance matrix of coefficients (shared across genes)
+        - design: np.ndarray
+            Copy of the design matrix used for fitting
+        - genes: np.ndarray
+            Gene/feature names from adata.var_names
+        - method: str
+            Method used for fitting
+        - adata: AnnData
+            Reference to (possibly copied) AnnData object for annotation retrieval
+
+    Notes:
+    -----
+    **Algorithm for least squares (method="ls")**:
+
+    For each gene g with expression vector y_g across n samples:
+
+    1. Compute QR decomposition: design = Q @ R
+    2. Solve: coefficients = R^(-1) @ Q.T @ y_g
+    3. Compute fitted values: y_hat = design @ coefficients
+    4. Compute residuals: resid = y_g - y_hat
+    5. Estimate variance: sigma^2 = sum(resid^2) / df_residual
+    6. Unscaled standard errors: sqrt(diag((R.T @ R)^(-1)))
+
+    **Algorithm for robust regression (method="robust")**:
+
+    Uses iteratively reweighted least squares (IRLS) with Huber weights:
+
+    1. Initialize with OLS fit
+    2. Compute residuals and robust scale estimate (MAD)
+    3. Compute Huber weights based on scaled residuals
+    4. Refit with weighted least squares
+    5. Iterate until convergence
+
+    **Design Matrix Requirements**:
+
+    - Must have full column rank or estimable contrasts
+    - Number of rows must match number of samples in adata
+    - Should not have an intercept column of all 1s unless intended
+
+    The expression data is transposed internally to genes × samples for efficient
+    gene-wise fitting, then results are returned in the original orientation.
+
+    Examples:
+    --------
+    >>> import microarray as ma
+    >>> import numpy as np
+    >>> # Suppose we have preprocessed data with 4 samples: 2 control, 2 treatment
+    >>> # adata.X is shape (4, 10000) - 4 samples, 10000 genes
+    >>> # Create design matrix for two-group comparison
+    >>> design = np.array(
+    ...     [
+    ...         [1, 0],  # Sample 1: control
+    ...         [1, 0],  # Sample 2: control
+    ...         [0, 1],  # Sample 3: treatment
+    ...         [0, 1],  # Sample 4: treatment
+    ...     ]
+    ... )
+    >>> # Fit linear models
+    >>> fit = ma.tl.lm_fit(adata, design)
+    >>> # Coefficients: one row per gene, columns are [control_mean, treatment_mean]
+    >>> print(fit["coefficients"].shape)  # (10000, 2)
+    >>> # Use robust fitting for data with outliers
+    >>> fit_robust = ma.tl.lm_fit(adata, design, method="robust")
+
+    References:
+    ----------
+    Smyth, G. K. (2004). Linear models and empirical Bayes methods for assessing
+    differential expression in microarray experiments. Statistical Applications
+    in Genetics and Molecular Biology, 3(1).
+
+    See Also:
+    --------
+    ebayes : Apply empirical Bayes moderation to the fitted model
+    top_table : Extract top differentially expressed genes
+    """
+    adata = adata.copy() if copy else adata
+
+    legacy_design_input = isinstance(groupby, np.ndarray)
+
+    if legacy_design_input:
+        design = np.asarray(groupby, dtype=float)
+        design_columns = [f"coef_{i}" for i in range(design.shape[1])]
+        group_to_column = None
+        group_values = None
+        groupby_col = None
+    else:
+        if groupby not in adata.obs.columns:
+            raise ValueError(f"Column '{groupby}' not found in adata.obs")
+
+        group_series = adata.obs[groupby]
+        if group_series.isna().any():
+            raise ValueError(f"Column '{groupby}' contains missing values, cannot build design matrix")
+
+        # Preserve observed order for non-categorical data.
+        if pd.api.types.is_categorical_dtype(group_series):
+            levels = list(group_series.cat.categories)
+        else:
+            levels = list(pd.unique(group_series))
+
+        def _snake_case(value: object) -> str:
+            text = str(value).strip().lower()
+            text = re.sub(r"[^a-z0-9]+", "_", text)
+            text = re.sub(r"_+", "_", text).strip("_")
+            return text or "group"
+
+        base_names = [_snake_case(level) for level in levels]
+        name_counts: dict[str, int] = {}
+        design_columns = []
+        for name in base_names:
+            count = name_counts.get(name, 0)
+            if count == 0:
+                design_columns.append(name)
+            else:
+                design_columns.append(f"{name}_{count + 1}")
+            name_counts[name] = count + 1
+
+        group_to_column = {levels[i]: design_columns[i] for i in range(len(levels))}
+        group_values = np.asarray(group_series)
+        level_to_idx = {level: i for i, level in enumerate(levels)}
+        design = np.zeros((adata.n_obs, len(levels)), dtype=float)
+        row_idx = np.arange(adata.n_obs)
+        col_idx = np.array([level_to_idx[val] for val in group_values], dtype=int)
+        design[row_idx, col_idx] = 1.0
+        groupby_col = groupby
+
+    # Validate inputs
+    if design.shape[0] != adata.n_obs:
+        raise ValueError(f"Design matrix rows ({design.shape[0]}) must match number of samples ({adata.n_obs})")
+
+    # Check design matrix rank
+    rank = np.linalg.matrix_rank(design)
+    n_coef = design.shape[1]
+    if rank < n_coef:
+        warnings.warn(
+            f"Design matrix is not full rank (rank={rank}, columns={n_coef}). Some coefficients may not be estimable.",
+            category=UserWarning,
+            stacklevel=2,
+        )
+
+    # Transpose to genes × samples for gene-wise fitting
+    # AnnData convention: samples × genes, but we need genes × samples
+    expr = adata.X.T  # Now (n_genes, n_samples)
+    n_genes, n_samples = expr.shape
+
+    if method == "ls":
+        fit_result = _fit_ls(expr, design)
+    elif method == "robust":
+        fit_result = _fit_robust(expr, design)
+    else:
+        raise ValueError(f"Unknown method: {method}. Use 'ls' or 'robust'.")
+
+    # Add metadata
+    fit_result["design"] = design.copy()
+    fit_result["design_columns"] = list(design_columns)
+    fit_result["groupby"] = groupby_col
+    fit_result["group_to_column"] = group_to_column
+    fit_result["group_values"] = group_values
+    fit_result["genes"] = np.asarray(adata.var_names.to_numpy(copy=True))
+    fit_result["method"] = method
+    fit_result["_moderated"] = False
+
+    fit_for_uns = fit_result.copy()
+    adata.uns["lm_fit"] = fit_for_uns
+
+    if return_fit or legacy_design_input:
+        fit_for_return = fit_for_uns.copy()
+        fit_for_return["adata"] = adata
+        return fit_for_return
+    return adata if copy else None
+
+
+def _fit_ls(expr: np.ndarray, design: np.ndarray) -> dict:
+    """Fit linear models using least squares.
+
+    Parameters
+    ----------
+    expr : np.ndarray
+        Expression matrix (n_genes, n_samples)
+    design : np.ndarray
+        Design matrix (n_samples, n_coefficients)
+
+    Returns:
+    -------
+    dict
+        Fit results including coefficients, sigma, df_residual, etc.
+    """
+    n_genes, n_samples = expr.shape
+    n_coef = design.shape[1]
+    df_residual = n_samples - n_coef
+
+    if df_residual <= 0:
+        raise ValueError(
+            f"Not enough samples ({n_samples}) for design with "
+            f"{n_coef} coefficients. Need at least {n_coef + 1} samples."
+        )
+
+    # QR decomposition of design for stable computation
+    Q, R = linalg.qr(design, mode="economic")
+
+    # Compute coefficients: beta = R^-1 @ Q.T @ expr.T
+    # expr.T is (n_samples, n_genes), Q.T @ expr.T is (n_coef, n_genes)
+    coefficients = linalg.solve_triangular(R, Q.T @ expr.T, lower=False).T
+    # Now coefficients is (n_genes, n_coef)
+
+    # Compute fitted values and residuals
+    fitted = coefficients @ design.T  # (n_genes, n_samples)
+    residuals = expr - fitted
+
+    # Estimate residual variance for each gene
+    # sigma^2 = sum(residuals^2) / df_residual
+    rss = np.sum(residuals**2, axis=1)  # Residual sum of squares per gene
+    sigma = np.sqrt(rss / df_residual)
+
+    # Compute unscaled covariance matrix: (R.T @ R)^-1
+    # This is the (X.T @ X)^-1 matrix
+    R_inv = linalg.solve_triangular(R, np.eye(n_coef), lower=False)
+    cov_coef = R_inv @ R_inv.T
+
+    # Unscaled standard errors: sqrt(diag(cov_coef))
+    # These need to be multiplied by sigma to get actual standard errors
+    stdev_unscaled = np.sqrt(np.diag(cov_coef))
+    # Broadcast to (n_genes, n_coef)
+    stdev_unscaled = np.tile(stdev_unscaled, (n_genes, 1))
+
+    return {
+        "coefficients": coefficients,
+        "stdev_unscaled": stdev_unscaled,
+        "sigma": sigma,
+        "df_residual": np.full(n_genes, df_residual, dtype=float),
+        "cov_coefficients": cov_coef,
+    }
+
+
+def _fit_robust(expr: np.ndarray, design: np.ndarray, max_iter: int = 20) -> dict:
+    """Fit linear models using robust regression (IRLS with Huber weights).
+
+    Parameters
+    ----------
+    expr : np.ndarray
+        Expression matrix (n_genes, n_samples)
+    design : np.ndarray
+        Design matrix (n_samples, n_coefficients)
+    max_iter : int, default=20
+        Maximum number of IRLS iterations
+
+    Returns:
+    -------
+    dict
+        Fit results including coefficients, sigma, df_residual, etc.
+    """
+    n_genes, n_samples = expr.shape
+    n_coef = design.shape[1]
+    df_residual = n_samples - n_coef
+
+    if df_residual <= 0:
+        raise ValueError(
+            f"Not enough samples ({n_samples}) for design with "
+            f"{n_coef} coefficients. Need at least {n_coef + 1} samples."
+        )
+
+    # Initialize with OLS
+    Q, R = linalg.qr(design, mode="economic")
+    coefficients = linalg.solve_triangular(R, Q.T @ expr.T, lower=False).T
+
+    # Huber's k parameter
+    k = 1.345
+
+    # Iteratively reweight
+    for _ in range(max_iter):
+        # Compute residuals
+        fitted = coefficients @ design.T
+        residuals = expr - fitted
+
+        # Robust scale estimate using MAD (Median Absolute Deviation)
+        mad = np.median(np.abs(residuals - np.median(residuals, axis=1, keepdims=True)), axis=1)
+        scale = 1.4826 * mad  # Scale factor for normal distribution
+        scale[scale < 1e-8] = 1.0  # Avoid division by zero
+
+        # Compute Huber weights
+        scaled_resid = residuals / scale[:, np.newaxis]
+        weights = np.where(np.abs(scaled_resid) <= k, 1.0, k / np.abs(scaled_resid))
+
+        # Weighted least squares
+        # For each gene, solve: (X.T @ W @ X) @ beta = X.T @ W @ y
+        coefficients_new = np.zeros_like(coefficients)
+        for i in range(n_genes):
+            W = np.diag(weights[i, :])
+            XtWX = design.T @ W @ design
+            XtWy = design.T @ W @ expr[i, :]
+            try:
+                coefficients_new[i, :] = linalg.solve(XtWX, XtWy, assume_a="pos")
+            except linalg.LinAlgError:
+                # Fall back to OLS for this gene
+                coefficients_new[i, :] = coefficients[i, :]
+
+        # Check convergence
+        coef_change = np.max(np.abs(coefficients_new - coefficients))
+        coefficients = coefficients_new
+        if coef_change < 1e-6:
+            break
+
+    # Final residuals and sigma
+    fitted = coefficients @ design.T
+    residuals = expr - fitted
+    rss = np.sum(residuals**2, axis=1)
+    sigma = np.sqrt(rss / df_residual)
+
+    # Unscaled covariance (use final weights)
+    # For simplicity, use OLS covariance structure
+    R_inv = linalg.solve_triangular(R, np.eye(n_coef), lower=False)
+    cov_coef = R_inv @ R_inv.T
+    stdev_unscaled = np.tile(np.sqrt(np.diag(cov_coef)), (n_genes, 1))
+
+    return {
+        "coefficients": coefficients,
+        "stdev_unscaled": stdev_unscaled,
+        "sigma": sigma,
+        "df_residual": np.full(n_genes, df_residual, dtype=float),
+        "cov_coefficients": cov_coef,
+    }

microarray/tools/_mds.py

@@ -0,0 +1,101 @@
+"""Multidimensional scaling for microarray data."""
+
+import numpy as np
+from anndata import AnnData
+from sklearn.manifold import MDS
+from sklearn.metrics import pairwise_distances
+
+
+def mds(
+    adata: AnnData,
+    top: int = 500,
+    gene_selection: str = "common",
+    n_components: int = 2,
+    obsm_key: str = "X_mds",
+    random_state: int = 42,
+    copy: bool = False,
+) -> AnnData | None:
+    """Compute Multidimensional Scaling (MDS) embedding.
+
+    MDS reduces high-dimensional expression data to a lower-dimensional space
+    while preserving pairwise distances between samples. This is useful for
+    visualizing sample relationships and identifying outliers or batch effects.
+
+    Args:
+        adata: AnnData object with probe-level expression data in .X
+        top: Number of top varying probes to use for distance calculation. Default 500.
+        gene_selection: Method for selecting genes:
+            - "common": Use top probes with highest median absolute deviation
+            - "pairwise": Use different probes for each pair (not implemented)
+        n_components: Number of dimensions to reduce to. Default 2.
+        obsm_key: Key to store the MDS embedding in .obsm. Default "X_mds".
+        random_state: Random state for reproducibility. Default 42.
+        copy: Return a copy instead of writing to adata. Default False.
+
+    Returns:
+        Returns None if `copy=False`, else returns an `AnnData` object with the
+        MDS embedding stored in `.obsm[obsm_key]`.
+
+    Examples:
+        >>> import anndata as ad
+        >>> import numpy as np
+        >>> import microarray as ma
+        >>> data = np.random.randn(1000, 6)
+        >>> adata = ad.AnnData(data.T)  # Samples x probes
+        >>> ma.tl.mds(adata, top=500)
+        >>> print(adata.obsm["X_mds"].shape)
+        (6, 2)
+    """
+    adata = adata.copy() if copy else adata
+
+    # Get expression matrix (samples x probes)
+    expr = adata.X
+    n_samples, n_probes = expr.shape
+
+    # Convert to log2 if not already
+    if expr.min() >= 0 and (expr.max() - expr.min()) > 20:
+        log_expr = np.log2(expr + 1)
+    else:
+        log_expr = expr
+
+    # Gene selection
+    if gene_selection == "common":
+        # Calculate median absolute deviation for each probe
+        mad = np.median(np.abs(log_expr - np.median(log_expr, axis=0)), axis=0)
+        # Select top varying probes
+        top_n = min(top, n_probes)
+        top_indices = np.argpartition(mad, -top_n)[-top_n:]
+        expr_subset = log_expr[:, top_indices]
+    elif gene_selection == "pairwise":
+        raise NotImplementedError("Pairwise gene selection not yet implemented")
+    else:
+        raise ValueError(f"Unknown gene_selection method: {gene_selection}")
+
+    # Calculate pairwise distances
+    # Use Euclidean distance by default
+    distances = pairwise_distances(expr_subset, metric="euclidean")
+
+    # Perform MDS
+    mds_model = MDS(
+        n_components=n_components,
+        metric="precomputed",
+        n_init=4,
+        init="random",
+        random_state=random_state,
+    )
+    coords = mds_model.fit_transform(distances)
+
+    # Store in obsm
+    adata.obsm[obsm_key] = coords
+
+    # Store parameters in uns
+    adata.uns[obsm_key] = {
+        "params": {
+            "top": top,
+            "gene_selection": gene_selection,
+            "n_components": n_components,
+            "random_state": random_state,
+        }
+    }
+
+    return adata if copy else None

microarray/tools/_pca.py

@@ -0,0 +1,88 @@
+"""Principal component analysis for microarray data."""
+
+from __future__ import annotations
+
+import numpy as np
+from anndata import AnnData
+from scipy import sparse
+from sklearn.decomposition import PCA
+
+
+def pca(
+    adata: AnnData,
+    n_components: int | None = None,
+    obsm_key: str = "X_pca",
+    layer: str | None = None,
+    scale: bool = False,
+    random_state: int | None = 42,
+    copy: bool = False,
+) -> AnnData | None:
+    """Compute a PCA embedding and store it in ``adata.obsm``.
+
+    Args:
+        adata: AnnData object with expression values in ``.X`` or ``layer``.
+        n_components: Number of principal components to compute.
+            Defaults to ``adata.n_obs``.
+        obsm_key: Key used to store coordinates in ``adata.obsm``.
+        layer: Optional layer key to use instead of ``adata.X``.
+        scale: Whether to z-scale each feature before PCA.
+        random_state: Random seed used by PCA solvers that require randomness.
+        copy: Return a modified copy instead of writing in place.
+
+    Returns:
+        Modified AnnData when ``copy=True``, else ``None``.
+
+    Raises:
+        ValueError: If ``n_components`` is invalid.
+        KeyError: If ``layer`` is provided but missing from ``adata.layers``.
+    """
+    adata = adata.copy() if copy else adata
+
+    if layer is None:
+        matrix = adata.X
+    else:
+        if layer not in adata.layers:
+            raise KeyError(f"AnnData .layers has no '{layer}' layer")
+        matrix = adata.layers[layer]
+
+    values = matrix.toarray() if sparse.issparse(matrix) else np.asarray(matrix)
+    values = np.asarray(values, dtype=float)
+
+    if values.ndim != 2:
+        raise ValueError("Expected a 2D expression matrix")
+
+    if n_components is None:
+        n_components = adata.n_obs
+
+    if n_components < 1:
+        raise ValueError("n_components must be at least 1")
+
+    max_components = min(values.shape)
+    if n_components > max_components:
+        raise ValueError(f"n_components must be <= {max_components} for input with shape {values.shape}")
+
+    if scale:
+        mean = np.nanmean(values, axis=0)
+        std = np.nanstd(values, axis=0)
+        scaled = values - mean
+        valid = std > 0
+        scaled[:, valid] = scaled[:, valid] / std[valid]
+        values = scaled
+
+    model = PCA(n_components=n_components, random_state=random_state)
+    coords = model.fit_transform(values)
+
+    adata.obsm[obsm_key] = coords
+    adata.uns[obsm_key] = {
+        "variance_ratio": model.explained_variance_ratio_.copy(),
+        "variance": model.explained_variance_.copy(),
+        "components": model.components_.copy(),
+        "params": {
+            "n_components": n_components,
+            "layer": layer,
+            "scale": scale,
+            "random_state": random_state,
+        },
+    }
+
+    return adata if copy else None

microarray/tools/_score.py

@@ -0,0 +1,86 @@
+"""Gene set scoring helpers for sample-level summaries."""
+
+from collections.abc import Sequence
+from typing import Literal
+
+import numpy as np
+from anndata import AnnData
+from scipy import sparse
+
+
+def score(
+    adata: AnnData,
+    gene_set: Sequence[str],
+    method: Literal["mean", "median", "zscore"] = "mean",
+    *,
+    score_name: str = "score",
+    var_key: str | None = None,
+    layer: str | None = None,
+    copy: bool = False,
+) -> AnnData | None:
+    """Compute per-sample gene set scores and write them to ``adata.obs``.
+
+    Args:
+        adata: AnnData object with expression values in ``.X`` or ``layer``.
+        gene_set: Sequence of genes/features to score.
+        method: Scoring method: ``"mean"``, ``"median"``, or ``"zscore"``.
+        score_name: Column name used in ``adata.obs`` for output scores.
+        var_key: Optional ``adata.var`` column containing feature identifiers.
+            If not provided, ``adata.var_names`` are used.
+        layer: Optional layer key to use instead of ``adata.X``.
+        copy: Return a copy instead of writing into ``adata`` in place.
+
+    Returns:
+        Modified AnnData when ``copy=True``, else ``None``.
+
+    Raises:
+        ValueError: If ``gene_set`` is empty, method is unknown, or no genes match.
+        KeyError: If ``var_key`` or ``layer`` is missing.
+    """
+    adata = adata.copy() if copy else adata
+
+    if len(gene_set) == 0:
+        raise ValueError("gene_set must contain at least one gene")
+
+    if var_key is None:
+        feature_ids = adata.var_names.astype(str)
+    else:
+        if var_key not in adata.var.columns:
+            raise KeyError(f"AnnData .var has no '{var_key}' column")
+        feature_ids = adata.var[var_key].astype(str)
+
+    gene_lookup = {str(gene) for gene in gene_set}
+    feature_mask = np.asarray(feature_ids.isin(gene_lookup), dtype=bool)
+    if not np.any(feature_mask):
+        raise ValueError("None of the provided genes were found in AnnData features")
+
+    if layer is None:
+        matrix = adata.X
+    else:
+        if layer not in adata.layers:
+            raise KeyError(f"AnnData .layers has no '{layer}' layer")
+        matrix = adata.layers[layer]
+
+    subset = matrix[:, feature_mask]
+    if sparse.issparse(subset):
+        values = subset.toarray()
+    else:
+        values = np.asarray(subset)
+
+    if method == "mean":
+        scores = np.nanmean(values, axis=1)
+    elif method == "median":
+        scores = np.nanmedian(values, axis=1)
+    elif method == "zscore":
+        gene_mean = np.nanmean(values, axis=0)
+        gene_std = np.nanstd(values, axis=0)
+        z_values = np.zeros_like(values, dtype=float)
+        valid = gene_std > 0
+        z_values[:, valid] = (values[:, valid] - gene_mean[valid]) / gene_std[valid]
+        scores = np.nanmean(z_values, axis=1)
+    else:
+        raise ValueError(f"Unknown scoring method: {method}")
+
+    adata.obs[score_name] = np.asarray(scores, dtype=float)
+
+    return adata if copy else None