GA4 Entrance / Landing-Page Teleport Adapter (PROXY)

Turns GA4 entrance / landing-page counts into the teleport (reset / personalization) vector for weighted PageRank with an entrance-biased reset. Each session start is treated as a teleport event whose destination is the landing page, so pages where users more often begin a session receive proportionally more of the random surfer's reset mass — replacing the uniform teleport of standard PageRank.

This is the cheapest of the three behavioral-reset models (it reuses the standard PageRank machine unchanged), and it is deliberately a proxy: see the dedicated note below.

Usage

ga4_entrance_teleport(
  entrances_df,
  url_col = "url",
  entrances_col = "entrances",
  vertex_names = NULL,
  transform = c("none", "log", "percentile", "minmax", "zipf", "rank_linear"),
  alpha = 0,
  exclude_nodes = character(0),
  verbose = TRUE
)

Arguments

entrances_df: A data frame with one row per (landing page, entrance count) observation, e.g. a GA4 "Landing page" report. Multiple rows for the same URL are summed (entrances are additive raw counts). Rows with a missing URL or a missing / negative count are dropped.
url_col: Name of the landing-page URL column in entrances_df. Default "url".
entrances_col: Name of the numeric entrance-count column in entrances_df. Default "entrances". Contract: this must be an additive raw count (session starts / entrances), never a rate, share, or computed score — folding two URLs onto one representative is a meaningful sum. This mirrors the TIPR additive-count contract in [align_prior_to_vertices()].
vertex_names: Optional character vector of the graph's vertex names, in graph order (e.g. igraph::V(graph)$name). When supplied, the adapter returns the aligned teleport vector directly by delegating to [align_prior_to_vertices()] (passing transform, alpha, exclude_nodes, verbose). The vertex_names you pass must already be canonicalized + redirect-folded like the edges; pass NULL (the default) to get back a prior_df-shaped data frame and let [pagerank()] perform that canonicalization + fold (the recommended path — single source of truth for folding).
transform, alpha, exclude_nodes, verbose: Passed through to [align_prior_to_vertices()] when vertex_names is supplied; ignored otherwise. See that function for semantics. alpha = 1 recovers the standard uniform teleport.

Value

If vertex_names is NULL (default), a data frame with columns url and weight (one row per unique landing-page URL, entrances summed) ready to pass to pagerank(prior_df = , alpha = ). If vertex_names is supplied, a numeric teleport vector the same length and order as vertex_names, summing to 1 (the return value of [align_prior_to_vertices()]).

Details

Uniform entrances recover uniform teleport. If every (real) vertex has the same entrance count, the entrance share is uniform, so the resulting teleport vector equals the standard uniform PageRank reset — the proxy degrades gracefully to the default when there is no entrance signal.

Recommended usage (let pagerank() own the fold):


  tp <- ga4_entrance_teleport(ga4_landing_report,
                              url_col = "landing_page",
                              entrances_col = "sessions")
  pagerank(edges, prior_df = tp)   # prior_df = data.frame(url, weight)

This is a PROXY, not an identity

Session starts are not literally equivalent to every PageRank teleport event. The teleport in PageRank fires on every damping draw (including mid-session "I got bored, jump elsewhere" restarts), while GA4 entrances only observe the first page of a session. Using entrances as the reset distribution is a defensible approximation of "where browsing tends to (re)start," but it is an approximation. Higher-fidelity models — page-specific exit probabilities (a discrete behavioral Markov model) and continuous-time BrowseRank with dwell time — are explicitly out of scope here. Treat, report, and cite this vector as the entrance-biased teleport proxy.

Distinct from the backlink-authority prior

This adapter and the external-authority TIPR prior (e.g. Ahrefs referring domains; see [align_prior_to_vertices()]) both flow through the same prior_df / [align_prior_to_vertices()] plumbing, but they answer different questions and should not be conflated:

Backlink-authority prior — where authority enters the graph from outside (off-site links). A structural/link signal.
Entrance teleport (this adapter) — where users enter / restart browsing (observed session starts). A behavioral signal, and only a proxy for the teleport event (see above).

They can be used as alternatives, or — outside this function's remit — blended; that mixing policy is not decided here.

Naming decision (prior_df vs teleport_df/reset_df)

We reuse the existing prior_df machinery rather than introducing a separate teleport_df / reset_df. Rationale: (1) entrances are additive raw counts, so they satisfy the same TIPR additive-count contract as referring-domain counts — duplicate / redirect-folded URLs combine by summation, which is exactly what [align_prior_to_vertices()] already does; (2) both signals produce a teleport vector over the same final vertex set with the same canonicalization + redirect fold, so a parallel data-frame type and a parallel alignment path would be duplicated machinery for no behavioral gain; (3) the semantic distinction (authority-in vs users-in) is carried by documentation and by the proxy labeling here, not by the data structure. If a future model needs to blend a backlink prior and an entrance reset in a single pagerank() call, that is the point to revisit and split the type (tracked as research-notes Q5 / Q3).

Examples

ga4 <- data.frame(
  url = c("https://x/a", "https://x/a", "https://x/b"),
  entrances = c(60, 30, 10)
)
# As a prior_df for pagerank() (it does the canonicalize + fold):
ga4_entrance_teleport(ga4)
#>           url weight
#> 1 https://x/a     90
#> 2 https://x/b     10

# Or align directly to a known final vertex set:
v <- c("https://x/a", "https://x/b", "https://x/c")
ga4_entrance_teleport(ga4, vertex_names = v, verbose = FALSE)
#> [1] 0.9 0.1 0.0