simulation_expression_gif#

scdiffeq.plotting._simulation_expression_gif.simulation_expression_gif(adata_sim: AnnData, gene: str, savename: str = 'simulation_expression.gif', groupby: str = 'final_state', groups: List[str] | None = None, color: str = 't', use_key: str = 'X_umap', time_key: str = 't', gene_key: str = 'X_gene_inv', gene_ids_key: str = 'gene_ids', figsize: tuple = (12, 6), expr_width_scale: float = 0.8, expr_height_scale: float = 0.8, umap_cmap: str | Colormap = 'plasma_r', s: float = 10.0, alpha: float = 0.8, background_fn: Callable | None = None, background_groupby: str | None = None, background_cmap: Dict[str, str] | None = None, background_s: float = 100.0, background_inner_s: float = 65.0, umap_labels: List[Dict] | None = None, expr_cmap: Dict[str, str] | None = None, linewidth: float = 2.0, show_std: bool = True, std_alpha: float = 0.2, x_label: str = 't(d)', y_label: str = 'Log-norm. expression', show_time_label: bool = True, time_label_fmt: str = 't = {:.1f}d', time_label_loc: tuple = (0.05, 0.95), time_label_fontsize: int = 12, umap_title: str | None = None, fps: int = 10, duration: float | None = None, hold_frames: int = 10, fade_frames: int = 8, leading_edge_scale: float = 2.0, trail_alpha: float = 0.5, show_progenitor: bool = True, progenitor_frames: int = 8, progenitor_label: str = 'Progenitor', progenitor_s: float = 80.0, progenitor_color: str = 'dodgerblue', dpi: int = 100, return_fig: bool = False, **kwargs) → str | tuple[source]#

Create a dual-panel GIF with synchronized UMAP trajectory and gene expression.

Left panel shows the simulation trajectory growing over UMAP space. Right panel shows temporal gene expression (mean ± std) growing over time.

Parameters:

  • adata_sim (AnnData) – Simulated data from sdq.tl.simulate(), with UMAP coordinates in obsm and gene expression after sdq.tl.invert_scaled_gex().

  • gene (str) – Gene name to plot in the expression panel.

  • savename (str, default="simulation_expression.gif") – Output filename for the GIF.

  • groupby (str, default="final_state") – Column in adata_sim.obs for grouping trajectories in expression panel.

  • groups (List[str], optional) – Specific groups to plot. If None, plots all groups.

  • color (str, default="t") – What to color UMAP points by. Can be column in obs or gene name.

  • use_key (str, default="X_umap") – Key in adata_sim.obsm containing UMAP coordinates.

  • time_key (str, default="t") – Column in adata_sim.obs containing time values.

  • gene_key (str, default="X_gene_inv") – Key in adata_sim.obsm containing gene expression matrix.

  • gene_ids_key (str, default="gene_ids") – Key in adata_sim.uns containing gene names.

  • figsize (tuple, default=(12, 6)) – Figure size (width, height) in inches for the dual-panel figure.

  • expr_width_scale (float, default=0.8) – Width of expression panel relative to UMAP panel. 0.8 means expression panel is 80% as wide as UMAP panel.

  • expr_height_scale (float, default=0.8) – Height scaling for expression panel. Uses GridSpec height_ratios to make expression panel shorter. 0.8 means expression panel is 80% as tall, with remaining space as padding.

  • umap_cmap (str or Colormap, default="plasma_r") – Colormap for UMAP continuous values.

  • s (float, default=10.0) – Point size for simulation points on UMAP.

  • alpha (float, default=0.8) – Point transparency on UMAP.

  • background_fn (Callable, optional) – Custom function to plot UMAP background. Should accept (adata_sim, ax).

  • background_groupby (str, optional) – Column in obs to group background cells by (e.g., “final_state”). When set, background cells are colored by group using background_cmap.

  • background_cmap (Dict[str, str], optional) – Mapping from group names to colors for background. Example: {“Mon.”: “orange”, “Neu.”: “#4a7298”}

  • background_s (float, default=100.0) – Point size for background outer points.

  • background_inner_s (float, default=65.0) – Point size for background inner points.

  • umap_labels (List[Dict], optional) – List of label dictionaries to draw on the UMAP panel. Each dict should have keys “text”, “x”, “y”, and optionally any matplotlib text kwargs like “color”, “fontsize”, “weight”, “ha”, “va”. Example: [{“text”: “Monocyte”, “x”: 10.5, “y”: 10, “color”: “#F08700”, “weight”: “bold”}]

  • expr_cmap (Dict[str, str], optional) – Mapping from group names to colors for expression panel.

  • linewidth (float, default=2.0) – Width of mean lines in expression panel.

  • show_std (bool, default=True) – Whether to show standard deviation shading in expression panel.

  • std_alpha (float, default=0.2) – Transparency of std shading.

  • x_label (str, default="t(d)") – X-axis label for expression panel.

  • y_label (str, default="Log-norm. expression") – Y-axis label for expression panel.

  • show_time_label (bool, default=True) – Whether to show time label on UMAP panel.

  • time_label_fmt (str, default="t = {:.1f}d") – Format string for time label.

  • time_label_loc (tuple, default=(0.05, 0.95)) – Location of time label in axes coordinates.

  • time_label_fontsize (int, default=12) – Font size for time label.

  • umap_title (str, optional) – Title for UMAP panel.

  • fps (int, default=10) – Frames per second for the GIF.

  • duration (float, optional) – Total duration in seconds. If provided, overrides fps.

  • hold_frames (int, default=10) – Number of frames to hold at the end before fading.

  • fade_frames (int, default=8) – Number of frames for the fade-out transition.

  • leading_edge_scale (float, default=2.0) – Size multiplier for leading edge points on UMAP.

  • trail_alpha (float, default=0.5) – Alpha multiplier for trail points on UMAP.

  • show_progenitor (bool, default=True) – Whether to show progenitor intro frames at the start.

  • progenitor_frames (int, default=8) – Number of frames to hold on the progenitor before starting animation.

  • progenitor_label (str, default="Progenitor") – Label text for the progenitor annotation.

  • progenitor_s (float, default=80.0) – Point size for the progenitor marker.

  • progenitor_color (str, default="dodgerblue") – Color for the progenitor marker and annotation.

  • dpi (int, default=100) – Resolution for each frame.

  • return_fig (bool, default=False) – If True, also returns the final frame’s (fig, ax_umap, ax_expr) tuple.

  • **kwargs – Additional keyword arguments passed to UMAP scatter.

Returns:

Path to the saved GIF file. If return_fig=True, returns (savename, fig, ax_umap, ax_expr) tuple with the final frame.

Return type:

str or tuple

Examples

>>> import scdiffeq as sdq
>>> sdq.pl.simulation_expression_gif(
...     adata_sim,
...     gene="Spi1",
...     groupby="final_state",
...     expr_cmap={"Mon.": "orange", "Neu.": "#4a7298"}
... )