laris.plotting package#

laris.plotting.plotCCCDotPlot(laris_results: DataFrame, interactions_to_plot: List[str], senders: List[str] | None = None, receivers: List[str] | None = None, sender_receiver_pairs: List[str] | None = None, delimiter_pair: str = '-->', n_top: int = 3000, cmap: str | Colormap | None = None, bubble_size: float = 250, p_value_col: str = 'p_value_fdr', threshold: float = 0.05, filter_by_interaction_score: bool = True, threshold_interaction_score: float = 0.01, filter_significant: bool = True, n_permutations: int = 1000, legend_fontsize: int = 16, show_grid: bool = False, figsize: Tuple[float, float] | None = None, save: str | None = None, verbosity: int = 2, return_fig: bool = False) → Tuple[Figure, Axes] | None#

Create a bubble plot for selected cell type pairs and interactions.

Visualizes interaction strengths between specific sender-receiver cell type pairs using bubbles where size represents -log10(p-value) and color represents interaction score.

Parameters:

laris_results (pd.DataFrame) – DataFrame containing LARIS results
interactions_to_plot (list of str) – List of interaction names to include (e.g., [‘CXCL13::CXCR5’, …])
senders (list of str, optional) – List of sending cell types to plot (used with receivers)
receivers (list of str, optional) – List of receiving cell types (must match length of senders)
sender_receiver_pairs (list of str, optional) – Alternative to senders/receivers. List of pairs in format ‘sender–>receiver’ (or using custom delimiter_pair)
delimiter_pair (str, default='-->') – Delimiter used in sender_receiver_pairs to separate sender and receiver
n_top (int, default=3000) – Number of top interactions if no filters applied
cmap (colormap, optional) – Colormap for bubble colors. If None, uses pos_cmap
bubble_size (float, default=250) – Maximum bubble size for most significant p-values
p_value_col (str, default='p_value_fdr') – Column name for p-value filtering and sizing
threshold (float, default=0.05) – P-value cutoff for significance filtering
filter_by_interaction_score (bool, default=True) – If True, filter by interaction_score > threshold_interaction_score
threshold_interaction_score (float, default=0.01) – Cutoff for interaction score
filter_significant (bool, default=True) – If True, apply significance filtering
n_permutations (int, default=1000) – Number of permutations used (for p-value scaling)
legend_fontsize (int, default=16) – Font size for legend titles (“Interaction Score” and “P value”)
show_grid (bool, default=False) – If True, show grid lines in the plot
figsize (tuple, optional) – Figure size. If None, automatically calculated
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the figure and axes objects

Returns:

(fig, ax) if return_fig=True, otherwise None

Return type:

tuple or None

Examples

>>> # Using senders and receivers
>>> senders = ['B_cell', 'B_cell', 'T_cell']
>>> receivers = ['T_cell', 'Macrophage', 'B_cell']
>>> interactions = ['CXCL13::CXCR5', 'CD40LG::CD40']
>>>
>>> la.pl.plotCCCDotPlot(
...     laris_results,
...     interactions_to_plot=interactions,
...     senders=senders,
...     receivers=receivers,
...     filter_significant=True,
...     legend_fontsize=16,
...     show_grid=False,
...     save='dotplot.pdf'
... )
>>>
>>> # Using sender_receiver_pairs
>>> pairs = ['B_cell-->T_cell', 'B_cell-->Macrophage', 'T_cell-->B_cell']
>>> la.pl.plotCCCDotPlot(
...     laris_results,
...     interactions_to_plot=interactions,
...     sender_receiver_pairs=pairs,
...     save='dotplot.pdf'
... )

Notes

Bubble sizes are scaled by -log10(p_value), providing continuous scaling that better represents the range of significance values. The minimum possible p-value is determined by 1/(n_permutations + 1).

laris.plotting.plotCCCDotPlotFacet(laris_results: DataFrame, cmap: str | Colormap | None = None, bubble_size: float = 400, height_single_panel: float = 4.5, width_single_panel: float = 4.5, x_padding: float = 0.4, y_padding: float = 0.4, n_top: int | None = None, senders: List[str] | None = None, receivers: List[str] | None = None, interactions_to_plot: List[str] | None = None, p_value_col: str = 'p_value_fdr', threshold: float = 0.05, filter_by_interaction_score: bool = True, threshold_interaction_score: float = 0.01, filter_significant: bool = True, n_permutations: int = 1000, ncol: int = 3, facet_by: str = 'sender', legend_fontsize: int = 16, show_grid: bool = True, save: str | None = None, verbosity: int = 2, return_fig: bool = False) → Figure | None#

Create faceted bubble plots organized by sending or receiving cell type.

Generates a grid of bubble plots where each facet represents a different sending or receiving cell type, showing interactions to/from other cell types.

Parameters:

