microarray 0.1.0__py3-none-any.whl

microarray/io/_read.py

@@ -0,0 +1,127 @@
+"""High-level readers for raw CEL data."""
+
+from __future__ import annotations
+
+import os
+from glob import glob
+from typing import Literal
+
+from anndata import AnnData, concat
+from tqdm import tqdm
+
+from microarray.io._anndata_converter import cel_to_anndata
+from microarray.io._cdf import CdfFile
+
+DEFAULT_CEL_PATTERNS = ["*.cel", "*.cel.gz"]
+
+
+def _collect_cel_paths(folder: str, patterns: str | list[str] | None = None) -> list[str]:
+    """Collect CEL file paths from a folder using common CEL filename patterns.
+
+    Parameters
+    ----------
+    folder : str
+        Path to the folder containing CEL files.
+    patterns : str or list of str, optional
+        Filename patterns to match CEL files. Defaults to common CEL patterns.
+
+    Returns:
+    -------
+    list of str
+        List of paths to the CEL files found in the folder.
+
+    Raises:
+    ------
+    ValueError
+        If the specified folder does not exist or if no CEL files are found.
+    """
+    if not os.path.isdir(folder):
+        raise ValueError(f"Not a directory: {folder}")
+
+    if patterns is None:
+        patterns = DEFAULT_CEL_PATTERNS
+
+    cel_paths = []
+    if isinstance(patterns, str):
+        patterns = [patterns]
+    for pattern in patterns:
+        cel_paths.extend(glob(os.path.join(folder, pattern)))
+
+    if len(cel_paths) == 0:
+        raise ValueError(f"No CEL files found in folder: {folder}")
+
+    return cel_paths
+
+
+def read_cel(cel_file: str, cdf_file: str | CdfFile) -> AnnData:
+    """Read a CEL file and return an unprocessed AnnData object.
+
+    The resulting object is probe-grid based (one sample, all array positions)
+    and does not require CDF annotation.
+
+    Parameters
+    ----------
+    cel_file : str
+        Path to the CEL file.
+    cdf_file : str or CdfFile
+        Path to the CDF file or a parsed CdfFile instance for metadata.
+
+    Returns:
+    --------
+    AnnData
+        Unprocessed probe-grid AnnData with shape (1, n_cells).
+    """
+    sample_name = os.path.splitext(os.path.split(cel_file)[-1])[0]
+    return cel_to_anndata(cel_file, cdf_file, sample_name=sample_name)
+
+
+def read_cel_batch(
+    cel_folder: str,
+    cdf_file: str | CdfFile,
+    patterns: str | list[str] | None = None,
+    axis: Literal[0, 1] = 0,
+    join: Literal["inner", "outer"] = "outer",
+    merge: Literal["same", "unique"] | None = "same",
+    verbose: bool = True,
+) -> AnnData:
+    """Read all CEL files from a folder and stack them into one AnnData object.
+
+    Parameters
+    ----------
+    cel_folder : str
+        Path to the folder containing CEL files.
+    cdf_file : str or CdfFile
+        Path to the CDF file or a parsed CdfFile instance for metadata.
+    patterns : str or list of str, optional
+        Filename patterns to match CEL files. Defaults to common CEL patterns.
+    join : {"inner", "outer"}, optional
+        How to join variables when concatenating. Defaults to "outer".
+    merge : {"same", "unique"}, optional
+        How to merge observations when concatenating. Defaults to "same".
+
+
+    Returns:
+    -------
+    AnnData
+        Stacked AnnData object with shape (n_samples, n_cells).
+    """
+    cel_paths = _collect_cel_paths(cel_folder, patterns)
+
+    batch: list[AnnData] = []
+
+    for path in tqdm(cel_paths, desc="Reading CEL files", disable=not verbose):
+        if not os.path.isfile(path):
+            raise ValueError(f"File not found: {path}")
+        batch.append(read_cel(path, cdf_file))
+
+    n_features = batch[0].n_vars
+    for adata in batch[1:]:
+        if adata.n_vars != n_features:
+            raise ValueError("CEL files in folder have inconsistent chip dimensions and cannot be stacked.")
+
+    return concat(
+        batch,
+        axis=axis,
+        merge=merge,
+        join=join,
+    )

microarray/plotting/__init__.py

@@ -0,0 +1,28 @@
+from microarray.plotting._cel import intensities, probe_annotations
+from microarray.plotting._de_plots import venn, volcano
+from microarray.plotting._diagnostic_plots import mds, sa
+from microarray.plotting._heatmap import heatmap
+from microarray.plotting._ma_plots import ma
+from microarray.plotting._pca import pca, pca_feature_variance, pca_variance
+from microarray.plotting._qc_plots import boxplot, densities, histogram
+from microarray.plotting._score import score
+from microarray.plotting._top_table_heatmap import top_table_heatmap
+
+__all__ = [
+    "intensities",
+    "probe_annotations",
+    "ma",
+    "pca",
+    "pca_variance",
+    "pca_feature_variance",
+    "densities",
+    "boxplot",
+    "histogram",
+    "mds",
+    "sa",
+    "volcano",
+    "venn",
+    "heatmap",
+    "top_table_heatmap",
+    "score",
+]

