dynamo.pl.causality

dynamo.pl.causality(adata, pairs_mat, hessian_matrix=False, xkey=None, ykey=None, zkey=None, log=True, drop_zero_cells=False, delay=0, k=30, normalize=True, grid_num=25, n_row=1, n_col=None, cmap='viridis', show_rug=True, show_extent=False, ext_format=None, stacked_fraction=False, figsize=(6, 4), save_show_or_return='show', save_kwargs={}, return_data=False, **kwargs)[source]

Plot the heatmap for the expected value z(t) given x and y data.

Parameters:

  • adata (AnnData) – an AnnData object.

  • pairs_mat (ndarray) – a matrix where each row is the gene pair and the first column is the hypothetical source or regulator while the second column represents the hypothetical target. The name in this matrix should match the name in the gene_short_name column of the adata object.

  • hessian_matrix (bool) – whether to visualize the Hessian matrix results (row, column are the regulatory/co-regulator gene expression while the color is the results of the Hessian to the effector). Defaults to False.

  • xkey (Optional[str]) – the layer key of x data (regulator gene 1). If None, dynamo’s default naming rule would be used. Defaults to None.

  • ykey (Optional[str]) – the layer key of y data (regulator gene 2). If None, dynamo’s default naming rule would be used. Defaults to None.

  • zkey (Optional[str]) – the layer key of z data (the hypothetical target). If None, dynamo’s default naming rule would be used. Defaults to None.

  • log (bool) – whether to perform log transformation (using log(expression + 1)) before calculating density estimates. Defaults to True.

  • drop_zero_cells (bool) – whether to drop cells that with zero expression for either the potential regulator or potential target. This can signify the relationship between potential regulators and targets, speed up the calculation, but at the risk of ignoring strong inhibition effects from certain regulators to targets. Defaults to False.

  • delay (int) – the time delay between the source and target gene. Always zero because we don’t have real time-series. Defaults to 0.

  • k (int) – number of k-nearest neighbors used in calculating 2-D kernel density. Defaults to 30.

  • normalize (bool) – whether to row-scale the data. Defaults to True.

  • grid_num (int) – the number of grid when creating the lagged DREVI plot. Defaults to 25.

  • n_row (int) – the number of rows used to layout the faceted cluster panels. Defaults to 1.

  • n_col (Optional[int]) – the number of columns used to layout the faceted cluster panels. Defaults to None.

  • cmap (Union[str, Colormap, None]) – the color map used to plot the heatmap. Could be the name of the color map or a matplotlib color map object. If None, the color map would be generated automatically. Defaults to “viridis”.

  • show_rug (bool) – whether to plot marginal distributions by drawing ticks along the x and y axes. Defaults to True.

  • show_extent (bool) – whether to extend the figure. If False, show_ridge and show_rug would be set to False automatically. Defaults to False.

  • ext_format (Optional[List[str]]) – the string/list of strings (the first is for x and second for y labels) that will be used to format the ticks on x or y-axis. If it is None or one of the element in the list is None, the default setting will be used. Defaults to None.

  • stacked_fraction (bool) – if True the jacobian will be represented as a stacked fraction in the title, otherwise a linear fraction style is used. Defaults to False.

  • figsize (Tuple[float, float]) – the size of the figure. Defaults to (6, 4).

  • save_show_or_return (Literal['save', 'show', 'both', 'all']) – whether to save or show the figure. If “both”, it will save and plot the figure at the same time. If “all”, the figure will be saved, displayed and the associated axis and other object will be return.

  • save_kwargs (Dict[str, Any]) – a dictionary that will be passed to the save_show_ret function. By default, it is an empty dictionary and the save_show_ret function will use the {“path”: None, “prefix”: ‘scatter’, “dpi”: None, “ext”: ‘pdf’, “transparent”: True, “close”: True, “verbose”: True} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs. Defaults to {}. Defaults to {}.

  • return_data (bool) – whether to return the calculated causality data. Defaults to False.

Raises:

  • ValueError – no preprocessing data in adata.uns

  • ValueError – No layers named as xkey, ykey, or zkey.

  • ValueError – adata does not contain gene data specified in pairs_mat

  • ValueError – n_col * n_row is less than number of gene pairs

Return type:

Optional[DataFrame]

Returns:

None would be returned by default. If return_data is set to be True, the causality data, a DataFrame with columns (“x”: x coordination, “y”: y coordination, “expected_z”: expected z coordination, “pair”: gene pairs) would be returned.