laris_results (pd.DataFrame) – DataFrame containing LARIS interaction results
cmap (colormap, optional) – Colormap for bubble colors. If None, uses pos_cmap
bubble_size (float, default=400) – Maximum bubble size
height_single_panel (float, default=4.5) – Height of each facet panel in inches
width_single_panel (float, default=4.5) – Width of each facet panel in inches
x_padding (float, default=0.4) – Extra space on x-axis
y_padding (float, default=0.4) – Extra space on y-axis
n_top (int, optional) – Number of top interactions if no filters applied
senders (list of str, optional) – Specific sending cell types. If None, all are included
receivers (list of str, optional) – Specific receiving cell types. If None, all are included
interactions_to_plot (list of str, optional) – Specific interactions. If None, all are included
p_value_col (str, default='p_value_fdr') – Column name for p-value filtering
threshold (float, default=0.05) – P-value cutoff for significance
filter_by_interaction_score (bool, default=True) – If True, filter by interaction_score > threshold_interaction_score
threshold_interaction_score (float, default=0.01) – Cutoff for interaction score
filter_significant (bool, default=True) – If True, apply significance filtering
n_permutations (int, default=1000) – Number of permutations (for p-value scaling)
ncol (int, default=3) – Number of columns per row
facet_by (str, default='sender') – How to organize facets: - ‘sender’ : Each facet shows a different sending cell type - ‘receiver’ : Each facet shows a different receiving cell type
legend_fontsize (int, default=16) – Font size for legend titles (“Interaction Score” and “P value”)
show_grid (bool, default=True) – If True, show grid lines in the plots
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the Figure object

Returns:

fig – The Figure object if return_fig=True, otherwise None

Return type:

matplotlib.figure.Figure or None

Examples

>>> # Facet by sender (default)
>>> la.pl.plotCCCDotPlotFacet(
...     laris_results,
...     senders=['B_cell', 'T_cell'],
...     receivers=['Macrophage', 'NK_cell'],
...     interactions_to_plot=['CXCL13::CXCR5', 'CD40LG::CD40'],
...     filter_significant=True,
...     ncol=2,
...     facet_by='sender',
...     show_grid=False,
...     save='facet_plot_sender.pdf'
... )
>>>
>>> # Facet by receiver
>>> la.pl.plotCCCDotPlotFacet(
...     laris_results,
...     senders=['B_cell', 'T_cell'],
...     receivers=['Macrophage', 'NK_cell'],
...     interactions_to_plot=['CXCL13::CXCR5', 'CD40LG::CD40'],
...     filter_significant=True,
...     ncol=2,
...     facet_by='receiver',
...     save='facet_plot_receiver.pdf'
... )

laris.plotting.plotCCCHeatmap(laris_results: DataFrame, cmap: str | Colormap = 'Purples', n_top: int = 3000, figsize: Tuple[float, float] = (6, 5), axis_label_fontsize: int = 16, tick_fontsize: int = 12, cbar_label_fontsize: int = 16, cbar_tick_fontsize: int = 12, filter_significant: bool = True, p_value_col: str = 'p_value_fdr', threshold: float = 0.05, show_borders: bool = True, cluster: bool = False, filter_by_interaction_score: bool = True, threshold_interaction_score: float = 0.01, save: str | None = None, verbosity: int = 2, return_fig: bool = False) → Figure | None#

Create a heatmap showing the number of cell-cell communication interactions.

This function visualizes the frequency of interactions between sending and receiving cell types as a heatmap. It ensures the row and column orders are identical to maintain the self-interaction diagonal.

Parameters:

laris_results (pd.DataFrame) – DataFrame containing LARIS results with columns: - ‘sender’ : str, cell type sending the signal - ‘receiver’ : str, cell type receiving the signal - ‘significant’ : bool (optional), fallback significance flag - p_value_col : str (optional), column name for p-values
cmap (str or matplotlib.colors.Colormap, default='Purples') – Colormap to use for the heatmap (e.g., ‘viridis’, ‘RdBu_r’)
n_top (int, default=3000) – Number of top-ranked interactions to include if no filters are applied
figsize (tuple, default=(6, 5)) – Figure size as (width, height) in inches
axis_label_fontsize (int, default=16) – Font size for axis labels
tick_fontsize (int, default=12) – Font size for tick labels
cbar_label_fontsize (int, default=16) – Font size for colorbar label
cbar_tick_fontsize (int, default=12) – Font size for colorbar tick labels
filter_significant (bool, default=True) – If True, filters interactions based on p_value_col and threshold
p_value_col (str, default='p_value_fdr') – Column name to use for p-value filtering
threshold (float, default=0.05) – P-value cutoff for filtering
show_borders (bool, default=True) – If True, draws light grey border lines between heatmap cells
cluster (bool, default=False) – If True, performs hierarchical clustering on cell types
filter_by_interaction_score (bool, default=True) – If True, filters by interaction_score > threshold_interaction_score
threshold_interaction_score (float, default=0.01) – Cutoff for interaction score filtering
save (str, optional) – Path to save the figure (e.g., ‘heatmap.pdf’). If None, figure is not saved
verbosity (int, default=2) – Verbosity level (0=silent, 1=errors, 2=warnings/info, 3=debug)
return_fig (bool, default=False) – If True, return the figure object instead of just displaying