microarray/plotting/_base.py

@@ -0,0 +1,253 @@
+import matplotlib.pyplot as plt
+import numpy as np
+from anndata import AnnData
+from matplotlib.axes import Axes
+from matplotlib.colors import Colormap
+from matplotlib.figure import Figure
+
+
+def _plot_base(
+    ax: Axes | None = None,
+    title: str | None = None,
+    xlabel: str | None = None,
+    ylabel: str | None = None,
+    figsize: tuple[float | int, float | int] = (5, 6),
+) -> tuple[Figure, Axes]:
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=figsize)
+    else:
+        fig = ax.figure
+
+    ax.set_xticks([])
+    ax.set_xticklabels([])
+    if ylabel is not None:
+        ax.set_ylabel(ylabel)
+    if xlabel is not None:
+        ax.set_xlabel(xlabel)
+    if title is not None:
+        ax.set_title(title)
+
+    return fig, ax
+
+
+def _plot_obs_barplot(
+    adata_obj: AnnData,
+    groupby: str,
+    values: str,
+    ax: Axes | None = None,
+    title: str | None = None,
+    xlabel: str | None = None,
+    ylabel: str | None = None,
+    bar_alpha: float = 0.7,
+    bar_width: float = 0.9,
+    jitter_std: float = 0.05,
+    jitter_seed: int = 42,
+    figsize: tuple[float | int, float | int] = (5, 6),
+    cmap: str | Colormap = "tab10",
+    show: bool = True,
+    show_legend: bool = True,
+) -> tuple[Figure, Axes]:
+
+    fig, ax = _plot_base(
+        ax=ax,
+        title=title,
+        xlabel=xlabel,
+        ylabel=ylabel,
+        figsize=figsize,
+    )
+
+    obs = adata_obj.obs[[groupby, values]].copy()
+    group_means = obs.groupby(groupby)[values].mean()
+
+    conditions = group_means.index.tolist()
+    x = np.arange(len(conditions))
+
+    cmap = plt.get_cmap(cmap)
+    colors = {cond: cmap(i % 10) for i, cond in enumerate(conditions)}
+
+    ax.bar(
+        x,
+        group_means.values,
+        color=[colors[c] for c in conditions],
+        alpha=bar_alpha,
+        width=bar_width,
+        edgecolor="black",
+    )
+
+    rng = np.random.default_rng(jitter_seed)
+    for i, cond in enumerate(conditions):
+        y = obs.loc[obs[groupby] == cond, values].values
+        jitter = rng.normal(0, jitter_std, size=len(y))
+        ax.scatter(
+            np.full(len(y), i) + jitter,
+            y,
+            color=colors[cond],
+            edgecolor="black",
+            s=45,
+            label=cond,
+            zorder=3,
+        )
+
+    if ylabel is None:
+        ax.set_ylabel(values)
+    if xlabel is None:
+        ax.set_xlabel(groupby)
+
+    if show_legend:
+        ax.legend(
+            title=None,
+            loc="upper left",
+            bbox_to_anchor=(1.02, 1),
+            borderaxespad=0,
+            frameon=False,
+        )
+
+    if show:
+        fig.show()
+    return fig, ax
+
+
+def _plot_obs_violinplot(
+    adata_obj: AnnData,
+    groupby: str,
+    values: str,
+    ax: Axes | None = None,
+    title: str | None = None,
+    xlabel: str | None = None,
+    ylabel: str | None = None,
+    jitter_std: float = 0.05,
+    jitter_seed: int = 42,
+    figsize: tuple[float | int, float | int] = (5, 6),
+    cmap: str | Colormap = "tab10",
+    show: bool = True,
+    show_legend: bool = True,
+) -> tuple[Figure, Axes]:
+
+    fig, ax = _plot_base(
+        ax=ax,
+        title=title,
+        xlabel=xlabel,
+        ylabel=ylabel,
+        figsize=figsize,
+    )
+
+    obs = adata_obj.obs[[groupby, values]].copy()
+    conditions = obs[groupby].unique().tolist()
+
+    cmap = plt.get_cmap(cmap)
+    colors = {cond: cmap(i % 10) for i, cond in enumerate(conditions)}
+
+    data_to_plot = [obs.loc[obs[groupby] == cond, values].values for cond in conditions]
+    violin_parts = ax.violinplot(data_to_plot, showmeans=False, showmedians=False, showextrema=False)
+
+    for part, cond in zip(violin_parts["bodies"], conditions, strict=True):
+        part.set_facecolor(colors[cond])
+        part.set_edgecolor("black")
+        part.set_alpha(0.7)
+
+    rng = np.random.default_rng(jitter_seed)
+    for i, cond in enumerate(conditions):
+        y = obs.loc[obs[groupby] == cond, values].values
+        jitter = rng.normal(0, jitter_std, size=len(y))
+        ax.scatter(
+            np.full(len(y), i + 1) + jitter,
+            y,
+            color=colors[cond],
+            edgecolor="black",
+            s=45,
+            label=cond,
+            zorder=3,
+        )
+
+    if ylabel is None:
+        ax.set_ylabel(values)
+    if xlabel is None:
+        ax.set_xlabel(groupby)
+
+    if show_legend:
+        ax.legend(
+            title=None,
+            loc="upper left",
+            bbox_to_anchor=(1.02, 1),
+            borderaxespad=0,
+            frameon=False,
+        )
+
+    if show:
+        fig.show()
+    return fig, ax
+
+
+def _plot_obs_boxplot(
+    adata_obj: AnnData,
+    groupby: str,
+    values: str,
+    ax: Axes | None = None,
+    title: str | None = None,
+    xlabel: str | None = None,
+    ylabel: str | None = None,
+    jitter_std: float = 0.05,
+    jitter_seed: int = 42,
+    figsize: tuple[float | int, float | int] = (5, 6),
+    cmap: str | Colormap = "tab10",
+    show: bool = True,
+    show_legend: bool = True,
+    widths: float | list[float] = 0.9,
+) -> tuple[Figure, Axes]:
+
+    fig, ax = _plot_base(
+        ax=ax,
+        title=title,
+        xlabel=xlabel,
+        ylabel=ylabel,
+        figsize=figsize,
+    )
+
+    obs = adata_obj.obs[[groupby, values]].copy()
+    conditions = obs[groupby].unique().tolist()
+
+    cmap = plt.get_cmap(cmap)
+    colors = {cond: cmap(i % 10) for i, cond in enumerate(conditions)}
+
+    data_to_plot = [obs.loc[obs[groupby] == cond, values].values for cond in conditions]
+    bplot = ax.boxplot(data_to_plot, patch_artist=True, widths=widths)
+
+    for patch, cond in zip(bplot["boxes"], conditions, strict=True):
+        patch.set_facecolor(colors[cond])
+        patch.set_edgecolor("black")
+
+    for median in bplot["medians"]:
+        median.set(color="black")
+
+    rng = np.random.default_rng(jitter_seed)
+    for i, cond in enumerate(conditions):
+        y = obs.loc[obs[groupby] == cond, values].values
+        jitter = rng.normal(0, jitter_std, size=len(y))
+        ax.scatter(
+            np.full(len(y), i + 1) + jitter,
+            y,
+            color=colors[cond],
+            edgecolor="black",
+            s=45,
+            label=cond,
+            zorder=3,
+        )
+
+    if ylabel is None:
+        ax.set_ylabel(values)
+    if xlabel is None:
+        ax.set_xlabel(groupby)
+
+    if show_legend:
+        ax.legend(
+            title=None,
+            loc="upper left",
+            bbox_to_anchor=(1.02, 1),
+            borderaxespad=0,
+            frameon=False,
+        )
+
+    if show:
+        fig.show()
+    return fig, ax

