Visualization

Multicellular Network

recon.plot.plot_multicell.illustrate_multicell(lamb, figsize=(12, 10), azim: float = 90, elev: float = 20, display_layer_axis=True, display_self_proba=True, display_layer_names=False, alpha_layers: float = 0.5, cell_communication_layer_name: str = 'cell_communication')

Visualize the transition probabilities between layers in a multicellular multilayer model.

Parameters:

  • lamb (pd.DataFrame) – A DataFrame representing the transition probabilities between layers.

  • figsize (tuple, optional) – Size of the figure (width, height). Default is (12, 10).

  • azim (int, optional) – Azimuth angle for the 3D plot view. Default is 90.

  • elev (int, optional) – Elevation angle for the 3D plot view. Default is 20.

  • display_layer_axis (bool, optional) – Whether to display the layer axis. Default is True.

  • display_self_proba (bool, optional) – Whether to display self-transition probabilities. Default is True.

  • display_layer_names (bool, optional) – Whether to display layer names on the plot. Default is False.

  • alpha_layers (float, optional) – Transparency level for the layer planes. Default is 0.5.

  • cell_communication_layer_name (str, optional) – Name of the cell communication layer. Default is “cell_communication”.

Return type:

None

Result Plots

recon.plot.plot_results.plot_celltype_comparison(df, celltype1, celltype2, quantile=0.999)

Scatter plot of two cell types, highlighting outliers where celltype1 >> celltype2 (far to the right of diagonal), with a side zoom panel.

Parameters:

  • df (pd.DataFrame) – DataFrame with at least the two columns.

  • celltype1 (str) – Column name for X-axis.

  • celltype2 (str) – Column name for Y-axis.

  • quantile (float) – Quantile threshold for defining outliers (default=0.999).

Sankey Plots

recon.plot.sankey_paths.plot_intracell_sankey(multicell_obj, results, cell_type, seeds, top_receptor_n: int = 30, top_tf_n: int = 10, flow='upstream', verbose: bool = False, save_path=None)

Plot the intracellular regulatory Sankey diagram for a given cell type. This includes only the receptor → TF → gene layers, without any ligand or before-cell layers.

Parameters:

  • multicell_obj (object) – The multicell object containing the data.

  • results (pandas.DataFrame) – The results DataFrame containing scores for nodes.

  • cell_type (str) – The cell type of interest.

  • seeds (list or pd.Series) – List of gene names (in the form “GENE::CellType”) to filter for.

  • top_receptor_n (int, default=30) – Number of top receptors to include.

  • top_tf_n (int, default=10) – Number of top transcription factors to include.

  • flow (str, default="upstream") – Direction of the result scores. The diagram keeps the same receptor → TF → gene layout for both directions.

  • verbose (bool, default=False) – If True, print detailed debugging information about network construction.

  • save_path (str or None, default=None) – If provided, save the figure as an HTML file to this path.

Return type:

None

recon.plot.sankey_paths.plot_ligand_sankey(multicell_obj, results, cell_type, seeds, ligand_cells, top_ligand_n: int = 100, top_receptor_n: int = 30, top_tf_n: int = 10, per_celltype: bool = True, flow='upstream', verbose: bool = False, save_path=None)

Plot the ligand regulatory Sankey diagram for a given cell type. This includes the ligand → receptor → TF → gene layers, without any before-cell layers.

Parameters:

  • multicell_obj (object) – The multicell object containing the data.

  • results (pandas.DataFrame) – The results DataFrame containing scores for nodes.

  • cell_type (str) – The cell type of interest.

  • seeds (list or pd.Series) – List of gene names (in the form “GENE::CellType”) to filter for.

  • ligand_cells (list of str) – List of cell types to consider as ligand sources.

  • top_ligand_n (int, default=100) – Number of top ligands to include.

  • top_receptor_n (int, default=30) – Number of top receptors to include.

  • top_tf_n (int, default=10) – Number of top transcription factors to include.

  • per_celltype (bool, default=True) – If True, select top ligands per ligand cell type. If False, select top ligands globally.

  • flow (str, default="upstream") – Direction of the result scores. The diagram keeps the same ligand → receptor → TF → gene layout for both directions.

  • verbose (bool, default=False) – If True, print detailed debugging information about network construction.

  • save_path (str or None, default=None) – If provided, save the figure as an HTML file to this path.

Return type:

None

recon.plot.sankey_paths.plot_intercell_sankey(multicell_obj, results, cell_type, seeds, ligand_cells, top_ligand_n: int = 100, top_receptor_n: int = 30, top_tf_n: int = 10, before_top_n: int = 5, per_celltype: bool = True, flow='upstream', verbose: bool = False, save_path=None)

