Plotting

mc_astra.pl.plot_view_samples(anndata_dict, min_samples, table=False, figsize=(5, 5), dpi=100, ax=None, return_fig=False, **kwargs)

Quality control plot to assess the quality of the obtained pseudobulk samples.

Parameters:

Name	Type	Description	Default
anndata_dict	dict[str, AnnData]	Dictionary mapping view names to AnnData objects.	required
min_samples	int	Minimum number of samples required for a view to be included.	required
table	bool	Whether to return the underlying summary table instead of plotting. Default is False.	False
figsize	tuple[int, int]	Size of the figure in inches. Default is (5, 5).	(5, 5)
dpi	int	Resolution of the figure in dots per inch. Default is 100.	100
ax	Axes or None	Matplotlib Axes object to plot on. If None, a new figure and axes are created.	None
return_fig	bool	Whether to return the Figure object. Default is False.	False
**kwargs	dict	Additional keyword arguments passed to seaborn.scatterplot.	{}

Returns:

Name	Type	Description
fig	Figure or None	The created Figure object if return_fig is True, otherwise None.

mc_astra.pl.plot_view_genes(anndata_dict, min_genes, table=False, figsize=(5, 5), dpi=100, ax=None, return_fig=False, **kwargs)

Quality control plot to assess the quality of the obtained pseudobulk samples.

Parameters:

Name	Type	Description	Default
anndata_dict	dict[str, AnnData]	Dictionary mapping view names to AnnData objects.	required
min_genes	int	Minimum number of genes required for a view to be included.	required
table	bool	Whether to return the underlying summary table instead of plotting. Default is False.	False
figsize	tuple[int, int]	Size of the figure in inches. Default is (5, 5).	(5, 5)
dpi	int	Resolution of the figure in dots per inch. Default is 100.	100
ax	Axes or None	Matplotlib Axes object to plot on. If None, a new figure and axes are created.	None
return_fig	bool	Whether to return the Figure object. Default is False.	False
**kwargs	dict	Additional keyword arguments passed to seaborn.scatterplot.	{}

Returns:

Name	Type	Description
fig	Figure or None	The created Figure object if return_fig is True, otherwise None.

mc_astra.pl.plot_sample_coverage(anndata_dict, threshold, proportion, table=False, figsize=(5, 5), dpi=100, return_fig=False, **kwargs)

Visualize sample coverage for each AnnData view.

Samples below the requested proportion threshold are highlighted. One figure is produced per dictionary key.

Parameters:

Name	Type	Description	Default
anndata_dict	dict[str, AnnData]	Dictionary mapping view names to AnnData objects.	required
threshold	float or dict[str, float]	Gene expression threshold. If a dict, must contain all keys of anndata_dict.	required
proportion	float or dict[str, float]	Minimum proportion of genes above threshold. If a dict, must contain all keys.	required
table	bool	If True, return summary tables instead of plotting. Default is False.	False
figsize	tuple[int, int]	Figure size per subplot. Default is (5, 5).	(5, 5)
dpi	int	Figure resolution in dots per inch. Default is 100.	100
return_fig	bool	If True, return the generated Figure objects. Default is False.	False
**kwargs	dict	Additional keyword arguments passed to matplotlib.axes.Axes.scatter.	{}

Returns:

Type	Description
dict[str, DataFrame] or dict[str, Figure] or None	Summary tables if table is True, figures if return_fig is True, otherwise None.

mc_astra.pl.plot_pval_tiles(p_df: pd.DataFrame, star_threshold: float = 0.05, ax=None, title: str | None = None)

Create a tile plot of -log10(p) values.

Parameters:

Name	Type	Description	Default
p_df	DataFrame	DataFrame of p-values with rows and columns defining the tile grid.	required
star_threshold	float	P-value threshold for star annotation. Default is 0.05.	0.05
ax	Axes or None	Axes to draw on. If None, a new figure and axes are created.	None
title	str or None	Optional title for the plot.	None

Returns:

Name	Type	Description
axes	Axes or tuple[Figure, Axes]	Existing axes when ax is provided, otherwise the created figure and axes.

mc_astra.pl.plot_mcell_funcomics(result_dict: dict[str, dict[str, pd.DataFrame]], result_key: str = 'pw_acts', pval_key: str = 'pw_padj', p_threshold: float = 0.05, top_n: int = 10, cmap: str = 'coolwarm', figsize: tuple = (14, 5), ytick_rotation: int = 0, use_var: bool = False, share_color_scale: bool = True, center: float | None = 0.0)

Plot grouped heatmaps per view using a selected result matrix.

Features are filtered by adjusted p-value and ranked either by mean absolute value or variance.

Parameters:

