Explore Multicell

class recon.explore.recon.Celltype(celltype_name: str, grn_graph: str | DataFrame, receptor_grn_bipartite: str | DataFrame, receptor_graph: str | DataFrame | None = None, lamb=None, eta=None, receptor_graph_directed: bool = True, receptor_graph_weighted: bool = False, grn_graph_directed: bool = False, grn_graph_weighted: bool = True, receptor_grn_bipartite_graph_directed: bool = False, receptor_grn_bipartite_graph_weighted: bool = True, copy_graphs=True, seeds: List | Dict = [])

Bases: object

Single-cell-type multilayer network for ReCoN exploration.

A Celltype contains two multiplexes, one for intracellular gene regulation and one for receptors, plus a bipartite receptor-to-gene layer. Use Multixrank() when you need direct access to the underlying HuMMuS/Multixrank object, or explore() for the common one-line workflow that builds the multilayer object and runs random walk with restart.

Multixrank(self_loops=True, restart_proba=0.7, verbose=True)

Build the HuMMuS Multixrank object for this cell type.

Parameters:

  • self_loops (bool, default=True) – Whether to add self-loops in each layer.

  • restart_proba (float, default=0.7) – Random-walk restart probability.

  • verbose (bool, default=True) – Passed to HuMMuS when constructing the multilayer object.

Returns:

Configured multilayer object. Call random_walk_rank() on it to compute node scores, or use explore() to do both steps.

Return type:

hummuspy.create_multilayer.Multixrank

explore(seeds: List | Dict | None = None, self_loops=True, restart_proba=0.7, verbose=True, **random_walk_rank_kwargs)

Build the multilayer object and run random walk with restart.

This is the convenience method for the usual workflow:

results = celltype.explore(seeds=["MYC"], restart_proba=0.7)

It stores the created HuMMuS object in self.multilayer and the resulting scores in self.results before returning the scores.

Parameters:

  • seeds (list, dict, optional) – Seeds to use for this run. If provided, self.seeds is updated before building the multilayer object. Dictionaries are interpreted as weighted seeds.

  • self_loops (bool, default=True) – Whether to add self-loops in each layer.

  • restart_proba (float, default=0.7) – Random-walk restart probability.

  • verbose (bool, default=True) – Passed to Multixrank().

  • **random_walk_rank_kwargs – Extra keyword arguments forwarded to self.multilayer.random_walk_rank.

Returns:

Random-walk ranking results returned by HuMMuS.

Return type:

pandas.DataFrame

rename_celltype(celltype_name)
class recon.explore.recon.Multicell(celltypes: List[Celltype] | List[Dict] | List[Dict[str, Celltype]], cell_communication_graph: DataFrame, lamb=None, eta=None, cell_communication_graph_directed: bool = False, cell_communication_graph_weighted: bool = True, bipartite_grn_cell_communication_directed: bool | int = False, bipartite_grn_cell_communication_weighted: bool = False, bipartite_cell_communication_receptor_directed: bool = False, bipartite_cell_communication_receptor_weighted: bool = False, copy_graphs=True, seeds=[], verbose=True)

Bases: Celltype

Multicellular multilayer network.

Multicell combines several Celltype objects with a cell-cell communication layer. It supports the same Multixrank() and explore() workflow as Celltype; explore creates self.multilayer, runs random_walk_rank(), stores self.results, and returns the result table.

explore(seeds: List | Dict | None = None, self_loops=True, restart_proba=0.7, verbose=True, **random_walk_rank_kwargs)

Build the multicellular multilayer object and run RWR.

Parameters are the same as Celltype.explore(). Multicellular seed names usually include the cell-type suffix, for example "IL6::Macrophage" for gene-layer seeds or "IL6-Macrophage" for cell-communication-layer seeds.

illustrate_multicell(figsize=(12, 10), azim=90, elev=20, display_layer_axis=True, display_self_proba=True, display_layer_names=False, alpha_layers=0.5, cell_communication_layer_name='cell_communication')
recon.explore.recon.combine_effects(direct_effect, indirect_effect, alpha=0.8, cell_comm_matrix=None)

Combine direct and indirect perturbation effects.

