microarray 0.1.0__py3-none-any.whl

microarray/plotting/_pca.py

@@ -0,0 +1,320 @@
+"""PCA plotting for microarray data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import matplotlib.pyplot as plt
+import numpy as np
+from adjustText import adjust_text
+from anndata import AnnData
+from matplotlib.axes import Axes
+from matplotlib.colors import Colormap
+
+from microarray.plotting._utils import get_default_colors
+
+
+def pca(
+    adata: AnnData,
+    obsm_key: str = "X_pca",
+    components: tuple[int, int] = (1, 2),
+    labels: list[str] | None = None,
+    colors: str | None = None,
+    cmap: str | Colormap = "viridis",
+    xlab: str | None = None,
+    ylab: str | None = None,
+    title: str = "PCA Plot",
+    ax: Axes | None = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot PCA coordinates stored in ``adata.obsm``.
+
+    If ``obsm_key`` does not exist, PCA is computed automatically using
+    :func:`microarray.tools.pca`.
+
+    Args:
+        adata: AnnData object with PCA embedding in ``.obsm`` or expression data.
+        obsm_key: Key in ``.obsm`` where PCA coordinates are stored.
+        components: 1-based component indices to plot (e.g. ``(1, 2)``).
+        labels: Optional labels for each sample. Defaults to ``adata.obs_names``.
+        colors: Optional ``adata.obs`` column used for coloring points.
+            Categorical columns are shown with a legend. Numeric columns
+            are shown with a continuous colormap.
+        cmap: Colormap used when ``colors`` points to a numeric ``adata.obs`` column.
+        xlab: Optional x-axis label.
+        ylab: Optional y-axis label.
+        title: Plot title.
+        ax: Existing matplotlib axes to reuse.
+        **kwargs: Extra arguments forwarded to ``ax.scatter``.
+
+    Returns:
+        Matplotlib Axes with PCA scatter plot.
+
+    Raises:
+        ValueError: If components are invalid for the available embedding.
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(8, 7))
+
+    if len(components) != 2:
+        raise ValueError("components must contain exactly two indices")
+
+    if obsm_key not in adata.obsm:
+        raise KeyError(f"AnnData .obsm has no '{obsm_key}' key. Compute PCA first using microarray.tools.pca.")
+
+    coords = np.asarray(adata.obsm[obsm_key])
+    n_samples, n_dims = coords.shape
+
+    x_idx = components[0] - 1
+    y_idx = components[1] - 1
+    if x_idx < 0 or y_idx < 0 or x_idx >= n_dims or y_idx >= n_dims:
+        raise ValueError(f"components={components} are out of bounds for embedding with {n_dims} dimensions")
+
+    if labels is None:
+        labels = list(adata.obs_names) if adata.obs_names is not None else [f"Sample {i}" for i in range(n_samples)]
+
+    if colors is None:
+        point_color = get_default_colors(1)[0]
+        ax.scatter(
+            coords[:, x_idx],
+            coords[:, y_idx],
+            c=point_color,
+            s=100,
+            alpha=0.7,
+            edgecolors="black",
+            linewidth=0.5,
+            **kwargs,
+        )
+    else:
+        if colors not in adata.obs.columns:
+            raise KeyError(f"AnnData .obs has no '{colors}' column")
+
+        group_values = adata.obs[colors]
+        numeric_values = np.asarray(group_values)
+
+        if np.issubdtype(numeric_values.dtype, np.number):
+            scatter = ax.scatter(
+                coords[:, x_idx],
+                coords[:, y_idx],
+                c=numeric_values.astype(float),
+                cmap=cmap,
+                s=100,
+                alpha=0.7,
+                edgecolors="black",
+                linewidth=0.5,
+                **kwargs,
+            )
+            colorbar = ax.figure.colorbar(scatter, ax=ax)
+            colorbar.set_label(colors)
+        else:
+            unique_groups = np.unique(numeric_values.astype(str))
+            default_colors = get_default_colors(len(unique_groups))
+            color_map = dict(zip(unique_groups, default_colors, strict=False))
+
+            for group in unique_groups:
+                mask = numeric_values.astype(str) == group
+                ax.scatter(
+                    coords[mask, x_idx],
+                    coords[mask, y_idx],
+                    c=color_map[group],
+                    label=str(group),
+                    s=100,
+                    alpha=0.7,
+                    edgecolors="black",
+                    linewidth=0.5,
+                    **kwargs,
+                )
+            ax.legend(
+                loc="upper left",
+                bbox_to_anchor=(1.02, 1.0),
+                borderaxespad=0.0,
+                frameon=False,
+                title=colors,
+            )
+
+    text_artists = []
+    for i, label in enumerate(labels):
+        text_artists.append(
+            ax.annotate(
+                label,
+                (coords[i, x_idx], coords[i, y_idx]),
+                fontsize=9,
+                alpha=0.8,
+            )
+        )
+
+    adjust_text(
+        text_artists,
+        ax=ax,
+        expand=(1.02, 1.05),
+        force_text=(0.05, 0.08),
+        force_static=(0.05, 0.08),
+        force_pull=(0.25, 0.25),
+        max_move=10,
+        min_arrow_len=0,
+        arrowprops={"arrowstyle": "-", "color": "0.35", "lw": 0.6, "alpha": 0.8},
+    )
+
+    variance_ratio = None
+    if obsm_key in adata.uns and isinstance(adata.uns[obsm_key], dict):
+        variance_ratio = adata.uns[obsm_key].get("variance_ratio")
+
+    if xlab is None:
+        xlab = f"PC{components[0]}"
+        if variance_ratio is not None and len(variance_ratio) > x_idx:
+            xlab = f"{xlab} ({100 * float(variance_ratio[x_idx]):.1f}%)"
+    if ylab is None:
+        ylab = f"PC{components[1]}"
+        if variance_ratio is not None and len(variance_ratio) > y_idx:
+            ylab = f"{ylab} ({100 * float(variance_ratio[y_idx]):.1f}%)"
+
+    ax.set_xlabel(xlab)
+    ax.set_ylabel(ylab)
+    ax.set_title(title)
+
+    ax.grid(False)
+
+    return ax
+
+
+def pca_variance(
+    adata: AnnData,
+    obsm_key: str = "X_pca",
+    xlab: str = "Component",
+    ylab: str = "Cumulative variance explained",
+    title: str = "PCA Cumulative Variance",
+    ax: Axes | None = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot cumulative explained variance from a fitted PCA.
+
+    Args:
+        adata: AnnData object with PCA variance information in ``adata.uns``.
+        obsm_key: PCA key used in ``adata.uns`` (default: ``"X_pca"``).
+        xlab: X-axis label.
+        ylab: Y-axis label.
+        title: Plot title.
+        ax: Existing matplotlib axes to reuse.
+        **kwargs: Extra arguments forwarded to ``ax.plot``.
+
+    Returns:
+        Matplotlib Axes with cumulative variance line chart.
+
+    Raises:
+        KeyError: If variance ratio is unavailable in ``adata.uns``.
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(6, 6))
+
+    if obsm_key not in adata.uns or not isinstance(adata.uns[obsm_key], dict):
+        raise KeyError(f"AnnData .uns has no '{obsm_key}' PCA metadata. Compute PCA first using microarray.tools.pca.")
+
+    variance_ratio = adata.uns[obsm_key].get("variance_ratio")
+    if variance_ratio is None:
+        raise KeyError(
+            f"AnnData .uns['{obsm_key}'] has no 'variance_ratio'. Compute PCA first using microarray.tools.pca."
+        )
+
+    variance_ratio = np.asarray(variance_ratio, dtype=float)
+    cumulative = np.cumsum(variance_ratio)
+    components = np.arange(1, cumulative.size + 1)
+
+    ax.plot(components, cumulative, marker="o", **kwargs)
+    ax.set_xlabel(xlab)
+    ax.set_ylabel(ylab)
+    ax.set_title(title)
+    ax.set_xlim(1, max(1, cumulative.size))
+    ax.set_ylim(0.0, 1.05)
+    ax.grid(False)
+
+    return ax
+
+
+def pca_feature_variance(
+    adata: AnnData,
+    component: int = 1,
+    n_var: int = 20,
+    obsm_key: str = "X_pca",
+    xlab: str = "Feature rank",
+    ylab: str = "Variance contribution",
+    title: str | None = None,
+    ax: Axes | None = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot top feature variance contributions for one PCA component.
+
+    This uses squared PCA loadings as per-feature variance contribution within
+    a selected component and ranks features in decreasing order.
+
+    Args:
+        adata: AnnData object with PCA metadata in ``adata.uns``.
+        component: 1-based PCA component index to inspect.
+        n_var: Number of top-ranked features to display.
+        obsm_key: PCA key used in ``adata.uns`` (default: ``"X_pca"``).
+        xlab: X-axis label.
+        ylab: Y-axis label.
+        title: Plot title. Defaults to ``"PC{component} Feature Variance"``.
+        ax: Existing matplotlib axes to reuse.
+        **kwargs: Extra arguments forwarded to ``ax.plot``.
+
+    Returns:
+        Matplotlib Axes with ranked feature variance contributions.
+
+    Raises:
+        KeyError: If PCA metadata/components are unavailable.
+        ValueError: If ``component`` or ``n_var`` is invalid.
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(6, 6))
+
+    if n_var < 1:
+        raise ValueError("n_var must be at least 1")
+    if component < 1:
+        raise ValueError("component must be at least 1")
+
+    if obsm_key not in adata.uns or not isinstance(adata.uns[obsm_key], dict):
+        raise KeyError(f"AnnData .uns has no '{obsm_key}' PCA metadata. Compute PCA first using microarray.tools.pca.")
+
+    components = adata.uns[obsm_key].get("components")
+    if components is None:
+        raise KeyError(
+            f"AnnData .uns['{obsm_key}'] has no 'components'. Recompute PCA with a version that stores loadings."
+        )
+
+    components = np.asarray(components, dtype=float)
+    n_components, n_features = components.shape
+    if component > n_components:
+        raise ValueError(f"component must be <= {n_components}")
+
+    contribution = np.square(components[component - 1])
+    top_n = min(n_var, n_features)
+    top_idx = np.argsort(contribution)[::-1][:top_n]
+    top_contrib = contribution[top_idx]
+    ranks = np.arange(1, top_n + 1)
+
+    feature_names = np.asarray(adata.var_names.astype(str)) if adata.var_names is not None else np.array([])
+    if feature_names.size != n_features:
+        feature_names = np.array([f"Feature {i}" for i in range(n_features)])
+
+    ax.plot(ranks, top_contrib, marker="o", alpha=0.1, **kwargs)
+
+    for rank, value, idx in zip(ranks, top_contrib, top_idx, strict=False):
+        ax.text(
+            rank,
+            value,
+            feature_names[idx],
+            rotation=90,
+            ha="center",
+            va="center",
+            fontsize=8,
+        )
+
+    if title is None:
+        title = f"PC{component} Feature Variance"
+
+    ax.set_xlabel(xlab)
+    ax.set_ylabel(ylab)
+    ax.set_title(title)
+    ax.grid(False)
+
+    return ax

microarray/plotting/_qc_plots.py

@@ -0,0 +1,335 @@
+"""Quality control plot functions for microarray data."""
+
+from typing import Any
+
+import matplotlib.pyplot as plt
+import numpy as np
+from anndata import AnnData
+from matplotlib.axes import Axes
+from scipy import stats
+
+from microarray.plotting._utils import get_default_colors
+
+
+def densities(
+    adata: AnnData,
+    arrays: list[int | str] | None = None,
+    colors: list[str] | None = None,
+    xlab: str = "Log2 intensity",
+    ylab: str = "Density",
+    title: str = "Intensity Distributions",
+    legend: bool | str = "best",
+    ax: Axes | None = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot overlaid density estimates for multiple arrays.
+
+    Displays kernel density estimates of probe intensity distributions
+    for quality control. Similar arrays should have similar distributions.
+
+    Args:
+        adata: AnnData object with probe-level expression data in .X
+        arrays: List of array indices/names to plot. If None, plots all arrays.
+        colors: List of colors for each array. If None, uses default palette.
+        xlab: X-axis label
+        ylab: Y-axis label
+        title: Plot title
+        legend: Legend position ('best', 'upper right', etc.) or False to disable
+        ax: Existing Axes object. If None, creates new figure.
+        **kwargs: Additional arguments passed to ax.plot()
+
+    Returns:
+        Axes object with density plot
+
+    Examples:
+        >>> import anndata as ad
+        >>> import numpy as np
+        >>> from microarray.plotting import densities
+        >>> data = np.random.randn(1000, 4)
+        >>> adata = ad.AnnData(data.T)
+        >>> ax = densities(adata)
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(10, 6))
+
+    # Get expression matrix (samples x probes)
+    expr = adata.X
+
+    # Convert to log2 if not already
+    if expr.min() >= 0 and (expr.max() - expr.min()) > 20:
+        # Likely raw intensity values
+        log_expr = np.log2(expr + 1)
+    else:
+        log_expr = expr
+
+    # Select arrays to plot
+    if arrays is None:
+        array_indices = list(range(expr.shape[0]))
+        array_names = list(adata.obs_names) if adata.obs_names is not None else [f"Array {i}" for i in array_indices]
+    else:
+        array_indices = []
+        array_names = []
+        for arr in arrays:
+            if isinstance(arr, str):
+                idx = list(adata.obs_names).index(arr)
+                array_indices.append(idx)
+                array_names.append(arr)
+            else:
+                array_indices.append(arr)
+                array_names.append(adata.obs_names[arr] if adata.obs_names is not None else f"Array {arr}")
+
+    # Get colors
+    if colors is None:
+        colors = get_default_colors(len(array_indices))
+    elif len(colors) < len(array_indices):
+        colors = colors + get_default_colors(len(array_indices) - len(colors))
+
+    # Plot density for each array
+    for idx, name, color in zip(array_indices, array_names, colors, strict=False):
+        data = log_expr[idx, :]
+        # Remove NaN values
+        data = data[np.isfinite(data)]
+
+        if len(data) < 2:
+            continue
+
+        # Use kernel density estimation
+        kde = stats.gaussian_kde(data)
+
+        # Create x-axis for density plot
+        x_min, x_max = data.min(), data.max()
+        x_range = x_max - x_min
+        x = np.linspace(x_min - 0.1 * x_range, x_max + 0.1 * x_range, 512)
+
+        # Compute density
+        density = kde(x)
+
+        # Plot
+        ax.plot(x, density, color=color, label=name, linewidth=2, **kwargs)
+
+    # Set labels and title
+    ax.set_xlabel(xlab)
+    ax.set_ylabel(ylab)
+    ax.set_title(title)
+
+    # Add legend if requested
+    if legend and len(array_indices) > 1:
+        ax.legend(loc=legend if isinstance(legend, str) else "best", frameon=True)
+
+    ax.grid(True, alpha=0.3, linestyle="--")
+    ax.set_ylim(bottom=0)  # Density should start at 0
+
+    return ax
+
+
+def boxplot(
+    adata: AnnData,
+    arrays: list[int | str] | None = None,
+    colors: list[str] | str | None = None,
+    xlab: str = "Array",
+    ylab: str = "Log2 intensity",
+    title: str = "Intensity Boxplots",
+    show_fliers: bool = False,
+    ax: Axes | None = None,
+    **kwargs: Any,
+) -> Axes:
+    """Create boxplots of probe intensities across arrays.
+
+    Displays distribution of probe intensities for each array using boxplots.
+    Useful for comparing overall intensity levels and dispersion across arrays.
+
+    Args:
+        adata: AnnData object with probe-level expression data in .X
+        arrays: List of array indices/names to plot. If None, plots all arrays.
+        colors: Color(s) for boxes. Can be single color or list of colors.
+        xlab: X-axis label
+        ylab: Y-axis label
+        title: Plot title
+        show_fliers: Whether to show outlier points. Default False.
+        ax: Existing Axes object. If None, creates new figure.
+        **kwargs: Additional arguments passed to ax.boxplot()
+
+    Returns:
+        Axes object with boxplot
+
+    Examples:
+        >>> import anndata as ad
+        >>> import numpy as np
+        >>> from microarray.plotting import boxplot
+        >>> data = np.random.randn(1000, 4)
+        >>> adata = ad.AnnData(data.T)
+        >>> ax = boxplot(adata)
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(max(8, len(adata.obs_names) * 0.8), 6))
+
+    # Get expression matrix (samples x probes)
+    expr = adata.X
+
+    # 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
+
+    # Select arrays to plot
+    if arrays is None:
+        array_indices = list(range(expr.shape[0]))
+        array_names = list(adata.obs_names) if adata.obs_names is not None else [f"Array {i}" for i in array_indices]
+    else:
+        array_indices = []
+        array_names = []
+        for arr in arrays:
+            if isinstance(arr, str):
+                idx = list(adata.obs_names).index(arr)
+                array_indices.append(idx)
+                array_names.append(arr)
+            else:
+                array_indices.append(arr)
+                array_names.append(adata.obs_names[arr] if adata.obs_names is not None else f"Array {arr}")
+
+    # Prepare data for boxplot
+    data_list = []
+    for idx in array_indices:
+        data = log_expr[idx, :]
+        # Remove NaN values
+        data = data[np.isfinite(data)]
+        data_list.append(data)
+
+    # Create boxplot
+    bp = ax.boxplot(data_list, labels=array_names, showfliers=show_fliers, patch_artist=True, **kwargs)
+
+    # Color boxes
+    if colors is not None:
+        if isinstance(colors, str):
+            # Single color for all boxes
+            for patch in bp["boxes"]:
+                patch.set_facecolor(colors)
+        else:
+            # List of colors
+            if len(colors) < len(array_indices):
+                colors = colors + get_default_colors(len(array_indices) - len(colors))
+            for patch, color in zip(bp["boxes"], colors, strict=False):
+                patch.set_facecolor(color)
+
+    # Set labels and title
+    ax.set_xlabel(xlab)
+    ax.set_ylabel(ylab)
+    ax.set_title(title)
+
+    # Rotate x-axis labels if many arrays
+    if len(array_indices) > 4:
+        ax.set_xticklabels(array_names, rotation=45, ha="right")
+
+    ax.grid(True, alpha=0.3, linestyle="--", axis="y")
+
+    return ax
+
+
+def histogram(
+    adata: AnnData,
+    arrays: list[int | str] | None = None,
+    bins: int = 50,
+    colors: list[str] | None = None,
+    xlab: str = "Log2 intensity",
+    ylab: str = "Frequency",
+    title: str = "Intensity Histograms",
+    alpha: float = 0.6,
+    legend: bool | str = "best",
+    ax: Axes | None = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot histograms of probe intensities for multiple arrays.
+
+    Displays probe intensity distributions as histograms.
+    Similar to densities() but shows actual counts rather than smoothed density.
+
+    Args:
+        adata: AnnData object with probe-level expression data in .X
+        arrays: List of array indices/names to plot. If None, plots all arrays.
+        bins: Number of histogram bins. Default 50.
+        colors: List of colors for each array. If None, uses default palette.
+        xlab: X-axis label
+        ylab: Y-axis label
+        title: Plot title
+        alpha: Transparency of histogram bars (0-1)
+        legend: Legend position ('best', 'upper right', etc.) or False to disable
+        ax: Existing Axes object. If None, creates new figure.
+        **kwargs: Additional arguments passed to ax.hist()
+
+    Returns:
+        Axes object with histogram
+
+    Examples:
+        >>> import anndata as ad
+        >>> import numpy as np
+        >>> from microarray.plotting import histogram
+        >>> data = np.random.randn(1000, 4)
+        >>> adata = ad.AnnData(data.T)
+        >>> ax = histogram(adata)
+    """
+    if ax is None:
+        _, ax = plt.subplots(figsize=(10, 6))
+
+    # Get expression matrix (samples x probes)
+    expr = adata.X
+
+    # 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
+
+    # Select arrays to plot
+    if arrays is None:
+        array_indices = list(range(expr.shape[0]))
+        array_names = list(adata.obs_names) if adata.obs_names is not None else [f"Array {i}" for i in array_indices]
+    else:
+        array_indices = []
+        array_names = []
+        for arr in arrays:
+            if isinstance(arr, str):
+                idx = list(adata.obs_names).index(arr)
+                array_indices.append(idx)
+                array_names.append(arr)
+            else:
+                array_indices.append(arr)
+                array_names.append(adata.obs_names[arr] if adata.obs_names is not None else f"Array {arr}")
+
+    # Get colors
+    if colors is None:
+        colors = get_default_colors(len(array_indices))
+    elif len(colors) < len(array_indices):
+        colors = colors + get_default_colors(len(array_indices) - len(colors))
+
+    # Determine common bin range across all arrays
+    all_data = []
+    for idx in array_indices:
+        data = log_expr[idx, :]
+        data = data[np.isfinite(data)]
+        all_data.extend(data)
+
+    bin_range = (np.min(all_data), np.max(all_data))
+
+    # Plot histogram for each array
+    for idx, name, color in zip(array_indices, array_names, colors, strict=False):
+        data = log_expr[idx, :]
+        data = data[np.isfinite(data)]
+
+        if len(data) < 1:
+            continue
+
+        ax.hist(data, bins=bins, range=bin_range, color=color, alpha=alpha, label=name, edgecolor="none", **kwargs)
+
+    # Set labels and title
+    ax.set_xlabel(xlab)
+    ax.set_ylabel(ylab)
+    ax.set_title(title)
+
+    # Add legend if requested
+    if legend and len(array_indices) > 1:
+        ax.legend(loc=legend if isinstance(legend, str) else "best", frameon=True)
+
+    ax.grid(True, alpha=0.3, linestyle="--", axis="y")
+
+    return ax

microarray/plotting/_score.py

@@ -0,0 +1,38 @@
+from typing import Literal
+
+from anndata import AnnData
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from ._base import _plot_obs_barplot, _plot_obs_boxplot, _plot_obs_violinplot
+
+
+def score(
+    adata: AnnData,
+    groupby: str | None = None,
+    score_name: str = "score",
+    kind: Literal["bar", "box", "violin"] = "bar",
+    **kwargs,
+) -> tuple[Figure, Axes]:
+    """Plot gene set scores.
+
+    This function computes gene set scores using :func:`score` and then visualizes them.
+
+    Args:
+        adata: AnnData object with expression values in ``.X`` or ``layer``.
+        groupby: Optional column in ``adata.obs`` to group samples by for plotting.
+        score_name: Column name in ``adata.obs`` where scores are stored.
+        kind: Type of plot to create. Options are "bar", "box", or "violin".
+        **kwargs: Additional keyword arguments passed to the underlying plotting function.
+
+    Returns:
+        A tuple containing a matplotlib Figure and Axes object with the plot of scores.
+    """
+    if kind == "bar":
+        return _plot_obs_barplot(adata, groupby=groupby, values=score_name, **kwargs)
+    elif kind == "box":
+        return _plot_obs_boxplot(adata, groupby=groupby, values=score_name, **kwargs)
+    elif kind == "violin":
+        return _plot_obs_violinplot(adata, groupby=groupby, values=score_name, **kwargs)
+    else:
+        raise ValueError(f"Invalid plot kind: {kind}. Choose from 'bar', 'box', or 'violin'.")