flowsig.tools

Functions

learn_intercellular_flows() → None)

Learn the causal signaling network from cell-type-ligand expression constructed

apply_biological_flow(→ None)

Enforce inflow → module → (outflow | module)x ordering on a CPDAG.

filter_low_confidence_edges(→ None)

Keep only bootstrap‑stable edges (no biology applied).

construct_intercellular_flow_network(→ networkx.DiGraph)

Convert a (possibly filtered / validated) CPDAG adjacency into a weighted

Package Contents

flowsig.tools.learn_intercellular_flows(adata: anndata.AnnData, condition_key: str | None = None, control: str | None = None, use_spatial: bool = False, block_key: str | None = None, n_jobs: int = 1, n_bootstraps: int = 100, alpha_ci: float = 0.001, alpha_inv: float = 0.001, config: flowsig.preprocessing.FlowSigConfig = FlowSigConfig()) → None

Learn the causal signaling network from cell-type-ligand expression constructed from scRNA-seq and a base network derived from cell-cell communication inference.

This method splits the cell-type-ligand expression into control and perturbed samples (one sample for each perturbed condition). We then use UT-IGSP [Squires2020] and partial correlation testing to learn the causal signaling DAG and the list of perturbed (intervention) targets.

The base network is also used as a list of initial node permutations for DAG learning. To overcome the DAG assumption, as cell-cell communication networks are not necessarily DAGS, we use bootstrap aggregation to cover as many possible causal edges and the list of node permutations is constructed from all possible DAG subsets of the base network. Each boostrap sample is generated by sampling with replacement.

Parameters:

  • adata – The annotated dataframe (typically from Scanpy) of the single-cell data. Must contain constructed flow expression matrices and knowledge of possible cellular flow variables.

  • condition_key – The label in adata.obs which we use to partition the data.

  • control – The category in adata.obs[condition_key] that specifies which cells belong to the control condition, which is known in causal inference as the observational data.

  • flowsig_network_key – The label for which output will be stored in adata.uns

  • flow_expr_key – The label for which the augmente dflow expression expression is stored in adata.obsm

  • use_spatial – Boolean for whether or not we are analysing spatial data, and thus need to use block bootstrapping rather than normal bootstrapping, where we resample across all cells.

  • block_key – The label that specfies from which observation key we use to construct (hopefully) spatially correlated blocks used for block bootstrapping to learn spatially resolved cellular flows. These blocks can be simply just dividing the tissue into rougly equally spaced tissue regions, or can be based on tissue annotation (e.g. organ, cell type).

  • n_jobs – Number of CPU cores that are used during bootstrap aggregation. If n_jobs > 1, jobs are submitted in parallel using multiprocessing

  • n_boostraps – Number of bootstrap samples to generate for causal DAG learning.

  • alpha_ci – The significance level used to test for conditional independence

  • alpha_inv – The significance level used to test for conditional invariance.

Returns:

  • flow_vars – The list of cell-type-ligand pairs used during causal structure learning, stored in adata.uns[flowsig_network_key][‘flow_vars’].

  • adjacency – The weighted adjacency matrix encoding a bagged CPDAG, where weights are determined from bootstrap aggregation. Stored in adata.uns[flowsig_network_key][‘adjacency’]

  • perturbed_targets – The list of inferred perturbed targets, as determined by conditional invariance testing and their bootstrapped probability of perturbations. Stored in adata.uns[flowsig_network_key][‘perturbed_targets’]

References

[Squires2020]

Squires, C., Wang, Y., & Uhler, C. (2020, August). Permutation-based causal structure learning with unknown intervention targets. In Conference on Uncertainty in Artificial Intelligence (pp. 1039-1048). PMLR.

flowsig.tools.apply_biological_flow(adata: anndata.AnnData, *, flowsig_network_key: str = 'flowsig_network', adjacency_key: str = 'adjacency', validated_key: str = 'validated') → None

Enforce inflow → module → (outflow | module)x ordering on a CPDAG. Undirected module–module edges are kept bidirectionally.

flowsig.tools.filter_low_confidence_edges(adata: anndata.AnnData, edge_threshold: float, *, flowsig_network_key: str = 'flowsig_network', adjacency_key: str = 'adjacency', filtered_key: str = 'filtered') → None

Keep only bootstrap‑stable edges (no biology applied).

flowsig.tools.construct_intercellular_flow_network(adata: anndata.AnnData, *, flowsig_network_key: str = 'flowsig_network', adjacency_key: str = 'adjacency') → networkx.DiGraph

Convert a (possibly filtered / validated) CPDAG adjacency into a weighted directed NetworkX graph, orienting undirected edges by the same biological rules as apply_biological_flow.