hyper3 function

Weighted probability vectors: hyper3 objects

Objects of class hyper3 are a generalization of hyper2 objects that allow the brackets to contain weighted probabilities.

As a motivating example, suppose two players with Bradley-Terry strengths $p_1,p_2$ play chess where we quantify the first-mover advantage with a term $omitted$. If $p_1$ plays white $a+b$ times with $a$ wins and $b$ losses, and plays black $c+d$ times with $c$ wins and $d$

losses, then a sensible likelihood function might be

[REMOVE_ME]$\left(\frac{\lambda p_1}{\lambda p_1 + p_2}\right)^{a}\left(\frac{p_2 }{\lambda p_1 + p_2}\right)^{b}\left(\frac{p_1 }{p_1 + \lambda p_2}\right)^{c}\left(\frac{\lambda p_2}{p_1 + \lambda p_2}\right)^{d}omitted: see PDF [REMOVE_ME_2]$

If $a=1,b=2,c=3,d=4$ and $omitted$ appropriate package idiom might be:

H <- hyper3()
H[c(p1=1.3)]      %<>% inc(1) # a=1
H[c(p2=1)]        %<>% inc(2) # b=2
H[c(p1=1.3,p2=1)] %<>% dec(3) # a+b=1+2=3
H[c(p1=1)]        %<>% inc(3) # c=3
H[c(p2=1.3)]      %<>% inc(4) # d=4
H[c(p1=1,p2=1.3)] %<>% dec(7) # c+d=3+4=7
H
> log( (p1=1)^3 * (p1=1, p2=1.3)^-7 * (p1=1.3)^1 * (p1=1.3, p2=1)^-3 *
(p2=1)^2 * (p2=1.3)^4)

The general form of terms of a hyper3 object would be $omitted$; the complete object would be

[REMOVE_ME]$\mathcal{L}\left(p_1,\ldots,p_n\right)=\prod_{j=1}^N\left(\sum_{i=1}^nw_{ij}p_i\right)^{\alpha_i}omitted: see PDF [REMOVE_ME_2]$

where we understand that $omitted$; many of the weights might be zero. We see that the weights $w_ij$ may be arranged as a matrix and this form is taken by function hyper3_m().

Description

Objects of class hyper3 are a generalization of hyper2 objects that allow the brackets to contain weighted probabilities.

As a motivating example, suppose two players with Bradley-Terry strengths $p_1,p_2$ play chess where we quantify the first-mover advantage with a term $omitted$. If $p_1$ plays white $a+b$ times with $a$ wins and $b$ losses, and plays black $c+d$ times with $c$ wins and $d$

losses, then a sensible likelihood function might be

$$\left(\frac{\lambda p_1}{\lambda p_1 + p_2}\right)^{a}\left(\frac{p_2 }{\lambda p_1 + p_2}\right)^{b}\left(\frac{p_1 }{p_1 + \lambda p_2}\right)^{c}\left(\frac{\lambda p_2}{p_1 + \lambda p_2}\right)^{d}omitted: see PDF$$

If $a=1,b=2,c=3,d=4$ and $omitted$ appropriate package idiom might be:

H <- hyper3()
H[c(p1=1.3)]      %<>% inc(1) # a=1
H[c(p2=1)]        %<>% inc(2) # b=2
H[c(p1=1.3,p2=1)] %<>% dec(3) # a+b=1+2=3
H[c(p1=1)]        %<>% inc(3) # c=3
H[c(p2=1.3)]      %<>% inc(4) # d=4
H[c(p1=1,p2=1.3)] %<>% dec(7) # c+d=3+4=7
H
> log( (p1=1)^3 * (p1=1, p2=1.3)^-7 * (p1=1.3)^1 * (p1=1.3, p2=1)^-3 *
(p2=1)^2 * (p2=1.3)^4)

The general form of terms of a hyper3 object would be $omitted$; the complete object would be

