import networkx as nx
import pandas as pd
import logging
import os
from typing import Tuple, Optional
from modina.metrics import (EDGE_METRICS, NODE_METRICS, ALG_REQUIRES, ALG_EDGE_STATISTIC, ASCENDING_ALGORITHMS,
check_ranking_alg, check_rescaling_consistency)
# Compute ranking
[docs]
def compute_ranking(nodes_diff: Optional[pd.DataFrame | pd.Series], edges_diff: Optional[pd.DataFrame | pd.Series], ranking_alg: str,
path: Optional[str] = None, meta_file: Optional[pd.DataFrame] = None,
edge_node_stats: Optional[pd.DataFrame] = None) -> pd.DataFrame | pd.Series:
"""
Compute a ranking based on the specified ranking algorithm.
The output is additionally enriched with the node-metric value (when a node metric was employed)
and with per-node statistics over the incident edges (when an edge metric was employed).
'MeanEdgeRank' / 'MedianEdgeRank' score each node by the mean / median edge metric over its
incident edges ('edge-mean' / 'edge-median'). 'MeanProductRank' / 'MedianProductRank' rank nodes by
the product of their rank by the node metric and their rank by that mean / median incident edge
metric; their score is therefore better when lower, while 'rank' is 1 for the top node for every
algorithm. Algorithms combining node and edge metrics ('PageRank+', 'MeanProductRank',
'MedianProductRank') require both to use the same effect-size rescaling (RE or VE); P- and LP-based
metrics can be combined with either.
:param nodes_diff: Differential node scores.
:param edges_diff: Differential edge scores.
:param ranking_alg: Ranking algorithm to compute. Options are 'PageRank+', 'PageRank', 'MeanEdgeRank', 'MedianEdgeRank', 'nodeRank', 'MeanProductRank' and 'MedianProductRank'.
:param meta_file: Metadata file containing a 'label' and 'type' column to specify the data type of each variable.
:param path: Optional path to save the ranking as a CSV file.
:param edge_node_stats: Optional precomputed per-node edge statistics (see edge_node_statistics). If not
provided but an edge metric was employed, the statistics are computed on the fly.
:return: A DataFrame containing the ranking, enriched with the node-metric value and per-node edge statistics.
"""
check_ranking_alg(ranking_alg)
node_metric = _find_metric(nodes_diff, NODE_METRICS, fallback=0) if nodes_diff is not None else None
edge_metric = _find_metric(edges_diff, EDGE_METRICS, fallback=3) if edges_diff is not None else None
needs_edges, needs_nodes = ALG_REQUIRES[ranking_alg]
if (needs_edges and edges_diff is None) or (needs_nodes and nodes_diff is None):
required = [name for name, needed in (('nodes_diff', needs_nodes), ('edges_diff', needs_edges)) if needed]
raise ValueError(f"To compute '{ranking_alg}', please provide {' and '.join(repr(r) for r in required)}.")
if needs_edges and needs_nodes:
check_rescaling_consistency(node_metric, edge_metric)
# Per-node statistics over the incident edges (used by the edge-statistic algorithms and to enrich the output)
if edge_metric is not None and edge_node_stats is None:
from modina.diff_net_construction import edge_node_statistics
edge_node_stats = edge_node_statistics(edges_diff, edge_metric)
extra = None
# Personalized PageRank
if ranking_alg == 'PageRank+':
ranking_scores = pagerank(nodes_diff=nodes_diff, edges_diff=edges_diff,
node_metric=node_metric, edge_metric=edge_metric,
personalization=True)
# PageRank
elif ranking_alg == 'PageRank':
ranking_scores = pagerank(edges_diff=edges_diff, edge_metric=edge_metric,
personalization=False)
# Mean / median edge metric over each node's incident edges
elif ranking_alg in ('MeanEdgeRank', 'MedianEdgeRank'):
ranking_scores = edge_node_stats[ALG_EDGE_STATISTIC[ranking_alg]].to_dict()
# Direct ranking based on node metric
elif ranking_alg == 'nodeRank':
ranking_scores = nodes_diff[node_metric].to_dict()
# Product of the node-metric rank and the mean / median edge-metric rank
else:
extra = productrank(nodes_diff=nodes_diff, node_metric=node_metric, edge_node_stats=edge_node_stats,
statistic=ALG_EDGE_STATISTIC[ranking_alg])
ranking_scores = extra['score'].to_dict()
# Construct ranking dataframe
ascending = ranking_alg in ASCENDING_ALGORITHMS
ranking_df = pd.DataFrame({'node': list(ranking_scores.keys()), 'score': list(ranking_scores.values())})
ranking_df = ranking_df.sort_values('score', ascending=ascending).reset_index(drop=True)
ranking_df['rank'] = ranking_df['score'].rank(method='min', ascending=ascending).astype(int)
ranking_df = ranking_df[['node', 'rank', 'score']]
if extra is not None:
ranking_df = ranking_df.merge(extra.drop(columns='score'), how='left', left_on='node', right_index=True)
if meta_file is None:
logging.warning('No meta_file was provided to specify node types.')
else:
meta_file = meta_file.set_index('label')
ranking_df['type'] = ranking_df['node'].map(meta_file['type'])
# Enrich the node-indexed ranking with the node-metric value and per-node edge statistics.
if node_metric is not None:
ranking_df[node_metric] = ranking_df['node'].map(nodes_diff[node_metric])
if edge_metric is not None:
ranking_df = ranking_df.merge(edge_node_stats, how='left', left_on='node', right_index=True)
if path is not None:
ranking_df.to_csv(path, index=False)
return ranking_df
# Name of the metric column: the first column that is a known metric, else the column at the
# position the differential-network functions write it to (with a warning).
def _find_metric(df, known, fallback):
for col in df.columns:
if col in known:
return col
col = df.columns[fallback]
logging.warning(f"No known metric column found; using column '{col}' as the metric.")
return col
# PageRank algorithm
# MeanProductRank / MedianProductRank: rank nodes by the node metric and by the mean / median of their
# incident edge metric (statistic 'edge-mean' / 'edge-median'; both descending, ties get the average
# rank) and score each node by the product of both ranks (lower = better). Nodes without edges or
# without a node score are ranked last in that component.
[docs]
def productrank(nodes_diff, node_metric, edge_node_stats, statistic='edge-mean'):
nodes = nodes_diff.index.union(edge_node_stats.index)
rank_node = nodes_diff[node_metric].reindex(nodes).rank(method='average', ascending=False, na_option='bottom')
rank_edge = edge_node_stats[statistic].reindex(nodes).rank(method='average', ascending=False, na_option='bottom')
return pd.DataFrame({'score': rank_node * rank_edge, 'rank_node': rank_node, 'rank_edge': rank_edge})