netmap.downstream.final_downstream.filter_grn_by_top_signatures

netmap.downstream.final_downstream.filter_grn_by_top_signatures(data_ucell: DataFrame, grn_adata: AnnData, keep_top_ranked: int = 100, filter_by: str = 'z_score') → Tuple[AnnData | None, List[str]]

Filters a GRN (Gene Regulatory Network) AnnData object to keep only the edges corresponding to the top-ranked signatures per cluster based on UCell scores.

Parameters:

  • data_ucell (pd.DataFrame) – DataFrame containing UCell scores for each signature across cells, with a ‘spectral’ column indicating cluster assignments.

  • grn_adata (AnnData) – The GRN AnnData object to filter, containing edge metadata in .var.

  • keep_top_ranked (int, optional) – Number of top signatures to retain per cluster (default is 100).

  • filter_by (str, optional) – Metric used to rank signatures. Options include “P_Value”, “Adjusted_P_Value”, or “z_score” (default is “P_Value”).

Returns:

  • Filtered AnnData object containing only edges corresponding to top-ranked signatures.

  • List of unique top source names used to filter the GRN.

Return type:

Tuple[Optional[AnnData], List[str]]

Notes

  • For each cluster, signatures are ranked using the chosen metric.

  • When filter_by=’z_score’, a combined score of -log10(P_Value) and z_score is used.

  • The function returns None and an empty list if the input GRN has no variables.