gretapy.pl.links

gretapy.pl.links(mdata, grn, target, tfs, gannot='hg38', w_size=100000, sample_col='celltype', agg_mode='mean', palette=None, expr_cmap=None, **kwargs)

Plot CRE-to-gene links for TFs in a genomic region.

Creates a multi-panel figure showing: - Top panels: Arcs connecting CREs to the target gene TSS for each TF - Middle panel: Gene expression heatmap and chromatin accessibility peaks - Bottom panel: Genomic annotations (genes as arrows)

Parameters:

• mdata – MuData object with ‘rna’ and ‘atac’ modalities. Can be either single-cell data (which will be automatically aggregated by cell type) or pre-computed pseudobulk data. The ‘rna’ modality should have genes as variables, and ‘atac’ should have CREs in format “chr-start-end”.

• grn (DataFrame | dict[str, DataFrame]) – GRN predictions. Either a DataFrame with columns ‘source’ (TF), ‘target’ (gene), ‘cre’, and ‘score’, or a dict mapping GRN names to DataFrames.

• target (str) – Target gene name to plot.

• tfs (list[str]) – List of TF names to plot (one panel per TF).

• gannot (PyRanges | str (default: 'hg38')) – Gene annotations. If a string (e.g., ‘hg38’), reads the Promoters database for that organism using gretapy.ds.read_db. If a PyRanges object, uses it directly. Default is ‘hg38’.

• w_size (int (default: 100000)) – Window size (bp) around target gene TSS. Default is 250000.

• sample_col (str (default: 'celltype')) – Column in mdata.obs containing cell type labels for aggregation. If the column exists, data will be aggregated by cell type using decoupler.get_pseudobulk. Set to None to skip aggregation. Default is ‘celltype’.

• agg_mode (str (default: 'mean')) – Aggregation mode for pseudobulk computation. One of ‘mean’, ‘sum’, or ‘median’. Default is ‘mean’.

• palette (dict[str, str] | None (default: None)) – Color palette mapping GRN names to colors. If None, uses default colors.

• expr_cmap (None | str | list[str] (default: None)) – Colormap for expression heatmap. Default is white to purple.

• **kwargs – Additional arguments passed to decoupler.Plotter (e.g. figsize, dpi, return_fig, save). figsize defaults to (3, auto) and dpi defaults to 125.

Return type:

Figure | None

Returns:

plt.Figure or None Figure if return_fig=True.

Examples

>>> import gretapy as gt
>>> # Load data and generate GRN
>>> mdata, grn = gt.ds.toy()
>>> # Plot links - data is automatically aggregated by cell type
>>> gt.pl.links(mdata, grn, target="CD19", tfs=["PAX5", "EBF1"])
>>> # Plot links for multiple GRNs
>>> grns = {"granie": grn1, "celloracle": grn2}
>>> gt.pl.links(mdata, grns, target="AREG", tfs=["JUND", "FOSL2"])