damping_sensitivity: Sweep PageRank across a range of damping factors

In pagerankr: Modular Toolkit for PageRank Calculation

Sweep PageRank across a range of damping factors

Description

Runs [pagerank()] at each damping factor \alpha in 'alphas' and returns a tidy data frame of per-URL scores alongside the convergence metadata for each solve. This makes the sensitivity of the ranking to \alpha directly inspectable on *your* graph, rather than relying on the field default of '0.85' (see the "Damping factor" section of [pagerank()] for why that default is only an empirical convention).

Usage

damping_sensitivity(edge_list_df, alphas = c(0.75, 0.8, 0.85, 0.9, 0.95), ...)

Arguments

edge_list_df	A data frame representing the edge list, passed to every [pagerank()] call. (Named for consistency with the rest of the package; it is an edge list, not a constructed graph object.)
alphas	Numeric vector of damping factors to sweep, each strictly between 0 and 1. Default 'c(0.75, 0.80, 0.85, 0.90, 0.95)'. Duplicate values are dropped.
...	Additional arguments forwarded to [pagerank()] (e.g. 'redirects_df', 'weight_col', 'algo', 'eps', 'niter', 'prior_df'). Passing 'damping' here is an error, since 'alphas' is what drives the damping factor.

Details

The helper is the empirical companion to the closed-form \alpha-derivative analysis of Boldi, Santini & Vigna (PageRank as a Function of the Damping Factor, WWW 2005): instead of differentiating the PageRank vector with respect to \alpha analytically, it samples the vector at a grid of \alpha values so you can see how much each page's score (and the overall ranking) actually moves. Pair it with [compare_pagerank()] to quantify the rank churn between any two \alpha values.

Each row also carries the convergence metadata for that \alpha's solve. The empirical 'iters' count is only reported by the ARPACK solver; under the default PRPACK direct solver it is 'NA' (PRPACK exposes no iteration count). To populate it, forward 'algo = "arpack"' (or an 'eps' / 'niter' control) through '...'. The solver-independent 'iters_estimate' column is always populated: it is the power-iteration rule of thumb \lceil \log_{10}(\tau) / \log_{10}(\alpha) \rceil (Langville & Meyer, 2004) at the convergence tolerance \tau, and shows how the required iteration count climbs as \alpha approaches 1 regardless of solver.

Value

A tidy data frame with one row per (URL, \alpha) pair, sorted by 'alpha' ascending then 'score' descending, with columns:

'url'

Node / page identifier.

'alpha'

The damping factor used for this solve.

'score'

The page's PageRank score at this 'alpha'.

'iters'

Iterations the solver used (ARPACK only; 'NA' under PRPACK).

'iters_estimate'

Power-iteration iteration-count estimate at the convergence tolerance (solver-independent).

'residual'

Post-hoc L1 residual \|G x - x\|_1 of the solve.

'converged'

Whether the residual met the tolerance.

A '"convergence"' attribute is attached: a compact one-row-per-'alpha' data frame ('alpha', 'algo', 'iters', 'iters_estimate', 'residual', 'tol', 'converged', 'n_nodes') summarizing each solve.

See Also

[pagerank()] (the "Damping factor" section), [pagerank_convergence], [compare_pagerank()], [pagerank_grid()]

Examples

edges <- data.frame(
  from = c("A", "B", "C", "A", "D"),
  to = c("B", "C", "A", "C", "A")
)
sens <- damping_sensitivity(edges, clean_edge_urls = FALSE)
print(sens)
attr(sens, "convergence")

# Populate the empirical iteration count by using the ARPACK solver.
sens_ar <- suppressMessages(
  damping_sensitivity(edges, algo = "arpack", clean_edge_urls = FALSE)
)
attr(sens_ar, "convergence")

pagerankr documentation built on Oct. 1, 2026, 5:09 p.m.