$$\mathcal{L}\left(p_1,\ldots,p_n\right)=\prod_{j=1}^N\left(\sum_{i=1}^nw_{ij}p_i\right)^{\alpha_i}omitted: see PDF$$

where we understand that $omitted$; many of the weights might be zero. We see that the weights $w_ij$ may be arranged as a matrix and this form is taken by function hyper3_m().

hyper3(B = list(), W = list(), powers = 0, pnames)
hyper3_bw(B = list(), W = list(), powers = 0, pnames)
hyper3_nv(L=list(),powers=0,pnames)
hyper3_m(M,p,stripzeros=TRUE)

Arguments

• B: A list of brackets
• W: A list of weights
• L: A list of named vectors
• powers: Numeric vector of powers
• pnames: Character vector of player names
• M: Matrix of weights, column names being player names
• p: Vector of powers, length equal to ncol(M)
• stripzeros: Boolean with default TRUE meaning to silently remove all-zero rows of M

Details

• Function hyper3() is the user-friendly creation method, which dispatches to a helper function depending on its arguments.

• Function hyper3_bw() takes a list of brackets (character vectors) and a list of weights (numeric vectors) and returns a hyper3 object.

• Function hyper3_nv() takes a list of named vectors and returns a hyper3 object.

• Function hyper3_m() takes a matrix with rows being the brackets (entries are weights) and a numeric vector of powers.

• Function evaluate3() is a low-level helper function that evaluates a log-likelihood at a point in probability space. Don't use this: use the user-friendly loglik() instead, which dispatches to evaluate3().

• Function maxp3() is a placeholder (it is not yet written). But the intention is that it will maximize the log-likelihood of a hyper3 object over the Bradley Terry strengths and any weights given. This might not be possible as envisaged right now; I present some thoughts in inst/kka.Rmd.

• Function list2nv() converts a list of character vectors into a named vector suitable for use as argument e of function cheering3(). It is used in inst/global_liveability_ranking.Rmd.

• Function as.namedvectorlist() takes a hyper3

  object and returns a disoRdered list of named vectors corresponding to the brackets and their weights.

• Function setweight() alters the weight of every occurrence of a set of players. It is vectorised, so setweight(H,c("a","b"),88:89) sets the weight of a to 88 and b to 89. Replacement methods are defined, so ‘H["a"] \<- as.weight(3)’ will set the weight of every occurrence of player a to 3. If H is a hyper2

  object, it will be coerced to hyper3.

Returns

Generally return or deal with hyper3 objects

Author(s)

Robin K. S. Hankin

Note

Functionality for hyper3 objects is generally indicated by adding a ‘3’ to function names, eg gradient() goes to gradient3().

See Also

hyper2

Examples

hyper3(B=list("a",c("a","b"),"b"),W=list(1.2,c(1.2,1),1),powers=c(3,4,-7))
hyper3(list(c(a=1.2),c(b=1),c(a=1.2,b=1)),powers=c(3,4,-7))
## Above two objects should be identical.

## Third method, send a matrix:
M <- matrix(rpois(15,3),5,3)
colnames(M) <- letters[1:3]
hyper3(M,c(2,3,-1,-5,1))   # second argument interpreted as powers


## Standard way to generate a hyper3 object is to create an empty object
## and populate it using the replacement methods:

a <- hyper3()  # default creation method [empty object]

a[c(p1=1.3)] <- 5
a[c(p2=1  )] <- 2
a[c(p1=1.3,p2=1)] <- -7
a

chess3  # representative simple hyper3 object

H1 <- rankvec_likelihood(letters[sample(6)])
H2 <- rankvec_likelihood(letters[sample(6)])
H1["a"] <- as.weight(1.2)         # "a" has some disadvantage in H1
H1[c("b","c")] <- as.weight(2:3)  # "b" and "c" have some advantage in H1
H2[c("c","d")] <- as.weight(1.5)  # "c" and "d" have some advantage in H2
H1+H2