microarray/plotting/_cel.py

@@ -0,0 +1,75 @@
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from matplotlib.colors import Colormap
+from matplotlib.patches import Patch
+
+from microarray.io import CelFile
+
+
+def _set_spines(ax: Axes, show_spines: bool) -> None:
+    ax.spines["top"].set_visible(show_spines)
+    ax.spines["right"].set_visible(show_spines)
+    ax.spines["bottom"].set_visible(show_spines)
+    ax.spines["left"].set_visible(show_spines)
+
+
+def _remove_ticks(ax: Axes) -> None:
+    ax.set_xticklabels([])
+    ax.set_yticklabels([])
+    ax.set_xticks([])
+    ax.set_yticks([])
+
+
+def intensities(
+    celfile: CelFile,
+    show_spines: bool = True,
+    show_ticks: bool = False,
+    cmap: str | Colormap = "Reds",
+    ax: Axes | None = None,
+    title: str | None = "Intensities",
+) -> Axes:
+    """Plot the intensities of a CEL file."""
+    if ax is None:
+        _, ax = plt.subplots(figsize=(10, 10))
+    ax.imshow(celfile.intensities, cmap=cmap)
+    if not show_ticks:
+        _remove_ticks(ax)
+
+    _set_spines(ax, show_spines)
+
+    if title is not None:
+        ax.set_title(title)
+
+    return ax
+
+
+def probe_annotations(
+    celfile: CelFile,
+    show_spines: bool = True,
+    show_ticks: bool = False,
+    ax: Axes | None = None,
+    title: str | None = "Probe annotations",
+) -> Axes:
+    """Plot the probe annotations of a CEL file."""
+    if ax is None:
+        _, ax = plt.subplots(figsize=(10, 10))
+    ax.imshow(celfile.probe_annotation == None, cmap="gray")  # noqa: E711
+    if not show_ticks:
+        _remove_ticks(ax)
+
+    _set_spines(ax, show_spines)
+
+    if title is not None:
+        ax.set_title(title)
+
+    ax.legend(
+        handles=[
+            Patch(facecolor="black", label="Probe", linewidth=1, edgecolor="black"),
+            Patch(facecolor="white", label="No probe", linewidth=1, edgecolor="black"),
+        ],
+        labels=["Probe", "No probe"],
+        loc="upper left",
+        bbox_to_anchor=(1, 1),
+        frameon=False,
+    )
+    return ax