hyper3 {hyper2}

Weighted probability vectors: hyper3 objects

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 \lambda. 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}

If a=1,b=2,c=3,d=4 and \lambda=1.3 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 \left(w_1p_1+\cdots+w_rp_r\right)^{\alpha}; the complete object would be

\mathcal{L}\left(p_1,\ldots,p_n\right)= \prod_{j=1}^N\left(\sum_{i=1}^n w_{ij}p_i\right)^{\alpha_i}

where we understand that p_n=1-\sum_{i=1}^{n-1}p_i; 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().

Usage

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.

Value

Generally return or deal with hyper3 objects

Note

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

Author(s)

Robin K. S. Hankin

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