from typing import Optional
# Score types computed per context (see statistics_utils.add_score_columns). Every edge and node
# metric is built from one of these, so the same score can be compared across metric families:
# P = 1 - p (linear significance; p is the multiple-testing adjusted p-value)
# LP = -log10(p) (log significance)
# RE = rank-based probit rescaled effect size (rescaled-E)
# VE = variance-explained effect size (transformed-E, sign(r) * r² or η²)
# LPxRE = LP * RE, LPxVE = LP * VE
SCORE_TYPES = ('P', 'LP', 'RE', 'VE', 'LPxRE', 'LPxVE')
# Edge metrics, mapped to the score types whose absolute between-context differences are summed.
# 'diff-Z' is not a plain difference of one score: it compares the standardised effect sizes z / sqrt(n) of both
# contexts and divides by the standard error of their difference (see diff_net_construction._diff_z), so it needs
# the per-edge sample size 'n'. It uses no effect-size rescaling and can be combined with every node metric.
EDGE_METRICS = {
**{f'diff-{s}': (s,) for s in SCORE_TYPES},
'sum-LP-VE': ('LP', 'VE'),
'sum-LP-RE': ('LP', 'RE'),
'diff-Z': ('Z',),
}
# Node metrics: weighted degree centrality (WDC), PageRank centrality (PRC) and statistical test
# centrality (STC), each with every score type.
NODE_FAMILIES = ('WDC', 'PRC', 'STC')
NODE_METRICS = tuple(f'{f}-{s}' for f in NODE_FAMILIES for s in SCORE_TYPES)
RANKING_ALGORITHMS = ('PageRank+', 'PageRank', 'MeanEdgeRank', 'MedianEdgeRank', 'nodeRank', 'MeanProductRank',
'MedianProductRank')
# (needs edges_diff, needs nodes_diff) per ranking algorithm
ALG_REQUIRES = {
'PageRank+': (True, True),
'PageRank': (True, False),
'MeanEdgeRank': (True, False),
'MedianEdgeRank': (True, False),
'nodeRank': (False, True),
'MeanProductRank': (True, True),
'MedianProductRank': (True, True),
}
# Per-node edge statistic (column of edge_node_statistics) used by the edge-statistic based algorithms
ALG_EDGE_STATISTIC = {
'MeanEdgeRank': 'edge-mean',
'MedianEdgeRank': 'edge-median',
'MeanProductRank': 'edge-mean',
'MedianProductRank': 'edge-median',
}
# Ranking algorithms whose score is better when lower (sorted and ranked ascending).
ASCENDING_ALGORITHMS = frozenset({'MeanProductRank', 'MedianProductRank'})
def metric_score(metric: str) -> str:
"""Score type a node metric is built from, e.g. 'PRC-LPxRE' -> 'LPxRE'."""
return metric.split('-', 1)[1]
[docs]
def check_edge_metric(edge_metric: str) -> str:
if edge_metric not in EDGE_METRICS:
raise ValueError(f"Invalid edge metric '{edge_metric}'. Choose from: {', '.join(EDGE_METRICS)}.")
return edge_metric
[docs]
def check_node_metric(node_metric: str) -> str:
if node_metric not in NODE_METRICS:
raise ValueError(f"Invalid node metric '{node_metric}'. Choose from: {', '.join(NODE_METRICS)}.")
return node_metric
[docs]
def check_ranking_alg(ranking_alg: str) -> str:
if ranking_alg not in RANKING_ALGORITHMS:
raise ValueError(f"Invalid ranking algorithm '{ranking_alg}'. Choose from: {', '.join(RANKING_ALGORITHMS)}.")
return ranking_alg
[docs]
def effect_rescaling(metric: Optional[str]) -> Optional[str]:
"""Effect-size rescaling a metric uses: 'RE' (rank-based), 'VE' (variance-explained) or None (P, LP)."""
if metric is None:
return None
components = EDGE_METRICS[metric] if metric in EDGE_METRICS else (metric_score(metric),)
for rescaling in ('RE', 'VE'):
if any(rescaling in c for c in components):
return rescaling
return None
[docs]
def check_rescaling_consistency(node_metric: Optional[str], edge_metric: Optional[str], ranking_alg: Optional[str] = None) -> None:
"""Node and edge metrics combined in one ranking must not mix the RE and VE effect-size rescalings."""
if ranking_alg is not None and not all(ALG_REQUIRES.get(ranking_alg, (False, False))):
return
node_rescaling, edge_rescaling = effect_rescaling(node_metric), effect_rescaling(edge_metric)
if node_rescaling is not None and edge_rescaling is not None and node_rescaling != edge_rescaling:
raise ValueError(f"The node metric '{node_metric}' ({node_rescaling}) and the edge metric '{edge_metric}' ({edge_rescaling}) "
f"use different effect-size rescalings and cannot be combined. Use the same rescaling (RE or VE) for both.")