simulate_changes: Simulate the PageRank Impact of Link and Redirect Changes
In pagerankr: Modular Toolkit for PageRank Calculation

simulate_changes

R Documentation

Simulate the PageRank Impact of Link and Redirect Changes

Description

Compares PageRank before and after proposed changes to the link graph, at both the edge level (adding/removing links) and the URL level (retiring a page behind a redirect, or repointing an existing redirect). The whole graph is recomputed and a before/after table is returned; interpretation is left to the caller. This is a faithful recompute primitive, not a ranking or target-optimization engine.

Usage

simulate_changes(
  edge_list_df,
  add_links_df = NULL,
  remove_links_df = NULL,
  redirect_urls_df = NULL,
  remove_urls = NULL,
  redirects_df = NULL,
  on_unknown_target = c("warn", "error", "allow"),
  ...,
  edge_from_col = "from",
  edge_to_col = "to",
  redirect_from_col = "from",
  redirect_to_col = "to",
  label_baseline = "baseline",
  label_proposed = "proposed"
)

Arguments

`edge_list_df`	A data frame representing the current link edge list.
`add_links_df`	Optional data frame of links to add. Must have the same from/to column names as `edge_list_df`. Columns present in `edge_list_df` but absent here are padded with `NA` on the added rows, so weighted / annotated edge lists keep their schema. Default `NULL`.
`remove_links_df`	Optional data frame of links to remove. Matching is by exact from+to pair. Must have the same from/to column names as `edge_list_df`. Default `NULL`.
`redirect_urls_df`	Optional two-column `from`/`to` data frame of URL-level redirects to model. Each row retires the `from` URL and sends its inbound authority to `to` at 100% pass-through. Retire semantics: the live source's own outbound links are stripped before folding (an honest 301 has no body), so the target inherits the source's inbound authority only, never its outlinks. A row for source `A` overrides any prior redirect for `A` – whether from an earlier row or from the baseline crawl's real 3xx – so "change A into a redirect to C" is a single override. A duplicate source mapping to two distinct targets in one changeset is an error (strict). Default `NULL`.
`remove_urls`	Optional character vector of URLs to model as removed (turned into HTTP 404s). Each removed URL keeps its inbound links – other pages still point at it – but now they flow into a dead page: authority arrives and evaporates to the shared waste sink rather than redistributing across the site (dangle) or self-amplifying (self-loop). The page's own outbound links are dropped. The node stays in the output holding the mass it absorbed once, flagged `"removed-dead"` in `node_status` so its residual score is never misread as earned authority. Under the hood this forces a `status_df` entry (HTTP `404`) into the proposed model only; 4xx and 5xx are one class (no split). A URL appearing in both `remove_urls` and `redirect_urls_df` is an error (a page cannot be both a 301 and a 404). To also model cleaning up the inbound links, compose with `remove_links_df`. Default `NULL`.
`redirects_df`	Optional data frame of existing redirects (baseline). Default `NULL`.
`on_unknown_target`	How to treat a redirect or link target that is not a node in the current graph (it may be a legitimate new page, modeled as a new node that carries inbound authority with no outlinks yet). One of `"warn"` (default, warn and proceed), `"error"`, or `"allow"` (proceed silently).
`...`	Additional arguments passed to both `pagerank()` calls (e.g., `clean_edge_urls`, `damping`, `nofollow_col`, `indexability_df`, etc.).
`edge_from_col`	Name of the from column in edge list data frames. Default `"from"`.
`edge_to_col`	Name of the to column in edge list data frames. Default `"to"`.
`redirect_from_col`	Name of the source column in `redirect_urls_df` and `redirects_df`. Default `"from"`.
`redirect_to_col`	Name of the target column in `redirect_urls_df` and `redirects_df`. Default `"to"`.
`label_baseline`	Label for the baseline model in the comparison output. Default `"baseline"`.
`label_proposed`	Label for the proposed model in the comparison output. Default `"proposed"`.

Value

The output of compare_pagerank (per-node deltas, percentage changes, and rank changes between baseline and proposed) with an added node_status column: "normal" for a node present and live in both models, "new-target" for a node introduced by the changeset (present in the proposed model, absent from the baseline), or "removed-dead" for a node retired via remove_urls (its proposed score is residual absorbed mass on the way to the waste sink, not earned authority).

node_status describes a node's role in this before/after comparison, which is a different axis from the page_state column pagerank attaches to describe a page's health/index state (live / noindex / robots_blocked / response_dead). The two are deliberately not merged into one vocabulary: new-target has no health analog, and removed-dead is the single value bridging both axes — a node whose comparison role is "removed" because its proposed health state is response_dead (a forced 404). Attributes:

summary: Aggregate statistics from compare_pagerank().
proposed: The full proposed pagerank() result, including its transition_audit attribute, so the evaporated-mass cost of a removal is surfaced by default.
manifest: A named list describing the changeset: redirects applied, which sources overrode a prior redirect, URLs removed, link add/remove counts, and any unknown targets.

Examples

# Current site links
edges <- data.frame(
  from = c("Home", "Home", "About", "Blog"),
  to = c("About", "Blog", "Home", "Home")
)

# Propose adding a link from Blog to About
new_links <- data.frame(
  from = "Blog", to = "About"
)
result <- simulate_changes(edges,
  add_links_df = new_links,
  clean_edge_urls = FALSE
)
print(result)
attr(result, "summary")

# Retire the About page behind a redirect to Home
retire <- data.frame(from = "About", to = "Home")
simulate_changes(edges, redirect_urls_df = retire, clean_edge_urls = FALSE)

# Model the About page 404-ing: inbound authority flows in and evaporates
simulate_changes(edges, remove_urls = "About", clean_edge_urls = FALSE)

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