Package {winning}

Calibrate abilities from observed shares

Description

Inverts the factor-race share map by damped coordinate Newton against the frozen shared field, with analytic slopes and an independent-race warm start. Shares determine abilities uniquely up to a common shift.

Usage

abilities_from_probabilities_factor(p, V, D, nodes = NULL,
  n_iter = 50, tol = 1e-6, points = 501)

Arguments

Value

Mean-zero ability vector (min-wins convention).

Block, nested and tree races

Description

Clustered covariance grammars of the general race: independent cluster effects (block), block plus one global factor (nested, interpolated by gamma), and a hierarchy of uniform shared effects (tree, two message passes). Across-cluster independence factorizes the survival field, so cost is O(n x lattice x nodes) regardless of the number of blocks. Base-R ports of the python reference, parity-locked.

Usage

block_race_probabilities(mu, cluster, loading, D, points = 257, qa = 9)

nested_race_probabilities(mu, cluster, loading, D, coupling = NULL,
  gamma = 1, points = 257, qa = 9, qf = 15)

tree_race_probabilities(mu, cluster, loading, D, parent, strength,
  points = 257, qa = 9)

block_race_jacobian(mu, cluster, loading, D, points = 257, qa = 9)

nested_race_jacobian(mu, cluster, loading, D, coupling = NULL, gamma = 1,
  points = 257, qa = 9, qf = 15)

abilities_from_block_race(p, cluster, loading, D, points = 257, qa = 9,
  tol = 1e-10, max_iter = 25)

tree_race_jacobian(mu, cluster, loading, D, parent, strength,
  points = 257, qa = 9)

Arguments

Value

Probability vectors summing to one; Jacobians as n x n matrices with zero row sums (off-diagonals are symmetric tie densities); abilities_from_block_race a list(mu, residual, iterations).

The horse race problem: ability from win probabilities, and back

Description

Given win probabilities for a multi-entrant contest in which every contestant's performance is a translated copy of one density, infer the translations (relative ability), or price the contest in the forward direction, with dead heats handled exactly. Implements the lattice fixed-point algorithm of Cotton (2021), doi:10.1137/19M1276261; this is a base-R port of the reference python package winning.

Usage

dividend_implied_ability(dividends, density, nan_value = 2000, unit = 1.0)

state_price_implied_ability(prices, density, unit = 1.0)

ability_implied_state_prices(ability, density, unit = 1.0)

ability_implied_dividends(ability, density, unit = 1.0)

solve_for_implied_offsets(prices, density, offset_samples = NULL,
  implied_offsets_guess = NULL, n_iter = 3)

Arguments

Value

The *_implied_ability functions return numeric abilities (lower is better) in units of unit; ability_implied_state_prices returns state prices; ability_implied_dividends their inverses; solve_for_implied_offsets raw lattice offsets.

Examples

d <- skew_normal_density(L = 200, unit = 0.02, a = 1.5)
ability <- dividend_implied_ability(c(2, 6, 6, 20), d)
p <- ability_implied_state_prices(ability, d)

Pruned product Gauss-Hermite nodes

Description

Golub-Welsch nodes of the probabilists' Hermite rule for expectations over a standard k-variate normal, as a pruned product grid.

Usage

hermite_nodes(k, order = 15, prune = 1e-7)

Arguments

Value

A list with matrix F (nodes by k) and weight vector W.

Polish a race onto linear constraints

Description

Weights ARE race probabilities, and finance imposes linear constraints on them; clipping and renormalizing breaks model-consistency. The right object is the nearest race satisfying the constraints, found by an augmented-Lagrangian on the exact race Jacobian (the python reference uses SLSQP; the two agree to optimizer tolerance).

Usage

polish_race(p0 = NULL, mu0 = NULL, V = NULL, D = NULL, F = NULL,
  W = NULL, base = "normal", points = 257, name_caps = NULL,
  groups = NULL, A = NULL, b = NULL, tol = 1e-09, max_iter = 60,
  structure = NULL)

race_jacobian(mu, V = NULL, D = NULL, F = NULL, W = NULL,
  base = "normal", points = 501, structure = NULL, qa = 9, qf = 15)

concentration_matrix(n, name_caps = NULL, groups = NULL)

Arguments

Value

polish_race: list(p, mu, info) – a probability vector that IS the race at mu, satisfying the caps, with mu as close to mu0 as the constraints allow. race_jacobian: the exact n x n d p / d mu. concentration_matrix: list(A, b).

Examples

p0 <- c(0.4, 0.25, 0.2, 0.15)
out <- polish_race(p0 = p0, D = rep(1, 4), name_caps = 0.3)
max(out$p)  # <= 0.3

Convert between dividends and probabilities

Description

Naive renormalization between Australian-style dividends (decimal prices) and risk-neutral win probabilities.

