library("hyper2",quietly=TRUE)
## 
## Attaching package: 'hyper2'
## The following object is masked from 'package:stats':
## 
##     weights

Objects of class are a generalization of objects that allow the brackets to contain weighted probabilities. Likelihood functions are defined on non-negative \(p_1,\ldots p_n\) subject to the unit-sum constraint \(\sum p_i=1\). Given known weights \(w^i_j\) with \(1\leq i\leq j\) we have

\[\mathcal{L}\left(p_1,\ldots p_n\right)=\prod_j\left(\sum_{i=1}^n w^i_jp_i\right)^{n_j}.\]

As a motivating example, suppose two teams (players) with Bradley-Terry strengths \(p_1,p_2\) play football where we quantify the home-ground advantage with a term \(\lambda\). If \(p_1\) plays at home \(a+b\) times with \(a\) wins and \(b\) losses, and plays away [so \(p_2\) is at home] \(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=6,B=2,C=5,D=1\) and \(\lambda=1.3\) [assumed for the moment to be known], appropriate package idiom might be:

A <- 6 ; B <- 2 ; C <- 7 ; D <- 1
H <- hyper3()
H[c(p1=1.3)]      %<>% inc(A) 
H[c(p2=1)]        %<>% inc(B) 
H[c(p1=1.3,p2=1)] %<>% dec(A+B)
H[c(p1=1)]        %<>% inc(C) 
H[c(p2=1.3)]      %<>% inc(D) 
H[c(p1=1,p2=1.3)] %<>% dec(C+D)
H
## log( (p1=1)^7 * (p1=1, p2=1.3)^-8 * (p1=1.3)^6 * (p1=1.3, p2=1)^-8 *
## (p2=1)^2 * (p2=1.3)^1)

We may estimate \(p_1\) and \(p_2\) using maximum likelihood, maxp() in package idiom:

maxp(H)
##        p1        p2 
## 0.8157512 0.1842488

Further, we can test whether the players are in fact of equal strength:

equalp.test(H)
## 
##  Constrained support maximization
## 
## data:  H
## null hypothesis: p1 = p2
## null estimate:
##  p1  p2 
## 0.5 0.5 
## (argmax, constrained optimization)
## Support for null:  -11.49 + K
## 
## alternative hypothesis:  sum p_i=1 
## alternative estimate:
##        p1        p2 
## 0.8157512 0.1842488 
## (argmax, free optimization)
## Support for alternative:  -8.066979 + K
## 
## degrees of freedom: 1
## support difference = 3.423017
## p-value: 0.008883826

Showing convincingly that we may reject the null that \(p_1=p_2\) and assert that the players do in fact differ in strength.

Another motivating example might come from Plackett-Luce likelihood functions for order statistics. Suppose we have three players with nonnegative strengths \(p_\mathrm{M},p_\mathrm{RB},p_\mathrm{F}\), with unit sum. These players might be conceputalised as F1 constructors (here Mercedes (M), Red Bull (RB), and Ferrari (F) for the sake of argument). Each constructor fields two cars and the order statistic might be

\[ RB\succ M\succ F\succ F\succ RB\succ M\]

indicating that the finishing order was Red Bull first, Mercedes second, Ferrari third, and so on (this was in fact observed at the 2021 Emilia Romagna Grand Prix). The Placket-Luce likelihood function would be

\[ \frac{p_\mathrm{RB}}{p_\mathrm{RB}+p_\mathrm{M}+p_\mathrm{F}+p_\mathrm{F}+p_\mathrm{RB}+p_\mathrm{M}}\cdot \frac{p_\mathrm{M}}{ p_\mathrm{M}+p_\mathrm{F}+p_\mathrm{F}+p_\mathrm{RB}+p_\mathrm{M}}\cdot \frac{p_\mathrm{F}}{ p_\mathrm{F}+p_\mathrm{F}+p_\mathrm{RB}+p_\mathrm{M}}\cdot \frac{p_\mathrm{F}}{ p_\mathrm{F}+p_\mathrm{RB}+p_\mathrm{M}}\cdot \frac{p_\mathrm{RB}}{ p_\mathrm{RB}+p_\mathrm{M}}\cdot \frac{p_\mathrm{M}}{ p_\mathrm{M}} \]

or, in a form more suitable for the package,

\[ \frac{p_\mathrm{RB}}{2p_\mathrm{RB}+ 2p_\mathrm{M}+ 2p_\mathrm{F}}\cdot \frac{p_\mathrm{M}}{ p_\mathrm{RB}+ 2p_\mathrm{M}+ 2p_\mathrm{F}}\cdot \frac{p_\mathrm{F}}{ p_\mathrm{RB}+ p_\mathrm{M}+ 2p_\mathrm{F}}\cdot \frac{p_\mathrm{F}}{ p_\mathrm{RB}+ p_\mathrm{M}+ p_\mathrm{F}}\cdot \frac{p_\mathrm{RB}}{ p_\mathrm{RB}+ p_\mathrm{M}}\]

We could proceed as follows:

a <- hyper3()
a[c(R=1)] %<>% inc
a[c(R=2,M=2,F=2)] %<>% dec
a[c(M=1)] %<>% inc
a[c(R=1,M=2,F=2)] %<>% dec
a[c(F=1)] %<>% inc
a[c(R=1,M=1,F=2)] %<>% dec
a[c(F=1)] %<>% inc
a[c(R=1,M=1,F=1)] %<>% dec
a[c(R=1)] %<>% inc
a[c(R=1,M=1    )] %<>% dec
a
## log( (F=1)^2 * (F=1, M=1, R=1)^-1 * (F=2, M=1, R=1)^-1 * (F=2, M=2,
## R=1)^-1 * (F=2, M=2, R=2)^-1 * (M=1)^1 * (M=1, R=1)^-1 * (R=1)^2)

Or maybe more logically

b <- hyper3()
b["R"] %<>% inc ; b[c("R","M","F","F","R","M")] %<>% dec
b["M"] %<>% inc ; b[c(    "M","F","F","R","M")] %<>% dec
b["F"] %<>% inc ; b[c(        "F","F","R","M")] %<>% dec
b["F"] %<>% inc ; b[c(            "F","R","M")] %<>% dec
b["R"] %<>% inc ; b[c(                "R","M")] %<>% dec

a==b
## [1] TRUE

And then

ma <- maxp(a)
ma
##         F         M         R 
## 0.4307508 0.1754030 0.3938462

Evidence for different strengths?

equalp.test(a)
## 
##  Constrained support maximization
## 
## data:  a
## null hypothesis: F = M = R
## null estimate:
##         F         M         R 
## 0.3333333 0.3333333 0.3333333 
## (argmax, constrained optimization)
## Support for null:  -6.579251 + K
## 
## alternative hypothesis:  sum p_i=1 
## alternative estimate:
##         F         M         R 
## 0.4307508 0.1754030 0.3938462 
## (argmax, free optimization)
## Support for alternative:  -6.250462 + K
## 
## degrees of freedom: 2
## support difference = 0.3287895
## p-value: 0.7197945

No evidence agains the null of equal strengths. Further:

gradient(a,ma)  # should be small at the evaluate
## [1] 9.311945e-05 4.276493e-04