Name	Type	Description	Default
result_dict	dict[str, dict[str, DataFrame]]	Output of run_ulm_per_view with one entry per view.	required
result_key	str	Key within each view result containing values to plot.	'pw_acts'
pval_key	str	Key within each view result containing adjusted p-values.	'pw_padj'
p_threshold	float	Adjusted p-value significance threshold.	0.05
top_n	int	Number of top significant features per view to display.	10
cmap	str	Colormap for the heatmaps.	'coolwarm'
figsize	tuple[int, int]	Overall figure size.	(14, 5)
ytick_rotation	int	Rotation angle for y-axis tick labels.	0
use_var	bool	If True, rank features by variance instead of mean absolute value.	False
share_color_scale	bool	Whether all heatmaps use a shared color scale.	True
center	float or None	Center value for diverging color scaling. If None, no center is used.	0.0

Returns:

Type	Description
None	The function displays the plot and does not return an object.

mc_astra.pl.plot_mcell_network(df: pd.DataFrame, weight_col: str = 'coef', abs_cutoff: float = 0.0, keep_negative: bool = True, edge_width_range: tuple = (0.8, 6), node_size: int = 1100, arrowsize: int = 18, reciprocal_curvature: float = 0.25, default_curvature: float = 0.04, positive_color: str = 'tab:purple', negative_color: str = 'tab:red', show_edge_labels: bool = False, label_fmt: str = '{:.2f}', title: str | None = None, save_path: str | None = None, edge_margin_factor: float = 0.55, arrows_on_top: bool = True)

Plot an inferred multicellular information network.

The results are shown solely from one subset (positive or negative loadings).

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame defining directed edges. Must contain at least source, target, and edge weight columns.	required
weight_col	str	Column name containing edge weights. Default is "coef".	'coef'
abs_cutoff	float	Minimum absolute weight required to keep an edge.	0.0
keep_negative	bool	Whether to retain negatively weighted edges.	True
edge_width_range	tuple[float, float]	Minimum and maximum edge widths used for scaling.	(0.8, 6)
node_size	int	Size of network nodes.	1100
arrowsize	int	Size of arrow heads.	18
reciprocal_curvature	float	Curvature used for reciprocal edges.	0.25
default_curvature	float	Curvature used for non-reciprocal edges.	0.04
positive_color	str	Color for positively weighted edges.	'tab:purple'
negative_color	str	Color for negatively weighted edges.	'tab:red'
show_edge_labels	bool	Whether to display edge weight labels.	False
label_fmt	str	Format string used for edge labels.	'{:.2f}'
title	str or None	Optional plot title.	None
save_path	str or None	If provided, save the figure to this path.	None
edge_margin_factor	float	Factor controlling spacing between nodes and edges.	0.55
arrows_on_top	bool	Whether arrows are drawn above nodes.	True

Returns:

Name	Type	Description
graph	DiGraph	Directed graph built from the filtered network table.

mc_astra.pl.plot_features_per_view(df_dict: dict[str, pd.DataFrame], features: list[str], cmap: str = 'coolwarm', figsize: tuple[int, int] = (14, 5), ytick_rotation: int = 0, xtick_rotation: int = 90, share_color_scale: bool = True, center: float | None = 0.0)

Plot grouped heatmaps for selected features across multiple views.

Each entry in df_dict is a dataframe for one view, with rows as samples and columns as features. For each view, only the requested features present in the dataframe are plotted.

Parameters:

Name	Type	Description	Default
df_dict	dict[str, DataFrame]	Dictionary mapping view names to sample-by-feature matrices.	required
features	list[str]	Feature names to plot in each view when present.	required
cmap	str	Matplotlib colormap name.	'coolwarm'
figsize	tuple[int, int]	Overall figure size.	(14, 5)
ytick_rotation	int	Rotation angle for y-axis tick labels.	0
xtick_rotation	int	Rotation angle for x-axis tick labels.	90
share_color_scale	bool	Whether all heatmaps use a shared color scale.	True
center	float or None	Center value for diverging color scaling. If None, no center is used.	0.0

Returns:

Type	Description
None	The function displays the plot and does not return an object.

mc_astra.pl.plot_comm_overview(plot_df, tile_width=0.6, tile_height=0.6, text_size=5, figsize=None, source_label='source', target_label='target', ax=None)

Plot ligand-receptor coherent interactions as source/target tiles.

Parameters:

Name	Type	Description	Default
plot_df	DataFrame	Output from generate_lr_plot_df.	required
tile_width	float	Width of each rectangular tile.	0.6
tile_height	float	Height of each rectangular tile.	0.6
text_size	float	Font size of + / - labels inside tiles.	5
figsize	tuple or None	Matplotlib figure size. If None, size is inferred from data dimensions.	None
source_label	str	Label for source side of x-axis.	'source'
target_label	str	Label for target side of x-axis.	'target'
ax	Axes or None	Existing axis to plot into.	None

Returns:

Name	Type	Description
fig	Figure	Figure containing the communication overview.
ax	Axes	Axes containing the communication overview.