Usage

prices_from_dividends(dividends, nan_value = 2000)

dividends_from_prices(prices, multiplicity = 1.0)

Arguments

Value

Numeric vector: normalized probabilities, or dividends.

The general race: one API, distributions and correlation as parameters

Description

Win probabilities of the general Gaussian (or gumbel, or custom-base) race, all N in one shared-field lattice pass, and the inverse map from probabilities to abilities. With base = "gumbel" and D = pi^2/6 the race is exactly softmax. Base-R port of the python reference; parity/vectors.json pins the two to machine precision.

Usage

race_probabilities(mu, V = NULL, D = NULL, F = NULL, W = NULL,
  base = "normal", points = 257, return_slopes = FALSE, structure = NULL,
  window = "bulk", delta = 1e-12, qa = 9, qf = 15, nodes = NULL)

abilities_from_race(p, V = NULL, D = NULL, F = NULL, W = NULL,
  base = "normal", points = 257, n_iter = 60, tol = 1e-08,
  structure = NULL, qa = 9, qf = 15)

calibrate_abilities(p, V = NULL, D = NULL, F = NULL, W = NULL,
  base = "normal", points = 257, n_iter = 60, tol = 1e-08,
  structure = NULL, qa = 9, qf = 15)

Arguments

Value

race_probabilities: probabilities summing to one (or list(p, slopes)). abilities_from_race and its alias calibrate_abilities: the mean-zero ability vector reproducing p.

Examples

p <- race_probabilities(c(-0.5, 0, 0.8))
mu <- calibrate_abilities(c(0.5, 0.3, 0.2))
s <- Blocks(cluster = c(1, 1, 2, 2), loading = rep(0.4, 4), D = rep(1, 4))
pb <- race_probabilities(c(-0.3, 0, 0.1, 0.2), structure = s)

Skew-normal performance density on a symmetric lattice

Description

The reference performance distribution of the horse race problem: proportional to 2/scale * dnorm(t) * pnorm(a t), normalized and centered on the lattice.

Usage

skew_normal_density(L, unit, loc = 0, scale = 1.0, a = 2.0)

Arguments

Value

Numeric density of length 2L+1.

Lattice race primitives

Description

The two primitives of the lattice race: the distribution of the winning (minimum) time of a field, with exact dead-heat multiplicity tracking, and the state prices of translated copies of a common density.

Usage

state_prices_from_offsets(density, offsets)

winner_of_many(densities)

Arguments

Value

state_prices_from_offsets returns the expected payoff of each contestant against the field (1 if strictly first, split on dead heats). winner_of_many returns a list with the density of the minimum of the field and the dead-heat multiplicity lattice.

One race, five covariance grammars

Description

Every model in this package is the SAME Gaussian min-race, Y = mu + noise; these constructors are declarative descriptions of the noise covariance admitting O(N)-per-lattice-point evaluation: Sigma = diag(D); V V' + diag(D); block-diagonal rank-1 + diag; blocks plus a global factor dialed by gamma; a hierarchy of uniform shared effects. Independent = Blocks with zero loadings; Blocks = Tree of depth 1.

Usage

Independent(D)

Factor(V, D)

Blocks(cluster, loading, D)

Nested(cluster, loading, D, coupling, gamma = 1)

Tree(cluster, loading, D, parent, strength)

Arguments

Value

A structure object for the structure= argument of race_probabilities, abilities_from_race, race_jacobian and polish_race.

The tree race implied by a hierarchical clustering

Description

Builds the tree race whose implied correlation is EXACTLY the cophenetic correlation matrix 1 - 2 d^2 of the clustering (HRP's implicit covariance): each merge at height h contributes lam^2 = rho - rho_parent with rho = 1 - 2 h^2. Pass the result as structure= to race_probabilities or polish_race to price or polish along the dendrogram.

Usage

tree_from_linkage(Z)

tree_from_hclust(hc)

Arguments

Value

A Tree structure with unit total variance per runner.

Examples

hc <- hclust(dist(matrix(rnorm(40), 8, 5)) / 10, method = "average")
tr <- tree_from_hclust(hc)
p <- race_probabilities(rnorm(8), structure = tr)

All win probabilities of a factor Gaussian race

Description

Computes every P(X_i = min_j X_j) for X = mu + V f + sqrt(D) eps in one shared-lattice pass per factor node: conditional on f the alternatives are independent, the product of all survival functions is built once, and each alternative's own factor is divided back out.

Usage

win_probabilities_factor(mu, V, D, nodes = NULL, points = 501)

Arguments

Value

Vector of win probabilities summing to one.

Examples

p <- win_probabilities_factor(c(0, .5, 1), matrix(rnorm(6, 0, .3), 3), rep(1, 3))