Quantitative Plots

Heatmaps, dotplots, violin plots, stacked bars, and replicate plots for isoform quantification.

Standalone Plotting Functions

These functions work directly with computed matrices (no TranscriptData needed).

API reference

---

plot_isoform_replicates_from_adata

def plot_isoform_replicates_from_adata(
    adata, # Annotated data object
    group_col:str, # Column in adata.obs defining groups (e.g., 'cell_type')
    replicate_col:str, # Column in adata.obs defining replicates (e.g., 'batch', 'sample_id')
    transcripts:Optional[List[str]]=None, # Explicit list of transcript IDs to plot.
Mutually exclusive with gene_id + top_n.
    gene_id:Optional[str]=None, # Gene ID to plot. Used with top_n to select isoforms.
    top_n:int=2, # Number of top isoforms to plot (when using gene_id)
    epsilon:float=1e-06, # Small value to avoid division by zero
    estimator:str='pseudobulk', # PSI estimator ('pseudobulk', 'dirichlet', 'cell-mean', 'cell-median', 'coverage-weighted')
    dirichlet_alpha:float=0.5, # Dirichlet alpha parameter
    box_overlay:bool=True, # If True, overlay boxplots on scatter points
    point_size:float=4.0, # Size of scatter points
    point_alpha:float=0.85, # Alpha transparency of points
    jitter_width:float=0.12, # Width of horizontal jitter for points
    fig_width:float=10.0, # Figure width in inches
    fig_height:Optional[float]=None, # Figure height in inches (auto if None)
    label_wrap:int=14, # Width for wrapping x-axis labels
    label_rot:int=35, # Rotation angle for x-axis labels
    show_version:bool=False, # If True, show full transcript IDs with version suffix
)->Tuple[plt.Figure, List[str], List[str], Dict[Tuple[int, int], np.ndarray]]: # The matplotlib figure

Plot per-replicate PSI values for a gene’s isoforms across groups.

This function creates a multi-panel plot showing PSI variability across biological replicates for each group. Each row represents one isoform.

---

plot_isoform_violin

def plot_isoform_violin(
    adata, # Annotated data object with transcript counts
    group_col:str, # Column in adata.obs defining groups (e.g., 'cell_type')
    transcripts:Optional[List[str]]=None, # Explicit list of transcript IDs to plot.
Mutually exclusive with gene_id + top_n.
    gene_id:Optional[str]=None, # Gene ID to plot. Used with top_n to select isoforms.
    top_n:int=2, # Number of top isoforms to plot by mean expression (when using gene_id)
    gene_col:str='geneId', # Column in adata.var mapping transcripts to genes
    layer:str | None=None, # Layer in adata.layers to use. If None, uses adata.X
    log1p:bool=True, # Apply log1p transformation to counts
    drop_zeros:bool=False, # Remove zero values before plotting
    min_cells_per_group:int=10, # Minimum cells required per group to include
    figsize:tuple[float, float] | None=None, # Overall figure size (width, height). If None, computed from figsize_per_panel
    figsize_per_panel:tuple[float, float]=(4.0, 4.0), # Size per isoform panel (width, height)
    palette:str | list='tab10', # Color palette for groups
    stripplot:bool=True, # Overlay scatter points on violins
    point_size:float=2.0, # Size of scatter points
    point_alpha:float=0.6, # Alpha transparency of points
    jitter:float=0.25, # Horizontal jitter width for points
    sharey:bool=True, # Share y-axis across panels
    title:str | None=None, # Custom plot title. If None, uses gene_id or first transcript
    show_version:bool=False, # Show full transcript IDs with version suffix
)->Tuple[plt.Figure, List]: # The matplotlib figure

Plot violin plots showing isoform expression distribution across groups.

Creates multi-panel violin plots for a gene’s isoforms, with optional scatter points overlay. Supports both raw counts and log-transformed data.

---

plot_isoform_heatmap_percell

def plot_isoform_heatmap_percell(
    adata, # Annotated data object with transcript counts
    group_col:str, # Column in adata.obs for grouping/sorting cells (e.g., 'cell_type')
    transcripts:Optional[List[str]]=None, # Explicit list of transcript IDs to plot.
Mutually exclusive with gene_id + top_n.
    gene_id:Optional[str]=None, # Gene ID to plot. Used with top_n to select isoforms.
    top_n:int=2, # Number of top isoforms to include by mean expression (when using gene_id)
    epsilon:float=1e-06, # Small value to avoid division by zero
    cell_subset:Optional[List[str]]=None, # Specific cell IDs to include. If None, uses all cells.
    max_cells:Optional[int]=None, # Maximum number of cells to plot. If exceeded, samples randomly within each group.
    cluster_within_groups:bool=True, # Whether to hierarchically cluster cells within each group
    cmap:str='magma', # Colormap name
    colorbar_label:str='PSI', # Label for colorbar
    fig_width:float=20.0, # Figure width in inches
    fig_height:Optional[float]=None, # Figure height in inches (auto if None)
    show_colorbar:bool=True, # Whether to show colorbar
    show_cell_labels:bool=False, # Whether to show individual cell labels on x-axis
    show_group_boundaries:bool=True, # Whether to show vertical lines between groups
    show_version:bool=False, # Show full transcript IDs with version suffix
)->Tuple[plt.Figure, List[str], List[str], np.ndarray]: # The matplotlib figure

Plot a per-cell heatmap for isoform PSI values.

This function creates a heatmap where each column represents an individual cell (not aggregated by group). Cells are sorted by group and optionally clustered within each group to reveal similar patterns.

---

plot_isoform_stacked_bar

def plot_isoform_stacked_bar(
    adata, # Annotated data object with transcript counts
    group_col:str, # Column in adata.obs defining groups (e.g., 'cell_type')
    transcripts:Optional[List[str]]=None, # Explicit list of transcript IDs to plot.
Mutually exclusive with gene_id + top_n.
    gene_id:Optional[str]=None, # Gene ID to plot. Used with top_n to select isoforms.
    top_n:Optional[int]=None, # Number of top isoforms to show separately. Others grouped as "Other".
If None when using gene_id, shows all isoforms.
    estimator:str='pseudobulk', # PSI estimator ('pseudobulk', 'dirichlet', 'cell-mean', 'cell-median', 'coverage-weighted')
    dirichlet_alpha:float=0.5, # Dirichlet alpha parameter
    epsilon:float=1e-06, # Small value to avoid division by zero
    cmap:str='tab10', # Colormap name for isoforms
    fig_width:float=12.0, # Figure width in inches
    fig_height:float=6.0, # Figure height in inches
    label_wrap:int=14, # Width for wrapping x-axis labels
    label_rot:int=45, # Rotation angle for x-axis labels
    show_legend:bool=True, # Whether to show legend
    show_values:bool=False, # Whether to show percentage values on bars
    show_version:bool=False, # Show full transcript IDs with version suffix
)->Tuple[plt.Figure, List[str], List[str], np.ndarray]: # The matplotlib figure

Plot stacked bar chart showing isoform composition per group.

Creates a stacked bar chart where each bar represents a group (e.g., cell type) and shows the percent composition of each isoform within that group.