API Reference
Complete Python API reference for the thurstone package. This covers all public classes, functions, and constants exported from the main package.
Table of Contents
Core Classes
The fundamental building blocks for Thurstone models: lattices for discretization, densities for performance distributions, and races for competitive scenarios.
UniformLattice
UniformLattice(L: int, unit: float)
Represents a uniform discretization lattice centered at zero. Used as the foundation for all density computations.
Parameters
| Name | Type | Description |
|---|---|---|
| L | int | Half-width: number of steps on one side of zero |
| unit | float | Spacing between consecutive lattice points |
Properties
size → int
Total number of lattice points: 2*L + 1
grid → np.ndarray
Array of actual lattice point values: unit * np.linspace(-L, L, size)
Methods
index_grid() → np.ndarray
Array of integer indices: np.arange(-L, L+1)
assert_compatible(arr: np.ndarray) → None
Validates that an array has compatible shape for this lattice
Density
Density(lattice: UniformLattice, p: np.ndarray)
A lattice-aligned probability measure representing a performance distribution. Automatically normalizes on construction.
Parameters
| Name | Type | Description |
|---|---|---|
| lattice | UniformLattice | The underlying discretization lattice |
| p | np.ndarray | Probability mass function values (automatically normalized) |
Methods
cdf() → np.ndarray
Cumulative distribution function
mean() → float
Expected value of the distribution
shift_fractional(offset: float) → Density
Shift the distribution by a fractional lattice offset (with interpolation)
dilate(scale: float) → Density
Scale the distribution variance by a factor
convolve(other: Density) → Density
Convolve with another density (sum of independent random variables)
approx_support(tol: float = 1e-12) → tuple[float, float]
Approximate support bounds where density exceeds tolerance
Race
Race(densities: List[Density])
Represents a competitive race between multiple contestants, each with their own performance density.
Parameters
| Name | Type | Description |
|---|---|---|
| densities | List[Density] | Performance distributions for each contestant |
Methods
state_prices() → np.ndarray
Winning probabilities for each contestant
dividends() → np.ndarray
Fair dividend odds: 1.0 / state_prices()
winner_density() → Density
Density of the winning performance (minimum across all contestants)
StatePricer
StatePricer(base_density: Density, offsets: List[float])
High-level interface for pricing races where contestants differ only by ability offsets from a common base distribution.
Parameters
| Name | Type | Description |
|---|---|---|
| base_density | Density | Base performance distribution |
| offsets | List[float] | Ability offsets for each contestant |
Methods
prices() → np.ndarray
Winning probabilities
dividends() → np.ndarray
Fair dividend odds
Calibration & Inference
Tools for inverse problems: inferring latent abilities from observed market prices or race outcomes.
AbilityCalibrator
AbilityCalibrator(base: Density, ...)
Calibrates ability offsets from observed state prices. Supports both 1D (location-only) and 2D (location + scale) inference.
Key Parameters
| Name | Type | Description |
|---|---|---|
| base | Density | Base performance distribution |
| scales | np.ndarray | None | Per-runner scale parameters for 2D calibration |
| n_iter | int | Number of refinement iterations (default: 3) |
Methods
calibrate(state_prices: List[float]) → np.ndarray
Infer ability offsets from observed winning probabilities
calibrate_2d(state_prices: List[float]) → tuple[np.ndarray, np.ndarray]
Infer both location and scale parameters. Returns (locations, scales)
GlobalAbilityCalibrator
GlobalAbilityCalibrator(base: Density, ...)
Multi-race calibration: fit a single ability vector across multiple races sharing common contestants.
Methods
fit_races(race_data: List[dict]) → np.ndarray
Fit global abilities from multiple race observations
KalmanAbilityTracker
KalmanAbilityTracker(base: Density, ...)
Dynamic ability tracking using Kalman filtering for time-varying performance.
Methods
update(state_prices: List[float], contestants: List[int]) → None
Update ability estimates with new race observation
get_abilities() → np.ndarray
Current ability estimates
Cube-to-Simplex Diffeomorphisms
Mathematical mappings from the unit k-cube to the k-simplex using racing dynamics, with quality assessment and optimization tools.
SigmoidParams
SigmoidParams(alpha: float, beta: float, gamma: float)
Parameters for a sigmoid mapping function: f(x) = alpha * sigmoid(beta * (x - gamma))
Parameters
| Name | Type | Description |
|---|---|---|
| alpha | float | Scale parameter (output range) |
| beta | float | Steepness parameter (transition sharpness) |
| gamma | float | Shift parameter (inflection point location) |
Methods
__call__(x: float) → float
Apply the sigmoid transformation to input x
CubeToSimplexMapping
CubeToSimplexMapping(sigmoid_params: List[SigmoidParams], lattice: UniformLattice = None)
A smooth diffeomorphism from [0,1]^k to the k-simplex using Thurstone racing dynamics.
Parameters
| Name | Type | Description |
|---|---|---|
| sigmoid_params | List[SigmoidParams] | Sigmoid parameters for each dimension |
| lattice | UniformLattice | Discretization lattice (uses default if None) |
Methods
__call__(cube_point: np.ndarray) → np.ndarray
Map a point from unit cube to simplex
jacobian(cube_point: np.ndarray) → np.ndarray
Compute the Jacobian matrix at the given point
batch_transform(cube_points: np.ndarray) → np.ndarray
Transform multiple points efficiently
QualityMetrics
QualityMetrics(symmetry_score: float, ...)
Container for various diffeomorphism quality assessment metrics.
Attributes
| Name | Type | Description |
|---|---|---|
| symmetry_score | float | Measure of mapping symmetry preservation |
| volume_preservation_score | float | None | How well the mapping preserves volume |
| smoothness_score | float | None | Smoothness of the transformation |
| coverage_score | float | None | How well the mapping covers the target simplex |
| invertibility_score | float | None | How close to invertible the mapping is |
Methods
overall_score(weights: dict = None) → float
Compute weighted average of all available metrics
Optimization Functions
comprehensive_quality_assessment(mapping: CubeToSimplexMapping, **kwargs) → QualityMetrics
Perform comprehensive quality assessment of a diffeomorphism mapping.
Parameters
| Name | Type | Description |
|---|---|---|
| mapping | CubeToSimplexMapping | The mapping to assess |
| symmetry_samples | int | Number of samples for symmetry test (default: 1000) |
| volume_samples | int | Number of samples for volume test (default: 100) |
| random_seed | int | Random seed for reproducible results |
optimize_diffeomorphism(target_metrics: QualityMetrics, bounds: ParameterBounds, **kwargs) → OptimizationResult
Optimize sigmoid parameters to achieve target quality metrics.
Parameters
| Name | Type | Description |
|---|---|---|
| target_metrics | QualityMetrics | Target quality metrics to optimize toward |
| bounds | ParameterBounds | Parameter bounds for optimization |
| method | str | Optimization method (default: 'differential_evolution') |
| maxiter | int | Maximum optimization iterations |
Constants & Conventions
Standard parameter sets and conventions used throughout the package.
Lattice Conventions
| Name | Value | Description |
|---|---|---|
| STD_L | 100 | Standard half-width for lattices |
| STD_UNIT | 0.04 | Standard lattice spacing |
| STD_SCALE | 1.0 | Standard scale parameter |
| STD_A | 0.0 | Standard skew parameter |
Alternative Conventions
| Name | Value | Description |
|---|---|---|
| ALT_L | 200 | Alternative (finer) half-width |
| ALT_UNIT | 0.02 | Alternative (finer) lattice spacing |
| ALT_SCALE | 1.2 | Alternative scale parameter |
| ALT_A | 0.1 | Alternative skew parameter |
Special Values
| Name | Value | Description |
|---|---|---|
| NAN_DIVIDEND | float('nan') | Placeholder for undefined dividend values |
Usage Examples
Basic Race Pricing
import thurstone as th
# Create a standard lattice and base density
lattice = th.UniformLattice(L=th.STD_L, unit=th.STD_UNIT)
base = th.Density.standard_normal(lattice)
# Price a 3-runner race with different ability offsets
pricer = th.StatePricer(base, offsets=[0.0, 0.5, -0.3])
prices = pricer.prices() # [0.45, 0.35, 0.20]
dividends = pricer.dividends() # [2.22, 2.86, 5.00]
Ability Calibration
# Infer abilities from observed market prices
calibrator = th.AbilityCalibrator(base)
observed_prices = [0.4, 0.3, 0.3]
inferred_abilities = calibrator.calibrate(observed_prices)
# Returns ability offsets that reproduce the observed prices
Cube-to-Simplex Mapping
# Create a 2D cube-to-simplex mapping
sigmoid_params = [
th.SigmoidParams(alpha=1.2, beta=4.0, gamma=0.5),
th.SigmoidParams(alpha=1.2, beta=4.0, gamma=0.5)
]
mapping = th.CubeToSimplexMapping(sigmoid_params)
# Transform a unit square point to triangle
cube_point = [0.3, 0.7]
simplex_point = mapping(cube_point) # [0.25, 0.35, 0.40]
assert abs(sum(simplex_point) - 1.0) < 1e-10
# Assess quality
metrics = th.comprehensive_quality_assessment(mapping)
print(f"Symmetry score: {metrics.symmetry_score:.3f}")