Returns:

fig – The figure object if return_fig=True, otherwise None

Return type:

matplotlib.figure.Figure or None

Examples

>>> la.pl.plotCCCHeatmap(
...     laris_results,
...     filter_significant=True,
...     cluster=True,
...     save='heatmap.pdf'
... )

laris.plotting.plotCCCNetwork(laris_results: DataFrame, cell_type_of_interest: str, interaction_direction: str = 'sending', adata: AnnData | None = None, n_top: int = 3000, edge_width_scale: float = 30, interaction_cutoff: float = 0.0, groupby: str = 'cell_type', cell_type_color_key: str = 'cell_type_colors', custom_color_mapping: dict | None = None, figsize: Tuple[float, float] = (12, 10), margins: float = 0.2, label_font_size: int = 16, node_size: int = 1100, p_value_col: str = 'p_value_fdr', threshold: float = 0.05, filter_by_interaction_score: bool = True, threshold_interaction_score: float = 0.01, filter_significant: bool = True, label_border: bool = True, label_border_color: str = 'white', label_border_width: float = 3.0, save: str | None = None, verbosity: int = 2, return_fig: bool = False) → Tuple[Figure, Axes] | None#

Plot an interaction network for a specific cell type.

Creates a directed network graph showing aggregated interactions where a specific cell type is either sending or receiving signals. Edge thickness represents the cumulative interaction strength.

Parameters:

laris_results (pd.DataFrame) – DataFrame containing LARIS results
cell_type_of_interest (str) – Cell type to focus on (e.g., “B_cell”, “T_cell”)
interaction_direction ({'sending', 'receiving'}, default='sending') – Direction to filter: - ‘sending’ : Show outgoing interactions from cell_type_of_interest - ‘receiving’ : Show incoming interactions to cell_type_of_interest
adata (anndata.AnnData, optional) – AnnData object containing cell type information for coloring nodes
n_top (int, default=3000) – Number of top interactions if no filters applied
edge_width_scale (float, default=30) – Scaling factor for edge thickness based on interaction score
interaction_cutoff (float, default=0.0) – Minimum interaction score threshold
groupby (str, default='cell_type') – Column name in adata.obs containing cell type labels
cell_type_color_key (str, default='cell_type_colors') – Key in adata.uns containing cell type colors
custom_color_mapping (dict, optional) – Custom mapping of cell types to colors
figsize (tuple, default=(12, 10)) – Figure size in inches
margins (float, default=0.2) – Margin space around the plot
label_font_size (int, default=16) – Font size for node labels
node_size (int, default=1100) – Size of network nodes
p_value_col (str, default='p_value_fdr') – Column name for p-value filtering
threshold (float, default=0.05) – P-value cutoff for significance
filter_by_interaction_score (bool, default=True) – If True, filter by interaction_score > threshold_interaction_score
threshold_interaction_score (float, default=0.01) – Cutoff for interaction score
filter_significant (bool, default=True) – If True, apply significance filtering
label_border (bool, default=True) – If True, add border/outline to cell type labels for better visibility
label_border_color (str, default='white') – Color of the label border/outline
label_border_width (float, default=3.0) – Width of the label border/outline
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the figure and axes objects

Returns:

(fig, ax) if return_fig=True, otherwise None

Return type:

tuple or None

Examples

>>> la.pl.plotCCCNetwork(
...     laris_results,
...     cell_type_of_interest='B_cell',
...     interaction_direction='sending',
...     adata=adata,
...     filter_significant=True,
...     label_border=True,
...     label_border_width=4.0,
...     save='network.pdf'
... )

laris.plotting.plotCCCNetworkCumulative(laris_results: DataFrame, adata: AnnData, cutoff: float = 0, n_top: int = 3000, groupby: str = 'cell_type', cell_type_color_key: str = 'cell_type_colors', custom_color_mapping: dict | None = None, figsize: Tuple[float, float] = (12, 10), margins: float = 0.2, label_font_size: int = 16, node_size: int = 1100, edge_width_scale: float = 5, p_value_col: str = 'p_value_fdr', threshold: float = 0.05, filter_by_interaction_score: bool = True, threshold_interaction_score: float = 0.01, filter_significant: bool = True, edge_thickness_by_numbers: bool = False, total_edge_thickness: float = 100, label_border: bool = True, label_border_color: str = 'white', label_border_width: float = 3.0, save: str | None = None, verbosity: int = 2, return_fig: bool = False) → Tuple[Figure, Axes] | None#

Plot a cumulative interaction network across all cell types.

Creates a comprehensive network showing aggregated interactions between all cell type pairs. Edge thickness can represent either cumulative interaction scores or total interaction counts.

Parameters:

laris_results (pd.DataFrame) – DataFrame containing LARIS interaction results
adata (anndata.AnnData) – AnnData object with cell type information
cutoff (float, default=0) – Minimum threshold for including an edge
n_top (int, default=3000) – Number of top interactions if no filters applied
groupby (str, default='cell_type') – Column in adata.obs containing cell type labels
cell_type_color_key (str, default='cell_type_colors') – Key in adata.uns for cell type colors
custom_color_mapping (dict, optional) – Custom cell type to color mapping
figsize (tuple, default=(12, 10)) – Figure dimensions in inches
margins (float, default=0.2) – Plot margin size
label_font_size (int, default=16) – Font size for node labels
node_size (int, default=1100) – Size of network nodes
edge_width_scale (float, default=5) – Scaling factor for edge thickness (when using scores)
p_value_col (str, default='p_value_fdr') – Column name for p-value filtering
threshold (float, default=0.05) – P-value cutoff for significance
filter_by_interaction_score (bool, default=True) – If True, filter by interaction_score > threshold_interaction_score
threshold_interaction_score (float, default=0.01) – Cutoff for interaction score
filter_significant (bool, default=True) – If True, apply significance filtering
edge_thickness_by_numbers (bool, default=False) – If True, edge thickness represents interaction count
total_edge_thickness (float, default=100) – Total thickness budget when edge_thickness_by_numbers=True
label_border (bool, default=True) – If True, add border/outline to cell type labels for better visibility
label_border_color (str, default='white') – Color of the label border/outline
label_border_width (float, default=3.0) – Width of the label border/outline
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the figure and axes objects

Returns:

(fig, ax) if return_fig=True, otherwise None

Return type:

tuple or None

Examples

>>> la.pl.plotCCCNetworkCumulative(
...     laris_results,
...     adata=adata,
...     filter_significant=True,
...     label_border=True,
...     label_border_color='white',
...     label_border_width=4.0,
...     save='cumulative_network.pdf'
... )

laris.plotting.plotCCCSpatial(lr_adata: AnnData, basis: str, interaction: str, cell_type: str, selected_cell_types: List[str] | None = None, highlight_all_expressing: bool = False, background_color: str = 'lightgrey', colors: List[str] | None = None, size: float = 120, fig_width: float | None = 6, fig_height: float | None = None, max_title_chars: int = 60, save: str | None = None, verbosity: int = 2, return_fig: bool = False) → Figure | None#

Plot spatial distribution of ligand-receptor interactions.

Creates a spatial plot highlighting cells expressing a specific interaction, with options to highlight specific cell types or all expressing cells.

Parameters:

lr_adata (anndata.AnnData) – AnnData object containing LR interaction scores and spatial coordinates
basis (str) – Key for spatial coordinates in lr_adata.obsm
interaction (str) – Interaction name to visualize (must be in lr_adata.var_names)
cell_type (str) – Column name in lr_adata.obs containing cell type annotations
selected_cell_types (list of str, optional) – Specific cell types to highlight
highlight_all_expressing (bool, default=False) – If True, highlight all cells expressing the interaction
background_color (str, default='lightgrey') – Color for non-expressing cells
colors (list of str, optional) – Colors for selected cell types
size (float, default=120) – Point size for spatial plot
fig_width (float, default=6) – Figure width in inches. Height is calculated to maintain data aspect ratio
fig_height (float, optional) – Figure height in inches. If provided, overrides aspect ratio calculation
max_title_chars (int, default=60) – Maximum characters per line in title before wrapping
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the figure object

Returns:

The figure object if return_fig=True, otherwise None

Return type:

fig or None

Examples

>>> la.pl.plotCCCSpatial(
...     lr_adata,
...     basis='X_spatial',
...     interaction='CXCL13::CXCR5',
...     cell_type='cell_type',
...     selected_cell_types=['B_cell', 'T_cell'],
...     colors=['green', 'orange'],
...     fig_width=10,
...     save='spatial.pdf'
... )

laris.plotting.plotLRDotPlot(adata_dotplot: AnnData, interactions_to_plot: List[str], groupby: str, delimiter: str = '::', cmap_interaction: str = 'Spectral_r', cmap_ligand: str = 'Blues', cmap_receptor: str = 'Purples', standard_scale_interaction: str | None = 'var', standard_scale_ligand: str | None = 'var', standard_scale_receptor: str | None = 'var', orientation: str = 'horizontal', row_height: float | None = None, max_height: float | None = None, figsize: Tuple[float, float] | None = None, save: str | None = None, verbosity: int = 2, return_fig: bool = False) → Tuple[Figure, ndarray] | None#

Create three side-by-side (or stacked) dot plots for LR pairs, ligands, and receptors.

Visualizes expression patterns of ligand-receptor pairs alongside individual ligand and receptor expression across cell types.

Parameters:

