cellrank.pl.heatmap

cellrank.pl.heatmap(adata, model, genes, time_key, lineages=None, backward=False, mode='lineages', time_range=None, callback=None, cluster_key=None, show_fate_probabilities=False, cluster_genes=False, keep_gene_order=False, scale=True, n_convolve=5, show_all_genes=False, cbar=True, lineage_height=0.33, fontsize=None, xlabel=None, title=None, cmap=<matplotlib.colors.ListedColormap object>, dendrogram=True, return_genes=False, return_models=False, return_figure=False, n_jobs=1, backend='loky', show_progress_bar=True, figsize=None, dpi=None, save=None, gene_order=None, **kwargs)[source]

Plot a heatmap of smoothed gene expression along specified lineages.

See also

This requires a pseudotemporal ordering of cellular dynamics, computed using a method like DPT [Haghverdi et al., 2016] or Palantir [Setty et al., 2019]. The function combines the pseudotemporal ordering with CellRank’s fate probabilities to visualize each gene’s expression along specific trajectories. In the heatmap, genes are ordered according to their peak in pseudotime, which emphasizes expression cascades of sequential activation.

Parameters:

  • adata (AnnData) – Annotated data object.

  • model (Union[BaseModel, Mapping[str, Mapping[str, BaseModel]]]) – Model based on BaseModel to fit. If a dict, gene and lineage specific models can be specified. Use '*' to indicate all genes or lineages, for example {'gene_1': {'*': ...}, 'gene_2': {'lineage_1': ..., '*': ...}}.

  • genes (Sequence[str]) – Genes in var_names.

  • time_key (str) – Key in obs where the pseudotime is stored.

  • lineages (Union[str, Sequence[str], None]) – Names of the lineages for which to plot. If None, plot all lineages.

  • backward (bool) – Direction of the process.

  • mode (Literal['genes', 'lineages']) –

    Valid options are:

    • 'lineages' - group by genes for each lineage in lineages.

    • 'genes' - group by lineages for each gene in genes.

  • time_range (Union[float, tuple[Optional[float], Optional[float]], None, list[Union[float, tuple[Optional[float], Optional[float]], None]]]) –

    Specify start and end times:

    • tuple - it specifies the minimum and maximum pseudotime. Both values can be None, in which case the minimum is the earliest pseudotime and the maximum is automatically determined.

    • float - it specifies the maximum pseudotime.

    This can also be specified on per-lineage basis.

  • gene_symbols – Key in var to use instead of var_names.

  • callback (Union[Callable, Mapping[str, Mapping[str, Callable]], None]) – Function which takes a BaseModel and some keyword arguments for prepare() and returns the prepared model. Can be specified in gene- and lineage-specific manner, similarly to the model.

  • cluster_key (Union[str, Sequence[str], None]) – Key in obs containing categorical observations to be plotted on the top of heatmap. Only available when mode = 'lineages'.

  • show_fate_probabilities (bool) – Whether to also plot fate probabilities alongside the smoothed expression. Only available when mode = 'lineages'.

  • cluster_genes (bool) – Whether to cluster genes using clustermap() when mode = 'lineages'.

  • keep_gene_order (bool) – Whether to keep the gene order for later lineages after the first was sorted. Only available when cluster_genes = False and mode = 'lineages'.

  • scale (bool) – Whether to normalize the gene expression to \([0, 1]\).

  • n_convolve (Optional[int]) – Size of the convolution window when smoothing fate probabilities.

  • show_all_genes (bool) – Whether to show all genes on y-axis.

  • cbar (bool) – Whether to show the colorbar.

  • lineage_height (float) – Height of a bar when mode = 'genes'.

  • fontsize (Optional[float]) – Size of the title’s font.

  • xlabel (Optional[str]) – Label on the x-axis. If None, it is determined based on time_key.

  • title (Optional[str]) – Title of the figure.

  • cmap (ListedColormap) – Colormap to use when visualizing the smoothed expression.

  • dendrogram (bool) – Whether to show dendrogram when cluster_genes = True.

  • return_genes (bool) – Whether to return the sorted or clustered genes. Only available when mode = 'lineages'.

  • return_models (bool) – If True, return the fitted models for each gene in genes and lineage in lineages.

  • return_figure (bool) – Whether to return the figure object. Sets return_genes = True

  • show_progress_bar (bool) – Whether to show a progress bar. Disabling it may slightly improve performance.

  • n_jobs (Optional[int]) – Number of parallel jobs. If -1, use all available cores. If None or 1, the execution is sequential.

  • backend (Literal['loky', 'multiprocessing', 'threading']) – Which backend to use for parallelization. See Parallel for valid options.

  • figsize (Optional[tuple[float, float]]) – Size of the figure.

  • dpi (Optional[int]) – Dots per inch.

  • save (Union[Path, str, None]) – Filename where to save the plot.

  • kwargs (Any) – Keyword arguments for prepare().

  • gene_order (Sequence[str] | None)

Return type:

Union[dict[str, DataFrame], tuple[Mapping[str, Mapping[str, BaseModel]], dict[str, DataFrame]], None]

Returns:

: If return_models = False, just plots the figure and optionally saves it based on save. Otherwise returns the fitted models as {'gene_1': {'lineage_1': <model_11>, ...}, ...}. Models which have failed will be instances of cellrank.models.FailedModel.

  • If return_genes = True and mode = 'lineages', returns a DataFrame

containing the clustered or sorted genes. - If return_figure = True, returns a tuple containing the figure and genes.