Transform Edge Weights Per Source (Grouped)

Applies a weight transformation within each source page's outgoing choice set, rather than across one global vector. Link ranks and transition weights are normally meaningful relative to the other links on the same source page: a "position 1" link on page A and a "position 1" link on page B should each be top-of-choice-set for their own source. A global rank (as computed by transform_weights) conflates them; this helper computes the transform separately within each by group.

In addition to the transformed weight, it returns a normalized transition_probability that sums to 1 within each by group, so the per-source choice distribution can be inspected and validated before it reaches the solver (igraph re-normalizes edge strengths internally, but that normalization is not otherwise visible to the user).

Usage

transform_edge_weights(
  edge_list_df,
  value_col,
  by = "from",
  method = c("zipf", "none", "rank_linear", "log", "minmax", "percentile"),
  weight_col = "weight",
  prob_col = "transition_probability",
  ...
)

Arguments

edge_list_df

A data frame of edges. Must contain the column named by by and the column named by value_col.

value_col

Character, the name of the column holding the raw numeric signal to transform (e.g. link positions, GA4 click counts).

by

Character, the name of the grouping column defining each choice set. Default "from" (the source page). May name multiple columns to group by their combination.

method

Character, the transformation strategy, passed through to transform_weights. One of "none", "rank_linear", "zipf", "log", "minmax", "percentile". Default "zipf".

weight_col

Character, the name of the output column to hold the transformed weight. Default "weight".

prob_col

Character, the name of the output column to hold the per-source normalized transition_probability. Default "transition_probability".

...

Additional arguments forwarded to transform_weights (e.g. alpha, offset, floor_value, descending).

Value

The input data frame with two columns added (or overwritten): weight_col (the per-source transformed weight) and prob_col (the per-source transition probability, summing to 1 within each by group across non-NA weights). Row order is preserved.

Details

The transform is applied independently per group by calling transform_weights on each group's slice of value_col – it reuses, rather than re-implements, the existing methods. transition_probability is then formed by dividing each group's transformed weights by their group sum. NA transformed weights (e.g. from NA inputs) are carried through and excluded from the probability total. A group whose transformed weights sum to zero (or are all NA) yields NA probabilities for that group, since no meaningful distribution can be formed.

See also

transform_weights for the single-vector (global) transform and the full description of each method.

Examples

# Two source pages, each with its own link positions (1 = top)
edges <- data.frame(
  from = c("A", "A", "A", "B", "B"),
  to = c("B", "C", "D", "C", "D"),
  position = c(1, 2, 3, 1, 2)
)

# Zipf weights computed within each source's choice set
transform_edge_weights(edges, "position",
  method = "zipf", descending = FALSE
)
#>   from to position    weight transition_probability
#> 1    A  B        1 1.0000000              0.5454545
#> 2    A  C        2 0.5000000              0.2727273
#> 3    A  D        3 0.3333333              0.1818182
#> 4    B  C        1 1.0000000              0.6666667
#> 5    B  D        2 0.5000000              0.3333333

# The transition_probability column sums to 1 within each `from`