hyper3: Weighted probability vectors: 'hyper3' objects

In RobinHankin/hyper2: The Hyperdirichlet Distribution, Mark 2

Weighted probability vectors: hyper3 objects

Description

\loadmathjax

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 \mjseqnp_1,p_2 play chess where we quantify the first-mover advantage with a term \mjeqn\lambdaomitted. If \mjseqnp_1 plays white \mjseqna+b times with \mjseqna wins and \mjseqnb losses, and plays black \mjseqnc+d times with \mjseqnc wins and \mjseqnd losses, then a sensible likelihood function might be

\mjdeqn \left

(\frac\lambda p_1\lambda p_1 + p_2\right)^a \left(\fracp_2 \lambda p_1 + p_2\right)^b \left(\fracp_1 p_1 + \lambda p_2\right)^c \left(\frac\lambda p_2p_1 + \lambda p_2\right)^d omitted: see PDF

If \mjseqna=1,b=2,c=3,d=4 and \mjeqn\lambda=1.3omitted 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 \mjeqn\left(w_1p_1+...+w_rp_r\right)^\alphaomitted; the complete object would be

\mjdeqn \mathcal

L\left(p_1,...,p_n\right)= \prod_j=1^N\left(\sum_i=1^n w_ijp_i\right)^\alpha_i omitted: see PDF

where we understand that \mjeqnp_n=1-\sum_i=1^n-1p_iomitted; many of the weights might be zero. We see that the weights \mjeqnw_ijw_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(2.1)  # "a" has some advantage
H2["b"] <- as.weight(0.8)  # "b" has some disadvantage
H1+H2

RobinHankin/hyper2 documentation built on April 21, 2024, 11:38 a.m.