simulation_trajectory_gif#

scdiffeq.plotting._simulation_trajectory_gif.simulation_trajectory_gif(adata_sim: AnnData, savename: str = 'simulation_trajectory.gif', 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 = (6, 6), 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, 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, 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 GIF of simulation trajectories growing over UMAP space.

Parameters:

  • adata_sim (AnnData) – Simulated data from sdq.tl.simulate(), with UMAP coordinates in obsm.

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

  • color (str, default="t") – What to color 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=(6, 6)) – Figure size (width, height) in inches.

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

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

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

  • background_fn (Callable, optional) – Custom function to plot background. Should accept (adata_sim, ax). If None, uses default background (or fate-colored if background_groupby set).

  • 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. Required if background_groupby is set. 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. 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”}]

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

  • 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.

  • title (str, optional) – Plot title.

  • 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 (current time step).

  • trail_alpha (float, default=0.5) – Alpha multiplier for trail points (older time steps), relative to base alpha.

  • 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) tuple.

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

Returns:

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

Return type:

str or tuple

Examples

>>> import scdiffeq as sdq
>>> # Basic usage
>>> sdq.pl.simulation_trajectory_gif(adata_sim, savename="my_sim.gif")
>>> # With custom background
>>> def my_background(adata_sim, ax):
...     xu = adata_sim.obsm["X_umap"]
...     ax.scatter(xu[:, 0], xu[:, 1], c="lightgray", s=50)
>>> sdq.pl.simulation_trajectory_gif(adata_sim, background_fn=my_background)