Parameters:

  • direct_effect (pandas.DataFrame) – Direct-effect scores with genes as rows and target cell types as columns.

  • indirect_effect (pandas.DataFrame) – Indirect-effect scores with genes as rows and a two-level column index (celltype_target, celltype_source).

  • alpha (float, default=0.8) – Weight assigned to indirect effects. 1 - alpha is assigned to direct effects.

  • cell_comm_matrix (pandas.DataFrame, optional) – Optional cell-type communication weighting matrix. Rows should be target cell types and columns source cell types.

Returns:

Combined effect matrix with genes as rows and cell types as columns.

Return type:

pandas.DataFrame

recon.explore.recon.format_multicell_results(multicell_multixrank_results, celltypes: List[str], keep_layers: str | List[str] = 'gene', split: str = '::')

Format multicellular random-walk results as cell-type profiles.

Parameters:

  • multicell_multixrank_results (pandas.DataFrame) – Result table returned by Multicell.explore() or by Multicell.Multixrank(...).random_walk_rank(). It must contain at least node, layer, and score columns.

  • celltypes (list of str) – Cell types included in the multicellular analysis.

  • keep_layers (str or list of str, default="gene") – Layer name pattern(s) to retain. The default keeps gene-layer scores.

  • split (str, default="::") – Delimiter separating node names from cell-type names.

Returns:

Matrix with genes as rows, cell types as columns, and random-walk scores as values.

Return type:

pandas.DataFrame

recon.explore.recon.multicell_targets(seeds, celltypes, ccc, grn, receptor_grn: str | DataFrame, receptor_layer=None, grn_graph_directed=False, grn_graph_weighted=True, receptor_grn_graph_directed=False, receptor_grn_graph_weighted=True, receptor_graph_directed=False, receptor_graph_weighted=False, cell_communication_graph_directed=False, cell_communication_graph_weighted=True, bipartite_grn_cell_communication_directed=False, bipartite_grn_cell_communication_weighted=False, bipartite_cell_communication_receptor_directed=False, bipartite_cell_communication_receptor_weighted=False, restart_proba=0.6, extend_seeds=False, lamb=None, celltype_to_ccc_proba=None, ccc_to_celltype_proba=None, ccc_proba=0.5, grn_proba=0.5, njobs=-1, verbose=True, keep_layers='gene')

Predict direct and indirect perturbation effects across cell types.

The function builds a multicellular ReCoN network, runs intracellular random walk with restart to estimate direct effects, then propagates the resulting ligand signal through cell-cell communication to estimate indirect effects.

Parameters:

  • seeds (list or dict) – Perturbed genes or weighted seed genes.

  • celltypes (list or dict) – Cell-type names, Celltype objects, dictionaries accepted by Celltype, or a mapping from names to those objects.

  • ccc (pandas.DataFrame) – Cell-cell communication table with ligand source, receptor target, celltype_source, celltype_target, and weight columns.

  • grn (pandas.DataFrame or str) – Gene regulatory network shared by the cell types, unless individual Celltype objects are provided.

  • receptor_grn (pandas.DataFrame or str) – Receptor-to-gene bipartite network, or a loadable resource/path.

  • restart_proba (float, default=0.6) – Random-walk restart probability.

  • extend_seeds (bool, default=False) – If True, expand each seed to all cell types in the communication layer.

  • njobs (int, default=-1) – Number of parallel jobs for indirect-effect runs.

  • verbose (bool or int, default=True) – Controls progress messages and HuMMuS verbosity.

  • keep_layers (str or list of str, default="gene") – Layers retained for indirect-effect computations.

Returns:

(direct_effect, indirect_effect). Direct effects are indexed by gene and have target cell types as columns. Indirect effects are indexed by gene and have a (celltype_target, celltype_source) column index.

Return type:

tuple[pandas.DataFrame, pandas.DataFrame]

recon.explore.recon.set_lambda(multicell=None, celltypes=None, cell_communication_layer_name='cell_communication', direction: upstream | downstream = 'downstream', strategy: intracell | intercell = 'intercell', celltype_to_ccc_proba=None, ccc_to_celltype_proba=None)
recon.explore.recon.summarize_indirect_effects(predictions)

Split combined contribution tables into direct and indirect effects.