adata_dotplot (anndata.AnnData) – AnnData object prepared with prepareDotPlotAdata() containing both LR pair scores and individual gene expression
interactions_to_plot (list of str) – List of LR pairs in format ‘ligand::receptor’ (or using custom delimiter)
groupby (str) – Column in adata_dotplot.obs to group by
delimiter (str, default='::') – Delimiter used to separate ligand and receptor in interaction names
cmap_interaction (str, default='Spectral_r') – Colormap for the LR interaction scores plot
cmap_ligand (str, default='Blues') – Colormap for the ligand expression plot
cmap_receptor (str, default='Purples') – Colormap for the receptor expression plot
standard_scale_interaction (str or None, default='var') – Scaling method for interaction scores plot (‘var’, ‘group’, or None)
standard_scale_ligand (str or None, default='var') – Scaling method for ligand expression plot (‘var’, ‘group’, or None)
standard_scale_receptor (str or None, default='var') – Scaling method for receptor expression plot (‘var’, ‘group’, or None)
orientation (str, default='horizontal') – Layout orientation: ‘horizontal’ for side-by-side, ‘vertical’ for stacked
row_height (float, optional) – Height per interaction row in inches
max_height (float, optional) – Maximum figure height in inches
figsize (tuple, optional) – Overall figure size (width, height). Overrides row_height if provided
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the figure and axes objects

Returns:

(fig, axes) if return_fig=True, otherwise None

Return type:

tuple or None

Examples

>>> adata_combined = la.pl.prepareDotPlotAdata(lr_adata, adata)
>>> la.pl.plotLRDotPlot(
...     adata_combined,
...     interactions_to_plot=['CXCL13::CXCR5', 'CD40LG::CD40'],
...     groupby='cell_type',
...     delimiter='::',
...     orientation='vertical',
...     standard_scale_interaction='var',
...     standard_scale_ligand=None,
...     save='lr_dotplot.pdf'
... )

laris.plotting.prepareDotPlotAdata(lr_adata: AnnData, adata: AnnData, verbosity: int = 2) → AnnData#

Prepare combined AnnData for dot plot visualizations.

Concatenates LR interaction scores with original gene expression data horizontally to create a unified AnnData object for plotting.

Parameters:

lr_adata (anndata.AnnData) – AnnData object containing LR interaction scores
adata (anndata.AnnData) – Original AnnData object containing gene expression data
verbosity (int, default=2) – Verbosity level

Returns:

adata_dotplot – Combined AnnData object

Return type:

anndata.AnnData

Examples

>>> adata_combined = la.pl.prepareDotPlotAdata(lr_adata, adata)
>>> la.pl.plotLRDotPlot(adata_combined, interactions, groupby='cell_type')

Create a heatmap showing the number of cell-cell communication interactions.

Parameters:

laris_results (pd.DataFrame) – DataFrame containing LARIS results with columns: - ‘sender’ : str, cell type sending the signal - ‘receiver’ : str, cell type receiving the signal - ‘significant’ : bool (optional), fallback significance flag - p_value_col : str (optional), column name for p-values
cmap (str or matplotlib.colors.Colormap, default='Purples') – Colormap to use for the heatmap (e.g., ‘viridis’, ‘RdBu_r’)
n_top (int, default=3000) – Number of top-ranked interactions to include if no filters are applied
figsize (tuple, default=(6, 5)) – Figure size as (width, height) in inches
axis_label_fontsize (int, default=16) – Font size for axis labels
tick_fontsize (int, default=12) – Font size for tick labels
cbar_label_fontsize (int, default=16) – Font size for colorbar label
cbar_tick_fontsize (int, default=12) – Font size for colorbar tick labels
filter_significant (bool, default=True) – If True, filters interactions based on p_value_col and threshold
p_value_col (str, default='p_value_fdr') – Column name to use for p-value filtering
threshold (float, default=0.05) – P-value cutoff for filtering
show_borders (bool, default=True) – If True, draws light grey border lines between heatmap cells
cluster (bool, default=False) – If True, performs hierarchical clustering on cell types
filter_by_interaction_score (bool, default=True) – If True, filters by interaction_score > threshold_interaction_score
threshold_interaction_score (float, default=0.01) – Cutoff for interaction score filtering
save (str, optional) – Path to save the figure (e.g., ‘heatmap.pdf’). If None, figure is not saved
verbosity (int, default=2) – Verbosity level (0=silent, 1=errors, 2=warnings/info, 3=debug)
return_fig (bool, default=False) – If True, return the figure object instead of just displaying

Returns:

fig – The figure object if return_fig=True, otherwise None

Return type:

matplotlib.figure.Figure or None

Examples

>>> la.pl.plotCCCHeatmap(
...     laris_results,
...     filter_significant=True,
...     cluster=True,
...     save='heatmap.pdf'
... )

Plot an interaction network for a specific cell type.

Creates a directed network graph showing aggregated interactions where a specific cell type is either sending or receiving signals. Edge thickness represents the cumulative interaction strength.

Parameters:

laris_results (pd.DataFrame) – DataFrame containing LARIS results
cell_type_of_interest (str) – Cell type to focus on (e.g., “B_cell”, “T_cell”)
interaction_direction ({'sending', 'receiving'}, default='sending') – Direction to filter: - ‘sending’ : Show outgoing interactions from cell_type_of_interest - ‘receiving’ : Show incoming interactions to cell_type_of_interest
adata (anndata.AnnData, optional) – AnnData object containing cell type information for coloring nodes
n_top (int, default=3000) – Number of top interactions if no filters applied
edge_width_scale (float, default=30) – Scaling factor for edge thickness based on interaction score
interaction_cutoff (float, default=0.0) – Minimum interaction score threshold
groupby (str, default='cell_type') – Column name in adata.obs containing cell type labels
cell_type_color_key (str, default='cell_type_colors') – Key in adata.uns containing cell type colors
custom_color_mapping (dict, optional) – Custom mapping of cell types to colors
figsize (tuple, default=(12, 10)) – Figure size in inches
margins (float, default=0.2) – Margin space around the plot
label_font_size (int, default=16) – Font size for node labels
node_size (int, default=1100) – Size of network nodes
p_value_col (str, default='p_value_fdr') – Column name for p-value filtering
threshold (float, default=0.05) – P-value cutoff for significance
filter_by_interaction_score (bool, default=True) – If True, filter by interaction_score > threshold_interaction_score
threshold_interaction_score (float, default=0.01) – Cutoff for interaction score
filter_significant (bool, default=True) – If True, apply significance filtering
label_border (bool, default=True) – If True, add border/outline to cell type labels for better visibility
label_border_color (str, default='white') – Color of the label border/outline
label_border_width (float, default=3.0) – Width of the label border/outline
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the figure and axes objects

Returns:

(fig, ax) if return_fig=True, otherwise None

Return type:

tuple or None

Examples

>>> la.pl.plotCCCNetwork(
...     laris_results,
...     cell_type_of_interest='B_cell',
...     interaction_direction='sending',
...     adata=adata,
...     filter_significant=True,
...     label_border=True,
...     label_border_width=4.0,
...     save='network.pdf'
... )

Plot a cumulative interaction network across all cell types.

Creates a comprehensive network showing aggregated interactions between all cell type pairs. Edge thickness can represent either cumulative interaction scores or total interaction counts.

Parameters:

laris_results (pd.DataFrame) – DataFrame containing LARIS interaction results
adata (anndata.AnnData) – AnnData object with cell type information
cutoff (float, default=0) – Minimum threshold for including an edge
n_top (int, default=3000) – Number of top interactions if no filters applied
groupby (str, default='cell_type') – Column in adata.obs containing cell type labels
cell_type_color_key (str, default='cell_type_colors') – Key in adata.uns for cell type colors
custom_color_mapping (dict, optional) – Custom cell type to color mapping
figsize (tuple, default=(12, 10)) – Figure dimensions in inches
margins (float, default=0.2) – Plot margin size
label_font_size (int, default=16) – Font size for node labels
node_size (int, default=1100) – Size of network nodes
edge_width_scale (float, default=5) – Scaling factor for edge thickness (when using scores)
p_value_col (str, default='p_value_fdr') – Column name for p-value filtering
threshold (float, default=0.05) – P-value cutoff for significance
filter_by_interaction_score (bool, default=True) – If True, filter by interaction_score > threshold_interaction_score
threshold_interaction_score (float, default=0.01) – Cutoff for interaction score
filter_significant (bool, default=True) – If True, apply significance filtering
edge_thickness_by_numbers (bool, default=False) – If True, edge thickness represents interaction count
total_edge_thickness (float, default=100) – Total thickness budget when edge_thickness_by_numbers=True
label_border (bool, default=True) – If True, add border/outline to cell type labels for better visibility
label_border_color (str, default='white') – Color of the label border/outline
label_border_width (float, default=3.0) – Width of the label border/outline
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the figure and axes objects

Returns:

(fig, ax) if return_fig=True, otherwise None

Return type:

tuple or None

Examples

>>> la.pl.plotCCCNetworkCumulative(
...     laris_results,
...     adata=adata,
...     filter_significant=True,
...     label_border=True,
...     label_border_color='white',
...     label_border_width=4.0,
...     save='cumulative_network.pdf'
... )

Create a bubble plot for selected cell type pairs and interactions.

Visualizes interaction strengths between specific sender-receiver cell type pairs using bubbles where size represents -log10(p-value) and color represents interaction score.

Parameters:

laris_results (pd.DataFrame) – DataFrame containing LARIS results
interactions_to_plot (list of str) – List of interaction names to include (e.g., [‘CXCL13::CXCR5’, …])
senders (list of str, optional) – List of sending cell types to plot (used with receivers)
receivers (list of str, optional) – List of receiving cell types (must match length of senders)
sender_receiver_pairs (list of str, optional) – Alternative to senders/receivers. List of pairs in format ‘sender–>receiver’ (or using custom delimiter_pair)
delimiter_pair (str, default='-->') – Delimiter used in sender_receiver_pairs to separate sender and receiver
n_top (int, default=3000) – Number of top interactions if no filters applied
cmap (colormap, optional) – Colormap for bubble colors. If None, uses pos_cmap
bubble_size (float, default=250) – Maximum bubble size for most significant p-values
p_value_col (str, default='p_value_fdr') – Column name for p-value filtering and sizing
threshold (float, default=0.05) – P-value cutoff for significance filtering
filter_by_interaction_score (bool, default=True) – If True, filter by interaction_score > threshold_interaction_score
threshold_interaction_score (float, default=0.01) – Cutoff for interaction score
filter_significant (bool, default=True) – If True, apply significance filtering
n_permutations (int, default=1000) – Number of permutations used (for p-value scaling)
legend_fontsize (int, default=16) – Font size for legend titles (“Interaction Score” and “P value”)
show_grid (bool, default=False) – If True, show grid lines in the plot
figsize (tuple, optional) – Figure size. If None, automatically calculated
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the figure and axes objects

Returns:

(fig, ax) if return_fig=True, otherwise None

Return type:

tuple or None

Examples

>>> # Using senders and receivers
>>> senders = ['B_cell', 'B_cell', 'T_cell']
>>> receivers = ['T_cell', 'Macrophage', 'B_cell']
>>> interactions = ['CXCL13::CXCR5', 'CD40LG::CD40']
>>>
>>> la.pl.plotCCCDotPlot(
...     laris_results,
...     interactions_to_plot=interactions,
...     senders=senders,
...     receivers=receivers,
...     filter_significant=True,
...     legend_fontsize=16,
...     show_grid=False,
...     save='dotplot.pdf'
... )
>>>
>>> # Using sender_receiver_pairs
>>> pairs = ['B_cell-->T_cell', 'B_cell-->Macrophage', 'T_cell-->B_cell']
>>> la.pl.plotCCCDotPlot(
...     laris_results,
...     interactions_to_plot=interactions,
...     sender_receiver_pairs=pairs,
...     save='dotplot.pdf'
... )

Notes

Bubble sizes are scaled by -log10(p_value), providing continuous scaling that better represents the range of significance values. The minimum possible p-value is determined by 1/(n_permutations + 1).

Create faceted bubble plots organized by sending or receiving cell type.

Generates a grid of bubble plots where each facet represents a different sending or receiving cell type, showing interactions to/from other cell types.

Parameters:

laris_results (pd.DataFrame) – DataFrame containing LARIS interaction results
cmap (colormap, optional) – Colormap for bubble colors. If None, uses pos_cmap
bubble_size (float, default=400) – Maximum bubble size
height_single_panel (float, default=4.5) – Height of each facet panel in inches
width_single_panel (float, default=4.5) – Width of each facet panel in inches
x_padding (float, default=0.4) – Extra space on x-axis
y_padding (float, default=0.4) – Extra space on y-axis
n_top (int, optional) – Number of top interactions if no filters applied
senders (list of str, optional) – Specific sending cell types. If None, all are included
receivers (list of str, optional) – Specific receiving cell types. If None, all are included
interactions_to_plot (list of str, optional) – Specific interactions. If None, all are included
p_value_col (str, default='p_value_fdr') – Column name for p-value filtering
threshold (float, default=0.05) – P-value cutoff for significance
filter_by_interaction_score (bool, default=True) – If True, filter by interaction_score > threshold_interaction_score
threshold_interaction_score (float, default=0.01) – Cutoff for interaction score
filter_significant (bool, default=True) – If True, apply significance filtering
n_permutations (int, default=1000) – Number of permutations (for p-value scaling)
ncol (int, default=3) – Number of columns per row
facet_by (str, default='sender') – How to organize facets: - ‘sender’ : Each facet shows a different sending cell type - ‘receiver’ : Each facet shows a different receiving cell type
legend_fontsize (int, default=16) – Font size for legend titles (“Interaction Score” and “P value”)
show_grid (bool, default=True) – If True, show grid lines in the plots
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the Figure object

Returns:

fig – The Figure object if return_fig=True, otherwise None

Return type:

matplotlib.figure.Figure or None

Examples

>>> # Facet by sender (default)
>>> la.pl.plotCCCDotPlotFacet(
...     laris_results,
...     senders=['B_cell', 'T_cell'],
...     receivers=['Macrophage', 'NK_cell'],
...     interactions_to_plot=['CXCL13::CXCR5', 'CD40LG::CD40'],
...     filter_significant=True,
...     ncol=2,
...     facet_by='sender',
...     show_grid=False,
...     save='facet_plot_sender.pdf'
... )
>>>
>>> # Facet by receiver
>>> la.pl.plotCCCDotPlotFacet(
...     laris_results,
...     senders=['B_cell', 'T_cell'],
...     receivers=['Macrophage', 'NK_cell'],
...     interactions_to_plot=['CXCL13::CXCR5', 'CD40LG::CD40'],
...     filter_significant=True,
...     ncol=2,
...     facet_by='receiver',
...     save='facet_plot_receiver.pdf'
... )