Plot the full intercellular regulatory Sankey diagram for a given cell type. This includes the before-cell layers (receptor → TF and TF → ligand) as well as the ligand → receptor → TF → gene layers.

Parameters:

  • multicell_obj (object) – The multicell object containing the data.

  • results (pandas.DataFrame) – The results DataFrame containing scores for nodes.

  • cell_type (str) – The cell type of interest.

  • seeds (list or pd.Series) – List of gene names (in the form “GENE::CellType”) to filter for.

  • ligand_cells (list of str) – List of cell types to consider as ligand sources.

  • top_ligand_n (int, default=100) – Number of top ligands to include.

  • top_receptor_n (int, default=30) – Number of top receptors to include.

  • top_tf_n (int, default=10) – Number of top transcription factors to include.

  • before_top_n (int, default=5) – Number of top receptors and TFs to include in the before-cell layers.

  • per_celltype (bool, default=True) – If True, select top ligands per ligand cell type. If False, select top ligands globally.

  • flow (str, default="upstream") – Direction of the result scores. The diagram keeps the same upstream receptor → upstream TF → ligand → receiver receptor → TF → gene layout.

  • verbose (bool, default=False) – If True, print detailed debugging information about network construction.

  • save_path (str or None, default=None) – If provided, save the figure as an HTML file to this path.

Return type:

None

Cascade Plots

recon.plot.cascade_plot.cascade_plot(multicell_obj, results: DataFrame, *, cell_type: str | None = None, seeds: list | None = None, ligand_cells: list | None = None, top_ligand_n: int = 20, top_receptor_n: int = 10, top_tf_n: int = 10, before_top_n: int = 5, per_celltype: bool = True, show_seeds: bool = False, celltype_colors: dict | None = None, celltype_display_names: dict | None = None, show_labels: bool = True, label_fontsize: int = 14, node_size_by_weight: bool = True, node_type_halo: bool = False, node_alpha: float = 0.85, edge_alpha: float = 0.65, seed_label: str | None = None, seed_label_fontsize: int = 10, figsize: tuple | None = None, save_path: str | None = None, verbose: bool = False, title: str | None = None, flow: str = 'upstream')

Biological cell cascade diagram for a single run.

Node color: white → type color gradient (score-based). Edge color: white → grey gradient (source score-based),

with black outline underneath.

Node radius: proportional to score.

Parameters:

  • multicell_obj (single multicell object)

  • results (DataFrame with columns node, score.)

  • seeds (list of str, optional) – Raw seed gene names (e.g. [‘Nfkb1’, ‘Tnf’]).

  • show_seeds (bool) – If True, seed genes are shown as individual nodes in the nucleus.

  • flow ({'upstream', 'downstream'}, default='upstream') – If ‘upstream’, draw ligand → receptor → TF → gene arrows. If ‘downstream’, draw gene → TF → receptor → ligand arrows.

recon.plot.cascade_plot.contrast_cascade_plot(multicell_objs: dict, results_a: DataFrame, results_b: DataFrame, *, cell_type: str | None = None, seeds: list | None = None, ligand_cells: list | None = None, top_ligand_n: int = 20, top_receptor_n: int = 10, top_tf_n: int = 10, before_top_n: int = 5, per_celltype: bool = True, show_seeds: bool = False, delta_vmax: float = 2.0, delta_min_quantile: float = 0.3, delta_min_color_fraction: float = 0.0, contrast_scheme: str = 'temperature', celltype_colors: dict | None = None, celltype_display_names: dict | None = None, normalize_receiver_scores: bool = True, show_labels: bool = True, label_fontsize: int = 14, node_size_by_weight: bool = True, node_type_halo: bool = False, node_alpha: float = 0.85, edge_alpha: float = 0.65, seed_label: str | None = None, seed_label_fontsize: int = 10, figsize: tuple | None = None, save_path: str | None = None, verbose: bool = False, title: str | None = None, flow: str = 'upstream')

Biological cell cascade diagram comparing two runs.

Node and edge color uses a diverging scale based on the score difference between run A and run B.

Parameters:

  • multicell_objs (dict) – Condition-keyed dict of multicell objects.

  • results_a (DataFrame) – Run A results with columns node, score.

  • results_b (DataFrame) – Run B results with columns node, score.

  • contrast_scheme ({'temperature', 'sex'}) – ‘temperature’: blue (B-enriched) ↔ white ↔ red (A-enriched). ‘sex’: blue (A-enriched) ↔ white ↔ orange (B-enriched).

  • normalize_receiver_scores (bool) – Z-score color values within each receiver layer.

  • flow ({'upstream', 'downstream'}, default='upstream') – If ‘upstream’, draw ligand → receptor → TF → gene arrows. If ‘downstream’, draw gene → TF → receptor → ligand arrows.