diff --git a/RISE/__init__.py b/RISE/__init__.py index fe40b944..716f2914 100644 --- a/RISE/__init__.py +++ b/RISE/__init__.py @@ -1,3 +1,10 @@ +from .annotation_alignment import ( + CellTypeAlignmentResults, + ComponentAlignmentResult, + cell_type_alignment, + compute_tau, + score_cell_type_alignment, +) from .factorization import ( correct_conditions, export_factors, @@ -8,11 +15,16 @@ from .opq import OPQQuantizer, find_optimal_opq __all__ = [ + "CellTypeAlignmentResults", + "ComponentAlignmentResult", "OPQQuantizer", + "cell_type_alignment", + "compute_tau", "correct_conditions", "export_factors", "find_optimal_opq", "load_factors", "pf2", "rise_pca_r2x", + "score_cell_type_alignment", ] diff --git a/RISE/annotation_alignment.py b/RISE/annotation_alignment.py new file mode 100644 index 00000000..89f4c178 --- /dev/null +++ b/RISE/annotation_alignment.py @@ -0,0 +1,652 @@ +""" +Cell-type alignment scoring for RISE component projections. + +Quantifies how well a RISE component's cell loadings / projections align +with annotated cell types, answering: +1. Uniqueness: Does the component concentrate on a single annotated cell type (tau)? +2. Combination alignment: Does it align with a specific subset of cell types (AUROC + FDR, eta^2)? +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Any + +import anndata +import numpy as np +import pandas as pd +import scipy.stats as sp + + +@dataclass +class ComponentAlignmentResult: + """Alignment results for a single RISE component. + + Parameters + ---------- + component : int | str + Component index or label. + enrichment : pd.Series + AUROC per cell type distinguishing that type from all others. + p_values : pd.Series + Empirical permutation p-values for enrichment (AUROC > null). + q_values : pd.Series + Benjamini-Hochberg FDR-adjusted p-values. + tau : float + Tissue specificity index tau (uniqueness score in [0, 1]). + eta_squared : float + Proportion of loading variance explained by cell type (in [0, 1]). + kruskal_epsilon_squared : float + Non-parametric effect size epsilon-squared from Kruskal-Wallis. + significant_cell_types : list[str] + List of cell types with significant enrichment (q <= alpha and AUROC > 0.5). + alpha : float + Significance threshold used for q-values. + """ + + component: int | str + enrichment: pd.Series + p_values: pd.Series + q_values: pd.Series + tau: float + eta_squared: float + kruskal_epsilon_squared: float + significant_cell_types: list[str] = field(default_factory=list) + alpha: float = 0.05 + + def to_dict(self) -> dict[str, Any]: + """Convert result to a dictionary.""" + return { + "component": self.component, + "enrichment": self.enrichment.to_dict(), + "p_values": self.p_values.to_dict(), + "q_values": self.q_values.to_dict(), + "tau": self.tau, + "eta_squared": self.eta_squared, + "kruskal_epsilon_squared": self.kruskal_epsilon_squared, + "significant_cell_types": list(self.significant_cell_types), + "alpha": self.alpha, + } + + +@dataclass +class CellTypeAlignmentResults: + """Alignment results across multiple RISE components. + + Parameters + ---------- + results : list[ComponentAlignmentResult] + List of alignment results for individual components. + enrichment : pd.DataFrame + Components x cell types matrix of AUROC values. + p_values : pd.DataFrame + Components x cell types matrix of permutation p-values. + q_values : pd.DataFrame + Components x cell types matrix of joint BH FDR-adjusted p-values. + tau : pd.Series + Tissue specificity index tau for each component. + eta_squared : pd.Series + Eta-squared (variance explained) for each component. + kruskal_epsilon_squared : pd.Series + Kruskal-Wallis epsilon-squared for each component. + significant_cell_types : dict[int | str, list[str]] + Mapping of component to significant cell types. + alpha : float + Significance threshold used for q-values. + """ + + results: list[ComponentAlignmentResult] + enrichment: pd.DataFrame + p_values: pd.DataFrame + q_values: pd.DataFrame + tau: pd.Series + eta_squared: pd.Series + kruskal_epsilon_squared: pd.Series + significant_cell_types: dict[int | str, list[str]] + alpha: float = 0.05 + + def summary(self) -> pd.DataFrame: + """Return a summary DataFrame across all components.""" + top_types = [] + for comp in self.enrichment.index: + row = self.enrichment.loc[comp] + top_types.append(row.idxmax()) + + sig_str = [ + ", ".join(self.significant_cell_types.get(comp, [])) + for comp in self.enrichment.index + ] + + df = pd.DataFrame( + { + "tau": self.tau, + "eta_squared": self.eta_squared, + "kruskal_epsilon_squared": self.kruskal_epsilon_squared, + "top_cell_type": top_types, + "significant_cell_types": sig_str, + }, + index=self.enrichment.index, + ) + return df + + +def compute_auroc_per_cell_type( + loadings: np.ndarray, + cell_type_codes: np.ndarray, + n_types: int, +) -> np.ndarray: + """Compute AUROC for each cell type vs all other cells. + + Parameters + ---------- + loadings : np.ndarray + 1D array of cell loadings of shape (n_cells,). + cell_type_codes : np.ndarray + 1D array of integer cell type assignments in [0, n_types - 1]. + n_types : int + Total number of unique cell types. + + Returns + ------- + np.ndarray + 1D array of AUROC values for each cell type of shape (n_types,). + """ + n_cells = loadings.size + if n_cells == 0 or n_types <= 1: + return np.full(n_types, 0.5, dtype=float) + + ranks = sp.rankdata(loadings, method="average") + counts = np.bincount(cell_type_codes, minlength=n_types).astype(float) + rank_sums = np.bincount(cell_type_codes, weights=ranks, minlength=n_types).astype( + float + ) + + aurocs = np.full(n_types, 0.5, dtype=float) + for k in range(n_types): + n1 = counts[k] + n0 = n_cells - n1 + if n1 > 0 and n0 > 0: + u1 = rank_sums[k] - n1 * (n1 + 1.0) / 2.0 + aurocs[k] = u1 / (n1 * n0) + + return aurocs + + +def compute_tau( + enrichment_scores: np.ndarray | pd.Series, + baseline: float = 0.0, +) -> float: + """Compute tissue specificity index tau (Yanai et al., 2005). + + tau = sum(1 - x_hat) / (n_types - 1), where x_hat = x / max(x). + + When computed over AUROC enrichment values: + - tau -> 1 indicates the component is specific/private to a single cell type. + - tau -> 0 indicates the component is evenly distributed across cell types. + + Parameters + ---------- + enrichment_scores : np.ndarray | pd.Series + 1D array of enrichment values (e.g. AUROC) across cell types. + baseline : float, optional (default: 0.0) + Baseline value subtracted before calculating tau. Values below baseline are clipped to 0. + + Returns + ------- + float + Tau index in [0.0, 1.0]. + """ + x = np.asarray(enrichment_scores, dtype=float) + n = x.size + if n <= 1: + return 0.0 + + if baseline > 0.0: + x = np.maximum(0.0, x - baseline) + + max_val = np.nanmax(x) + if max_val <= 0.0 or not np.isfinite(max_val): + return 0.0 + + x_hat = x / max_val + tau = np.sum(1.0 - x_hat) / (n - 1.0) + return float(np.clip(tau, 0.0, 1.0)) + + +def compute_eta_squared( + loadings: np.ndarray, + cell_type_codes: np.ndarray, + n_types: int, +) -> float: + """Compute omnibus eta-squared (loading ~ cell_type). + + Proportion of loading variance explained by cell-type identity. + + Parameters + ---------- + loadings : np.ndarray + 1D array of cell loadings (shape: n_cells,). + cell_type_codes : np.ndarray + 1D array of integer cell type assignments (shape: n_cells,). + n_types : int + Number of unique cell types. + + Returns + ------- + float + Eta-squared value in [0.0, 1.0]. + """ + y = np.asarray(loadings, dtype=float) + n_cells = y.size + if n_cells <= 1 or n_types <= 1: + return 0.0 + + y_mean = np.mean(y) + ss_total = np.sum((y - y_mean) ** 2) + if ss_total <= 0.0: + return 0.0 + + counts = np.bincount(cell_type_codes, minlength=n_types).astype(float) + valid = counts > 0 + sums = np.bincount(cell_type_codes, weights=y, minlength=n_types) + + means = np.zeros(n_types, dtype=float) + means[valid] = sums[valid] / counts[valid] + + ss_between = np.sum(counts[valid] * (means[valid] - y_mean) ** 2) + eta2 = ss_between / ss_total + return float(np.clip(eta2, 0.0, 1.0)) + + +def compute_kruskal_epsilon_squared( + loadings: np.ndarray, + cell_type_codes: np.ndarray, + n_types: int, +) -> float: + """Compute Kruskal-Wallis epsilon-squared effect size. + + Non-parametric measure of association between loading and cell type. + + Parameters + ---------- + loadings : np.ndarray + 1D array of cell loadings (shape: n_cells,). + cell_type_codes : np.ndarray + 1D array of integer cell type assignments (shape: n_cells,). + n_types : int + Number of unique cell types. + + Returns + ------- + float + Epsilon-squared value in [0.0, 1.0]. + """ + y = np.asarray(loadings, dtype=float) + n_cells = y.size + if n_cells <= 1 or n_types <= 1: + return 0.0 + + groups = [ + y[cell_type_codes == k] + for k in range(n_types) + if np.sum(cell_type_codes == k) > 0 + ] + if len(groups) <= 1: + return 0.0 + + try: + stat, _ = sp.kruskal(*groups) + if not np.isfinite(stat) or stat < 0: + return 0.0 + eps2 = stat / (n_cells - 1.0) + return float(np.clip(eps2, 0.0, 1.0)) + except (ValueError, ZeroDivisionError): + return 0.0 + + +def _validate_and_encode_cell_types( + cell_types: pd.Series | np.ndarray | list, +) -> tuple[np.ndarray, list[str]]: + """Encode cell types to integer codes and return category names.""" + if isinstance(cell_types, pd.Series) and isinstance( + cell_types.dtype, pd.CategoricalDtype + ): + categories = list(cell_types.cat.categories) + codes = cell_types.cat.codes.to_numpy() + # If there are unused categories or NaN, retain only observed categories + observed = np.unique(codes[codes >= 0]) + if len(observed) < len(categories): + # Remap to dense 0..K-1 + remap = {old: new for new, old in enumerate(observed)} + categories = [categories[old] for old in observed] + codes = np.array([remap.get(c, -1) for c in codes], dtype=int) + return codes, categories + + s = pd.Series(cell_types) + cat = pd.Categorical(s) + categories = [str(c) for c in cat.categories] + codes = cat.codes + return codes, categories + + +def cell_type_alignment( + loadings: np.ndarray | pd.Series, + cell_types: pd.Series | np.ndarray, + signed: bool = False, + n_permutations: int = 1000, + alpha: float = 0.05, + random_state: int | np.random.Generator | None = None, + component_label: int | str = 1, +) -> ComponentAlignmentResult: + """Score alignment of a single component's cell loadings with annotated cell types. + + Parameters + ---------- + loadings : np.ndarray | pd.Series + Cell loading vector for one component (shape: n_cells,). + cell_types : pd.Series | np.ndarray + Cell type annotations (length: n_cells). + signed : bool, optional (default: False) + If True, uses the absolute value of loadings (|loading|), which is appropriate + for signed eigen-state projections (e.g. P_i @ B[:, r]). + n_permutations : int, optional (default: 1000) + Number of label permutations to compute empirical p-values. If 0, p-values + are computed using the asymptotic one-sided Mann-Whitney U test. + alpha : float, optional (default: 0.05) + FDR significance threshold for identifying enriched cell types. + random_state : int | np.random.Generator | None, optional (default: None) + Random seed or Generator for permutation reproducibility. + component_label : int | str, optional (default: 1) + Identifier for the component. + + Returns + ------- + ComponentAlignmentResult + Dataclass containing AUROC enrichment, p-values, q-values, tau, eta^2, + and significant cell types. + """ + y = np.asarray(loadings, dtype=float) + if signed: + y = np.abs(y) + + codes, categories = _validate_and_encode_cell_types(cell_types) + n_types = len(categories) + n_cells = y.size + + if codes.size != n_cells: + raise ValueError( + f"Length mismatch: loadings has {n_cells} cells but cell_types has {codes.size}." + ) + + # Compute observed AUROC per cell type + aurocs = compute_auroc_per_cell_type(y, codes, n_types) + + # Compute permutation p-values + p_values = np.ones(n_types, dtype=float) + if n_permutations > 0 and n_types > 1 and n_cells > 0: + rng = ( + random_state + if isinstance(random_state, np.random.Generator) + else np.random.default_rng(random_state) + ) + ranks = sp.rankdata(y, method="average") + counts = np.bincount(codes, minlength=n_types).astype(float) + null_counts = np.zeros(n_types, dtype=int) + + for _ in range(n_permutations): + perm_ranks = rng.permutation(ranks) + perm_sums = np.bincount( + codes, weights=perm_ranks, minlength=n_types + ).astype(float) + for k in range(n_types): + n1 = counts[k] + n0 = n_cells - n1 + if n1 > 0 and n0 > 0: + u_null = perm_sums[k] - n1 * (n1 + 1.0) / 2.0 + auc_null = u_null / (n1 * n0) + if auc_null >= aurocs[k]: + null_counts[k] += 1 + + p_values = (1.0 + null_counts) / (1.0 + n_permutations) + elif n_permutations == 0 and n_types > 1 and n_cells > 0: + # Asymptotic one-sided Mann-Whitney test + for k in range(n_types): + pos = y[codes == k] + neg = y[codes != k] + if pos.size > 0 and neg.size > 0: + res = sp.mannwhitneyu(pos, neg, alternative="greater") + p_values[k] = float(res.pvalue) + + # BH FDR correction across cell types for this component + if n_types > 1: + q_values = sp.false_discovery_control(p_values, method="bh") + else: + q_values = p_values.copy() + + # Scores + tau = compute_tau(aurocs, baseline=0.0) + eta2 = compute_eta_squared(y, codes, n_types) + eps2 = compute_kruskal_epsilon_squared(y, codes, n_types) + + enrichment_series = pd.Series(aurocs, index=categories, name="AUROC") + p_series = pd.Series(p_values, index=categories, name="p_value") + q_series = pd.Series(q_values, index=categories, name="q_value") + + significant = [ + categories[k] + for k in range(n_types) + if q_values[k] <= alpha and aurocs[k] > 0.5 + ] + + return ComponentAlignmentResult( + component=component_label, + enrichment=enrichment_series, + p_values=p_series, + q_values=q_series, + tau=tau, + eta_squared=eta2, + kruskal_epsilon_squared=eps2, + significant_cell_types=significant, + alpha=alpha, + ) + + +def score_cell_type_alignment( + data: anndata.AnnData | np.ndarray | pd.DataFrame, + cell_types: pd.Series | np.ndarray | str | None = None, + signed: bool = False, + projection_key: str = "weighted_projections", + n_permutations: int = 1000, + alpha: float = 0.05, + random_state: int | np.random.Generator | None = None, +) -> CellTypeAlignmentResults: + """Score cell-type alignment across all RISE components. + + Jointly calculates per-cell-type AUROC enrichment, empirical significance with + Benjamini-Hochberg FDR correction across all (component x cell type) tests, + uniqueness (tau), and combination alignment (eta^2). + + Parameters + ---------- + data : anndata.AnnData | np.ndarray | pd.DataFrame + AnnData containing fitted RISE results, or a matrix of cell loadings + (shape: n_cells, n_components). + cell_types : pd.Series | np.ndarray | str | None, optional + Cell type annotations. If data is AnnData and cell_types is a string (or None), + looks up data.obs[cell_types] (defaults to 'cell_type' or 'CellType'). + signed : bool, optional (default: False) + If True, takes the absolute value of loadings (|loading|). + projection_key : str, optional (default: "weighted_projections") + Key in data.obsm to extract loadings from when data is an AnnData. + Defaults to 'weighted_projections', or falls back to 'projections'. + n_permutations : int, optional (default: 1000) + Number of permutations for null AUROC distribution. + alpha : float, optional (default: 0.05) + Significance threshold for FDR q-values. + random_state : int | np.random.Generator | None, optional (default: None) + Random seed or Generator for permutations. + + Returns + ------- + CellTypeAlignmentResults + Container with full results across all components. + """ + # Extract loadings and cell_types + if isinstance(data, anndata.AnnData): + if projection_key in data.obsm: + loadings_matrix = np.asarray(data.obsm[projection_key]) + elif projection_key == "weighted_projections" and "projections" in data.obsm: + loadings_matrix = np.asarray(data.obsm["projections"]) + else: + raise KeyError(f"Could not find '{projection_key}' in data.obsm.") + + if cell_types is None: + for candidate in [ + "cell_type", + "CellType", + "cell_types", + "Cell_Type", + "celltype", + ]: + if candidate in data.obs: + cell_type_series = data.obs[candidate] + break + else: + raise KeyError( + "Cell-type column not specified and none of ['cell_type', 'CellType', 'cell_types'] found in data.obs." + ) + elif isinstance(cell_types, str): + if cell_types not in data.obs: + raise KeyError(f"Column '{cell_types}' not found in data.obs.") + cell_type_series = data.obs[cell_types] + else: + cell_type_series = pd.Series(cell_types) + elif isinstance(data, pd.DataFrame): + loadings_matrix = data.to_numpy() + if cell_types is None or isinstance(cell_types, str): + raise ValueError( + "cell_types must be provided when data is a DataFrame or array." + ) + cell_type_series = pd.Series(cell_types) + else: + loadings_matrix = np.asarray(data) + if cell_types is None or isinstance(cell_types, str): + raise ValueError( + "cell_types must be provided when data is a DataFrame or array." + ) + cell_type_series = pd.Series(cell_types) + + if loadings_matrix.ndim == 1: + loadings_matrix = loadings_matrix[:, np.newaxis] + + n_cells, n_comps = loadings_matrix.shape + codes, categories = _validate_and_encode_cell_types(cell_type_series) + n_types = len(categories) + + if codes.size != n_cells: + raise ValueError( + f"Length mismatch: data has {n_cells} cells but cell_types has {codes.size}." + ) + + rng = ( + random_state + if isinstance(random_state, np.random.Generator) + else np.random.default_rng(random_state) + ) + + component_labels = [i + 1 for i in range(n_comps)] + aurocs_mat = np.zeros((n_comps, n_types), dtype=float) + p_vals_mat = np.ones((n_comps, n_types), dtype=float) + tau_vec = np.zeros(n_comps, dtype=float) + eta2_vec = np.zeros(n_comps, dtype=float) + eps2_vec = np.zeros(n_comps, dtype=float) + + counts = np.bincount(codes, minlength=n_types).astype(float) + + for comp_idx in range(n_comps): + y = loadings_matrix[:, comp_idx].astype(float) + if signed: + y = np.abs(y) + + auc = compute_auroc_per_cell_type(y, codes, n_types) + aurocs_mat[comp_idx] = auc + tau_vec[comp_idx] = compute_tau(auc, baseline=0.0) + eta2_vec[comp_idx] = compute_eta_squared(y, codes, n_types) + eps2_vec[comp_idx] = compute_kruskal_epsilon_squared(y, codes, n_types) + + if n_permutations > 0 and n_types > 1 and n_cells > 0: + ranks = sp.rankdata(y, method="average") + null_counts = np.zeros(n_types, dtype=int) + for _ in range(n_permutations): + perm_ranks = rng.permutation(ranks) + perm_sums = np.bincount( + codes, weights=perm_ranks, minlength=n_types + ).astype(float) + for k in range(n_types): + n1 = counts[k] + n0 = n_cells - n1 + if n1 > 0 and n0 > 0: + u_null = perm_sums[k] - n1 * (n1 + 1.0) / 2.0 + auc_null = u_null / (n1 * n0) + if auc_null >= auc[k]: + null_counts[k] += 1 + p_vals_mat[comp_idx] = (1.0 + null_counts) / (1.0 + n_permutations) + elif n_permutations == 0 and n_types > 1 and n_cells > 0: + for k in range(n_types): + pos = y[codes == k] + neg = y[codes != k] + if pos.size > 0 and neg.size > 0: + res = sp.mannwhitneyu(pos, neg, alternative="greater") + p_vals_mat[comp_idx, k] = float(res.pvalue) + + # Joint BH FDR correction across all (component x cell_type) tests + if aurocs_mat.size > 1: + q_vals_mat = sp.false_discovery_control( + p_vals_mat.ravel(), method="bh" + ).reshape(p_vals_mat.shape) + else: + q_vals_mat = p_vals_mat.copy() + + enrichment_df = pd.DataFrame(aurocs_mat, index=component_labels, columns=categories) + p_values_df = pd.DataFrame(p_vals_mat, index=component_labels, columns=categories) + q_values_df = pd.DataFrame(q_vals_mat, index=component_labels, columns=categories) + tau_series = pd.Series(tau_vec, index=component_labels, name="tau") + eta2_series = pd.Series(eta2_vec, index=component_labels, name="eta_squared") + eps2_series = pd.Series( + eps2_vec, index=component_labels, name="kruskal_epsilon_squared" + ) + + results_list: list[ComponentAlignmentResult] = [] + sig_dict: dict[int | str, list[str]] = {} + + for comp_idx, comp_lbl in enumerate(component_labels): + sig_types = [ + categories[k] + for k in range(n_types) + if q_vals_mat[comp_idx, k] <= alpha and aurocs_mat[comp_idx, k] > 0.5 + ] + sig_dict[comp_lbl] = sig_types + res = ComponentAlignmentResult( + component=comp_lbl, + enrichment=enrichment_df.loc[comp_lbl], + p_values=p_values_df.loc[comp_lbl], + q_values=q_values_df.loc[comp_lbl], + tau=tau_vec[comp_idx], + eta_squared=eta2_vec[comp_idx], + kruskal_epsilon_squared=eps2_vec[comp_idx], + significant_cell_types=sig_types, + alpha=alpha, + ) + results_list.append(res) + + return CellTypeAlignmentResults( + results=results_list, + enrichment=enrichment_df, + p_values=p_values_df, + q_values=q_values_df, + tau=tau_series, + eta_squared=eta2_series, + kruskal_epsilon_squared=eps2_series, + significant_cell_types=sig_dict, + alpha=alpha, + ) diff --git a/RISE/plotting/__init__.py b/RISE/plotting/__init__.py index 9b554667..d1226d0c 100644 --- a/RISE/plotting/__init__.py +++ b/RISE/plotting/__init__.py @@ -2,6 +2,7 @@ Plotting and visualization functions for RISE. """ +from .annotation_alignment import plot_cell_type_alignment from .factors import ( plot_condition_factors, plot_eigenstate_factors, @@ -44,6 +45,7 @@ "plot_avegene_per_celltype", "plot_bicv_r2x", "plot_cell_gene_corr", + "plot_cell_type_alignment", "plot_condition_factors", "plot_eigenstate_factors", "plot_fms_diff_ranks", diff --git a/RISE/plotting/annotation_alignment.py b/RISE/plotting/annotation_alignment.py new file mode 100644 index 00000000..c71fd8ae --- /dev/null +++ b/RISE/plotting/annotation_alignment.py @@ -0,0 +1,226 @@ +""" +Plotting functions for cell-type alignment scoring. +""" + +from __future__ import annotations + +from collections.abc import Sequence + +import anndata +import matplotlib.pyplot as plt +import numpy as np +import pandas as pd +import seaborn as sns +from matplotlib.axes import Axes + +from ..annotation_alignment import CellTypeAlignmentResults, score_cell_type_alignment + +cmap_enrichment = sns.diverging_palette(240, 10, as_cmap=True) + + +def plot_cell_type_alignment( + data: anndata.AnnData | CellTypeAlignmentResults | pd.DataFrame, + ax: Axes | Sequence[Axes] | None = None, + cell_type_col: str = "cell_type", + projection_key: str = "weighted_projections", + signed: bool = False, + n_permutations: int = 1000, + alpha: float = 0.05, + annotate_significance: bool = True, + show_metrics: bool = True, + reorder: bool = True, + cmap=None, + metrics_cmap="Blues", + random_state=None, +) -> Axes | tuple[Axes, ...]: + """Plot cell-type alignment heatmap for RISE components. + + Visualizes per-cell-type AUROC enrichment for each component with optional + significance stars (* for q <= alpha) and row annotations for uniqueness (tau) + and variance explained (eta^2). + + Parameters + ---------- + data : anndata.AnnData | CellTypeAlignmentResults | pd.DataFrame + Alignment results or AnnData object containing RISE results. + ax : Axes | Sequence[Axes] | None, optional + Matplotlib Axes to plot on. Can be: + - None: creates a new figure with appropriate subplots. + - Single Axes: plots the main AUROC heatmap on the provided axes. + - Pair of Axes (ax_main, ax_metrics): plots heatmap on ax_main and metrics on ax_metrics. + cell_type_col : str, optional (default: "cell_type") + Column name in data.obs containing cell type labels (if data is AnnData). + projection_key : str, optional (default: "weighted_projections") + Key in data.obsm containing projections (if data is AnnData). + signed : bool, optional (default: False) + If True, takes the absolute value of loadings. + n_permutations : int, optional (default: 1000) + Number of permutations to run (if scoring an AnnData). + alpha : float, optional (default: 0.05) + FDR significance threshold. + annotate_significance : bool, optional (default: True) + If True, marks significant cell types (q <= alpha, AUROC > 0.5) with an asterisk (*). + show_metrics : bool, optional (default: True) + If True and subplots are available (or ax is None), shows tau and eta^2 row annotations. + reorder : bool, optional (default: True) + If True, reorders components by dominant cell type. + cmap : Colormap or str, optional + Colormap for AUROC enrichment heatmap (defaults to blue-red diverging). + metrics_cmap : Colormap or str, optional (default: "Blues") + Colormap for tau and eta^2 annotations. + random_state : int | None, optional + Random seed for permutations. + + Returns + ------- + Axes | tuple[Axes, ...] + The plotted Matplotlib Axes. + """ + if isinstance(data, CellTypeAlignmentResults): + results = data + elif isinstance(data, anndata.AnnData): + results = score_cell_type_alignment( + data=data, + cell_types=cell_type_col, + projection_key=projection_key, + signed=signed, + n_permutations=n_permutations, + alpha=alpha, + random_state=random_state, + ) + elif isinstance(data, pd.DataFrame): + # Raw enrichment dataframe + enrichment = data + q_values = pd.DataFrame(1.0, index=enrichment.index, columns=enrichment.columns) + tau = pd.Series( + [ + float(np.sum(1 - row / np.max(row)) / max(1, len(row) - 1)) + for _, row in enrichment.iterrows() + ], + index=enrichment.index, + ) + eta2 = pd.Series(0.0, index=enrichment.index) + results = CellTypeAlignmentResults( + results=[], + enrichment=enrichment, + p_values=q_values, + q_values=q_values, + tau=tau, + eta_squared=eta2, + kruskal_epsilon_squared=eta2, + significant_cell_types={}, + alpha=alpha, + ) + else: + raise TypeError(f"Unsupported data type: {type(data)}") + + enrichment_df = results.enrichment.copy() + q_values_df = results.q_values.copy() + tau_series = results.tau.copy() + eta2_series = results.eta_squared.copy() + + # Reorder components by dominant cell type if requested + if reorder and len(enrichment_df) > 1: + vals = enrichment_df.to_numpy() + max_idx = np.argmax(vals, axis=1) + max_val = vals[np.arange(vals.shape[0]), max_idx] + order = np.lexsort((-max_val, max_idx)) + enrichment_df = enrichment_df.iloc[order] + q_values_df = q_values_df.iloc[order] + tau_series = tau_series.iloc[order] + eta2_series = eta2_series.iloc[order] + + # Annotations for significance + annot_df = None + if annotate_significance: + annot_mat = np.full(enrichment_df.shape, "", dtype=object) + for i, comp in enumerate(enrichment_df.index): + for j, ctype in enumerate(enrichment_df.columns): + q = q_values_df.loc[comp, ctype] + auc = enrichment_df.loc[comp, ctype] + if q <= results.alpha and auc > 0.5: + annot_mat[i, j] = "*" + annot_df = pd.DataFrame( + annot_mat, index=enrichment_df.index, columns=enrichment_df.columns + ) + + # Set up axes + heatmap_cmap = cmap if cmap is not None else cmap_enrichment + + if ax is None: + if show_metrics: + _, axes = plt.subplots( + 1, + 2, + figsize=( + max(6, len(enrichment_df.columns) * 0.8 + 2), + max(4, len(enrichment_df) * 0.4 + 1), + ), + gridspec_kw={ + "width_ratios": [len(enrichment_df.columns), 2], + "wspace": 0.08, + }, + ) + ax_main = axes[0] + ax_metrics = axes[1] + else: + _, ax_main = plt.subplots( + figsize=( + max(5, len(enrichment_df.columns) * 0.8), + max(4, len(enrichment_df) * 0.4 + 1), + ) + ) + ax_metrics = None + + elif isinstance(ax, (list, tuple, np.ndarray)) and len(ax) >= 2: + ax_main = ax[0] + ax_metrics = ax[1] + else: + ax_main = ax # type: ignore + ax_metrics = None + + # Main AUROC heatmap + sns.heatmap( + data=enrichment_df, + ax=ax_main, + cmap=heatmap_cmap, + center=0.5, + vmin=0.0, + vmax=1.0, + cbar_kws={"label": "AUROC (Enrichment)"}, + annot=annot_df if annotate_significance else False, + fmt="", + annot_kws={"size": 14, "va": "center", "ha": "center", "weight": "bold"}, + ) + ax_main.set_ylabel("Component") + ax_main.set_xlabel("Cell Type") + ax_main.tick_params(axis="y", rotation=0) + ax_main.tick_params(axis="x", rotation=45) + + # Side metrics heatmap + if ax_metrics is not None and show_metrics: + metrics_df = pd.DataFrame( + { + r"$\tau$": tau_series, + r"$\eta^2$": eta2_series, + }, + index=enrichment_df.index, + ) + sns.heatmap( + data=metrics_df, + ax=ax_metrics, + cmap=metrics_cmap, + vmin=0.0, + vmax=1.0, + cbar_kws={"label": "Score"}, + annot=True, + fmt=".2f", + annot_kws={"size": 9}, + yticklabels=False, + ) + ax_metrics.set_ylabel("") + ax_metrics.tick_params(axis="x", rotation=0) + + if ax_metrics is not None: + return (ax_main, ax_metrics) + return ax_main diff --git a/RISE/tests/test_annotation_alignment.py b/RISE/tests/test_annotation_alignment.py new file mode 100644 index 00000000..6440d1b7 --- /dev/null +++ b/RISE/tests/test_annotation_alignment.py @@ -0,0 +1,238 @@ +""" +Unit tests for cell-type alignment scoring and visualization. +""" + +import anndata +import matplotlib.pyplot as plt +import numpy as np +import pandas as pd +import pytest + +from RISE import ( + CellTypeAlignmentResults, + ComponentAlignmentResult, + cell_type_alignment, + compute_tau, + score_cell_type_alignment, +) +from RISE.annotation_alignment import ( + compute_auroc_per_cell_type, + compute_eta_squared, + compute_kruskal_epsilon_squared, +) +from RISE.plotting import plot_cell_type_alignment + + +@pytest.fixture +def synthetic_alignment_data(): + """Create synthetic AnnData with 3 distinct components: + - Component 1: High only in TypeA (private -> high tau, significant for TypeA only) + - Component 2: High in TypeA and TypeB (moderate tau, both significant) + - Component 3: Random noise (tau and eta^2 near 0, no significant cell types) + """ + rng = np.random.default_rng(42) + n_cells = 600 + types = ["TypeA", "TypeB", "TypeC", "TypeD", "TypeE"] + cell_types = pd.Series(rng.choice(types, size=n_cells), name="cell_type") + + # Comp 1: private to TypeA + c1 = rng.normal(0.0, 0.5, size=n_cells) + c1[cell_types == "TypeA"] += 5.0 + + # Comp 2: high in TypeA and TypeB + c2 = rng.normal(0.0, 0.5, size=n_cells) + c2[cell_types == "TypeA"] += 5.0 + c2[cell_types == "TypeB"] += 5.0 + + # Comp 3: random noise + c3 = rng.normal(0.0, 0.5, size=n_cells) + + loadings = np.column_stack([c1, c2, c3]).astype(np.float32) + + adata = anndata.AnnData( + obs=pd.DataFrame({"cell_type": cell_types}), + obsm={"weighted_projections": loadings, "projections": loadings}, + ) + return adata, cell_types, loadings + + +def test_synthetic_three_components_expectations(synthetic_alignment_data): + """Test the three core scenarios: + 1. One component high only in one cell type (high tau, single significant type). + 2. One component high in two of several types (moderate tau, both types significant). + 3. One component random noise unrelated to cell type (tau and eta^2 near 0, no significant types). + """ + _, cell_types, loadings = synthetic_alignment_data + + # Test single-component scoring + # Comp 1: High in TypeA only + res1 = cell_type_alignment( + loadings[:, 0], cell_types, n_permutations=500, random_state=42 + ) + assert isinstance(res1, ComponentAlignmentResult) + assert res1.tau > 0.55 + assert res1.eta_squared > 0.7 + assert res1.significant_cell_types == ["TypeA"] + assert res1.enrichment["TypeA"] > 0.95 + + # Comp 2: High in TypeA and TypeB + res2 = cell_type_alignment( + loadings[:, 1], cell_types, n_permutations=500, random_state=42 + ) + assert 0.4 < res2.tau < 0.65 + assert res2.eta_squared > 0.7 + assert set(res2.significant_cell_types) == {"TypeA", "TypeB"} + assert res2.enrichment["TypeA"] > 0.8 + assert res2.enrichment["TypeB"] > 0.8 + + # Comp 3: Random noise + res3 = cell_type_alignment( + loadings[:, 2], cell_types, n_permutations=500, random_state=42 + ) + assert res3.tau < 0.15 + assert res3.eta_squared < 0.05 + assert len(res3.significant_cell_types) == 0 + + +def test_score_cell_type_alignment_anndata(synthetic_alignment_data): + """Test score_cell_type_alignment across all components from AnnData.""" + adata, _, _ = synthetic_alignment_data + + res = score_cell_type_alignment( + adata, + cell_types="cell_type", + projection_key="weighted_projections", + n_permutations=500, + random_state=42, + ) + + assert isinstance(res, CellTypeAlignmentResults) + assert res.enrichment.shape == (3, 5) + assert res.q_values.shape == (3, 5) + assert len(res.results) == 3 + + # Check component 1 + assert res.significant_cell_types[1] == ["TypeA"] + assert res.tau.loc[1] > 0.55 + + # Check component 2 + assert set(res.significant_cell_types[2]) == {"TypeA", "TypeB"} + + # Check component 3 + assert len(res.significant_cell_types[3]) == 0 + assert res.tau.loc[3] < 0.15 + assert res.eta_squared.loc[3] < 0.05 + + # Summary table + summary_df = res.summary() + assert summary_df.shape == (3, 5) + assert "top_cell_type" in summary_df.columns + assert "significant_cell_types" in summary_df.columns + assert summary_df.loc[1, "top_cell_type"] == "TypeA" + + +def test_signed_loadings(): + """Test signed=True handles signed loadings by taking absolute values.""" + rng = np.random.default_rng(42) + n_cells = 400 + types = ["Type1", "Type2", "Type3"] + cell_types = pd.Series(rng.choice(types, size=n_cells)) + + # Loading with large negative values in Type1 + loadings = rng.normal(0, 0.2, size=n_cells) + loadings[cell_types == "Type1"] = -5.0 + + res_unsigned = cell_type_alignment( + loadings, cell_types, signed=False, n_permutations=200, random_state=42 + ) + assert ( + res_unsigned.enrichment["Type1"] < 0.1 + ) # Depleted because values are strongly negative + + res_signed = cell_type_alignment( + loadings, cell_types, signed=True, n_permutations=200, random_state=42 + ) + assert res_signed.enrichment["Type1"] > 0.9 # Enriched in magnitude + assert res_signed.significant_cell_types == ["Type1"] + + +def test_asymptotic_mann_whitney(): + """Test n_permutations=0 runs asymptotic Mann-Whitney.""" + rng = np.random.default_rng(42) + n_cells = 200 + types = ["Type1", "Type2"] + cell_types = pd.Series(rng.choice(types, size=n_cells)) + + loadings = rng.normal(0, 1, size=n_cells) + loadings[cell_types == "Type1"] += 3.0 + + res = cell_type_alignment(loadings, cell_types, n_permutations=0) + assert res.p_values["Type1"] < 1e-4 + assert res.significant_cell_types == ["Type1"] + + +def test_to_dict_and_helpers(): + """Test to_dict, compute_tau, and effect size helpers.""" + # Test compute_tau + assert compute_tau(np.array([1.0, 0.0, 0.0]), baseline=0.0) == 1.0 + assert compute_tau(np.array([0.5, 0.5, 0.5]), baseline=0.0) == 0.0 + assert compute_tau(np.array([0.5])) == 0.0 + + # Test eta_squared and epsilon_squared with constant loading + const = np.ones(50) + codes = np.zeros(50, dtype=int) + assert compute_eta_squared(const, codes, 1) == 0.0 + assert compute_kruskal_epsilon_squared(const, codes, 1) == 0.0 + + # Test single-cell / single-type AUROC + assert compute_auroc_per_cell_type(np.array([]), np.array([]), 0).size == 0 + + +def test_plotting_functions(synthetic_alignment_data): + """Test plot_cell_type_alignment visualization.""" + adata, _, loadings = synthetic_alignment_data + + # 1. From AnnData (default creates fig with 2 subplots) + _, axes = plt.subplots(1, 2, figsize=(8, 4)) + out_axes = plot_cell_type_alignment( + adata, ax=axes, n_permutations=100, random_state=42 + ) + assert len(out_axes) == 2 + plt.close("all") + + # 2. Single axes (no metrics subplot) + _, ax = plt.subplots(figsize=(6, 4)) + out_ax = plot_cell_type_alignment( + adata, ax=ax, show_metrics=False, n_permutations=100, random_state=42 + ) + assert out_ax == ax + plt.close("all") + + # 3. From precomputed results + res = score_cell_type_alignment(adata, n_permutations=100, random_state=42) + out_axes2 = plot_cell_type_alignment(res, show_metrics=True) + assert isinstance(out_axes2, (tuple, list)) + plt.close("all") + + # 4. From raw DataFrame + df = pd.DataFrame(loadings[:5, :3], columns=["T1", "T2", "T3"]) + out_ax3 = plot_cell_type_alignment(df, show_metrics=False) + assert out_ax3 is not None + plt.close("all") + + +def test_error_handling(synthetic_alignment_data): + """Test error handling for mismatched dimensions or invalid keys.""" + adata, cell_types, loadings = synthetic_alignment_data + + # Dimension mismatch + with pytest.raises(ValueError, match="Length mismatch"): + cell_type_alignment(loadings[:, 0], cell_types.iloc[:10]) + + # Missing projection key + with pytest.raises(KeyError, match="Could not find"): + score_cell_type_alignment(adata, projection_key="non_existent_key") + + # Missing cell type column + with pytest.raises(KeyError, match="Column 'non_existent_col' not found"): + score_cell_type_alignment(adata, cell_types="non_existent_col")