cellrank.pl.gene_trends

cellrank.pl.gene_trends(adata, model, signals=<object object>, time_key=<object object>, lineages=None, backward=False, data_key=<object object>, time_range=None, transpose=False, callback=None, conf_int=True, same_plot=False, hide_cells=False, perc=None, lineage_cmap=None, fate_prob_cmap=<matplotlib.colors.ListedColormap object>, cell_color=None, cell_alpha=0.6, lineage_alpha=0.2, size=15, lw=2, cbar=True, margins=0.015, sharex=None, sharey=None, gene_as_title=None, legend_loc='best', obs_legend_loc='best', ncols=2, suptitle=None, return_models=False, n_jobs=1, backend='loky', show_progress_bar=True, figsize=None, dpi=None, save=None, return_figure=False, plot_kwargs=mappingproxy({}), genes=<object object>, **kwargs)

Plot gene expression trends along lineages.

See also

• See Visualizing and Clustering Gene Expression Trends on how to visualize the gene trends.

Each lineage is defined via its lineage weights. This function accepts any model based off BaseModel to fit a trend, where we take the lineage weights into account in the loss function.

Beyond gene expression, any observation-aligned quantity that varies continuously along the trajectory can be plotted by passing the appropriate Signal: Gene (expression from X, a layer or raw), Obs (a per-cell covariate in obs, e.g. a gene module score from score_genes()), or Obsm (a column of an obsm array or DataFrame). Signals of different kinds may be mixed in a single call.

Parameters:

• adata (AnnData) – Annotated data object.

• model (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': ..., '*': ...}}.

• signals (str | Signal | Sequence[str | Signal]) –

  What to fit and plot along the trajectory. One or more of:

  • a gene name in var_names (shorthand for Gene),

  • a Gene, e.g. Gene('Gata1', layer='Ms') or Gene('Gata1', use_raw=True),

  • an Obs, e.g. Obs('module_score'),

  • an Obsm, e.g. Obsm('X_pca', 0) or Obsm('palantir', 'pseudotime').

  Added in version 2.3.

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

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

• backward (bool) – Direction of the process.

• data_key (str) –

  Deprecated since version 2.4: Encode the data source in the signal instead, e.g. Gene(name, layer='Ms') or Obs(name).

• genes (str | Sequence[str]) –

  Deprecated since version 2.4: Renamed to signals, which also accepts Signal objects.

• time_range (float | tuple[float | None, float | None] | None | list[float | tuple[float | None, float | None] | 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.

• transpose (bool) – If same_plot = True, group the trends by lineages instead of genes. This forces hide_cells = True. If same_plot = False, show lineages in rows and genes in columns.

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

• conf_int (bool | float) – Whether to compute and show confidence interval. If the model is GAMR, it can also specify the confidence level, the default is \(0.95\).

• same_plot (bool) – Whether to plot all lineages for each gene in the same plot.

• hide_cells (bool) – If True, hide all cells.

• perc (tuple[float, float] | Sequence[tuple[float, float]] | None) – Percentile for colors. Valid values are in \([0, 100]\). This can improve visualization. Can be specified individually for each lineage.

• lineage_cmap (ListedColormap | None) – Categorical colormap to use when coloring in the lineages. If None and same_plot = True, use the corresponding colors in uns, otherwise use 'black'.

• fate_prob_cmap (ListedColormap) – Continuous colormap to use when visualizing the fate probabilities for each lineage. Only used when same_plot = False.

• cell_color (str | None) – Key in obs or var_names used for coloring the cells.

• cell_alpha (float) – Alpha channel for cells.

• lineage_alpha (float) – Alpha channel for lineage confidence intervals.

• size (float) – Size of the points.

• lw (float) – Line width of the smoothed values.

• cbar (bool) – Whether to show colorbar. Always shown when percentiles for lineages differ. Only used when same_plot = False.

• margins (float) – Margins around the plot.

• sharex (str | bool | None) – Whether to share x-axis. Valid options are 'row', 'col' or 'none'.

• sharey (str | bool | None) – Whether to share y-axis. Valid options are 'row'`, ``'col' or 'none'.

• gene_as_title (bool | None) – Whether to show gene names as titles instead on y-axis.

• legend_loc (str | None) – Location of the legend displaying lineages. Only used when same_plot = True.

• obs_legend_loc (str | None) – Location of the legend when cell_color corresponds to a categorical variable.

• ncols (int) – Number of columns of the plot when plotting multiple genes. Only used when same_plot = True.

• suptitle (str | None) – Suptitle of the figure.

• return_figure (bool) – Whether to return the figure object.

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

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

• n_jobs (int | None) – 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 (tuple[float, float] | None) – Size of the figure.

• dpi (int | None) – Dots per inch.

• save (str | Path | None) – Filename where to save the plot.

• plot_kwargs (Mapping[str, Any]) – Keyword arguments for the plot().

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

Return type:

Mapping[str, Mapping[str, BaseModel]] | 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. The returned models can be passed back as model to reuse the already computed gene trends instead of recomputing them.