Create three side-by-side (or stacked) dot plots for LR pairs, ligands, and receptors.

Visualizes expression patterns of ligand-receptor pairs alongside individual ligand and receptor expression across cell types.

Parameters:

adata_dotplot (anndata.AnnData) – AnnData object prepared with prepareDotPlotAdata() containing both LR pair scores and individual gene expression
interactions_to_plot (list of str) – List of LR pairs in format ‘ligand::receptor’ (or using custom delimiter)
groupby (str) – Column in adata_dotplot.obs to group by
delimiter (str, default='::') – Delimiter used to separate ligand and receptor in interaction names
cmap_interaction (str, default='Spectral_r') – Colormap for the LR interaction scores plot
cmap_ligand (str, default='Blues') – Colormap for the ligand expression plot
cmap_receptor (str, default='Purples') – Colormap for the receptor expression plot
standard_scale_interaction (str or None, default='var') – Scaling method for interaction scores plot (‘var’, ‘group’, or None)
standard_scale_ligand (str or None, default='var') – Scaling method for ligand expression plot (‘var’, ‘group’, or None)
standard_scale_receptor (str or None, default='var') – Scaling method for receptor expression plot (‘var’, ‘group’, or None)
orientation (str, default='horizontal') – Layout orientation: ‘horizontal’ for side-by-side, ‘vertical’ for stacked
row_height (float, optional) – Height per interaction row in inches
max_height (float, optional) – Maximum figure height in inches
figsize (tuple, optional) – Overall figure size (width, height). Overrides row_height if provided
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the figure and axes objects

Returns:

(fig, axes) if return_fig=True, otherwise None

Return type:

tuple or None

Examples

>>> adata_combined = la.pl.prepareDotPlotAdata(lr_adata, adata)
>>> la.pl.plotLRDotPlot(
...     adata_combined,
...     interactions_to_plot=['CXCL13::CXCR5', 'CD40LG::CD40'],
...     groupby='cell_type',
...     delimiter='::',
...     orientation='vertical',
...     standard_scale_interaction='var',
...     standard_scale_ligand=None,
...     save='lr_dotplot.pdf'
... )

Plot spatial distribution of ligand-receptor interactions.

Creates a spatial plot highlighting cells expressing a specific interaction, with options to highlight specific cell types or all expressing cells.

Parameters:

lr_adata (anndata.AnnData) – AnnData object containing LR interaction scores and spatial coordinates
basis (str) – Key for spatial coordinates in lr_adata.obsm
interaction (str) – Interaction name to visualize (must be in lr_adata.var_names)
cell_type (str) – Column name in lr_adata.obs containing cell type annotations
selected_cell_types (list of str, optional) – Specific cell types to highlight
highlight_all_expressing (bool, default=False) – If True, highlight all cells expressing the interaction
background_color (str, default='lightgrey') – Color for non-expressing cells
colors (list of str, optional) – Colors for selected cell types
size (float, default=120) – Point size for spatial plot
fig_width (float, default=6) – Figure width in inches. Height is calculated to maintain data aspect ratio
fig_height (float, optional) – Figure height in inches. If provided, overrides aspect ratio calculation
max_title_chars (int, default=60) – Maximum characters per line in title before wrapping
save (str, optional) – Path to save figure
verbosity (int, default=2) – Verbosity level
return_fig (bool, default=False) – If True, return the figure object

Returns:

The figure object if return_fig=True, otherwise None

Return type:

fig or None

Examples

>>> la.pl.plotCCCSpatial(
...     lr_adata,
...     basis='X_spatial',
...     interaction='CXCL13::CXCR5',
...     cell_type='cell_type',
...     selected_cell_types=['B_cell', 'T_cell'],
...     colors=['green', 'orange'],
...     fig_width=10,
...     save='spatial.pdf'
... )

laris.plotting.prepareDotPlotAdata(lr_adata: AnnData, adata: AnnData, verbosity: int = 2) → AnnData#

Prepare combined AnnData for dot plot visualizations.

Concatenates LR interaction scores with original gene expression data horizontally to create a unified AnnData object for plotting.

Parameters:

lr_adata (anndata.AnnData) – AnnData object containing LR interaction scores
adata (anndata.AnnData) – Original AnnData object containing gene expression data
verbosity (int, default=2) – Verbosity level

Returns:

adata_dotplot – Combined AnnData object

Return type:

anndata.AnnData

Examples

>>> adata_combined = la.pl.prepareDotPlotAdata(lr_adata, adata)
>>> la.pl.plotLRDotPlot(adata_combined, interactions, groupby='cell_type')

Table of Contents

laris.plotting package#