mc_astra.pl.plot_interaction_tileplot(df: pd.DataFrame, value_col: str = 'cor_estimate', row_col: str = 'target', col_col: str = 'predictor', cluster_by: str | None = 'rows', same_order_for_rows_cols: bool = True, fill_missing_for_clustering: float = 0.0, cmap: str = 'RdBu_r', center: float = 0.0, vlim: float | None = None, show_values: bool = True, value_decimals: int = 2, figsize: tuple[float, float] | None = None, cbar_label: str | None = None, linewidth: float = 0.5, linecolor: str = 'lightgrey', text_kwargs: dict | None = None)

Plot a target × predictor interaction matrix as a diverging clustered tile plot.

By default: - tile fill uses cor_estimate - colors are centered at 0 - 0 is white - rows are clustered - the inferred row order is also applied to columns

Parameters:

Name	Type	Description	Default
df	DataFrame	Long-format dataframe with one row per target-predictor interaction.	required
value_col	str	Column used for tile color.	'cor_estimate'
row_col	str	Column defining rows.	'target'
col_col	str	Column defining columns.	'predictor'
cluster_by	str | None	One of {"rows", "columns", None}. If "rows", cluster row profiles and apply that order. If "columns", cluster column profiles and apply that order. If None, keep original order.	'rows'
same_order_for_rows_cols	bool	If True, apply the chosen clustering order to both rows and columns. This is appropriate when rows and columns represent the same entities, e.g. cell types.	True
fill_missing_for_clustering	float	Value used only for clustering missing interactions. Missing plotted tiles remain NaN and are shown as white.	0.0
cmap	str	Diverging colormap.	'RdBu_r'
center	float	Center of the color scale.	0.0
vlim	float | None	Symmetric color limit. If None, inferred from max absolute value.	None
show_values	bool	Whether to write values in tiles.	True
value_decimals	int	Number of decimals shown inside tiles.	2

mc_astra.pl.plot_lr_circos(plot_df: pd.DataFrame, sector_order: Sequence[str] | None = None, sector_colors: Mapping[str, str] | None = None, cmap: str = 'tab10', sector_gap: float = 4, sector_r_lim: tuple[float, float] = (96, 100), gene_label_size: float = 7, link_color: str = 'black', link_width: float = 0.8, link_alpha: float = 0.7, arrow_height: float = 3, arrow_width: float = 2, figsize: tuple[float, float] = (10, 10), start: float = 0, end: float = 360, dpi: int = 100, ax: Axes | None = None, show_sector_legend: bool = True, legend_kwargs: dict | None = None) -> tuple[Figure, Axes]

Plot ligand-receptor interactions as a directed Circos plot.

Each source or target cell type is represented by one sector. Ligands and receptors are placed as labels within their corresponding cell-type sector. Each row creates a directed connection:

source ligand -> target receptor

mc_astra.pl.plot_feats_through_cov(adata, features, view, covariate='time', group_by=None, ci_opacity=0.3, line_size=0.8, dot_size=20, figsize=None, line_color='#08306b', point_color=None, ribbon_color='#d3d3d3', group_colors=None, covariate_order=None, sharey=True)

Plot selected features against a one-dimensional covariate.

For each feature, the function plots the mean values connected by a line, together with mean points and an approximate 95% confidence interval:

mean ± 1.96 * std / sqrt(n)

Parameters:

Name	Type	Description	Default
adata	AnnData	AnnData object containing: adata.obsm[view]: sample-by-feature matrix adata.uns[f"{view}_columns"]: feature names adata.obs[covariate]: covariate values	required
features	sequence of str	Features to plot. Panel order follows the order provided here.	required
view	str	Key in adata.obsm containing the sample-by-feature matrix.	required
covariate	str	Column in adata.obs used for the x-axis.	"time"
group_by	str or None	Optional column in adata.obs defining separate trajectories.	None
ci_opacity	float	Confidence interval opacity.	0.3
line_size	float	Width of the connecting lines.	0.8
dot_size	float	Scatter-point area in points squared.	20
figsize	tuple or None	Figure size. Defaults to approximately four inches per feature.	None
line_color	str	Fixed line colour when group_by=None.	"#08306b"
point_color	str or None	Fixed point colour when group_by=None. When None, uses line_color.	None
ribbon_color	str	Confidence interval colour when group_by=None.	"#d3d3d3"
group_colors	sequence, mapping, or None	Colours used when group_by is provided. If a mapping, keys should be group labels. If a sequence, colours are assigned in group order. If None, colours are taken from Matplotlib's tab10 colormap.	None
covariate_order	sequence or None	Explicit ordering for a categorical covariate.	None
sharey	bool	Whether feature panels share the same y-axis scale.	True

Returns:

Name	Type	Description
fig	Figure	Matplotlib figure.
axes	ndarray	One-dimensional array of Matplotlib axes.
summary	DataFrame	Summary statistics used for plotting.