Implied Odds Probabilities (implied)#

This submodule provides a comprehensive toolkit for converting bookmaker odds into their underlying “true” probabilities. It achieves this by removing the bookmaker’s margin (the overround) using various statistical methods.

The primary entry point is the calculate_implied() function, which handles all calculations and returns a structured data object.

Quick Start#

Here’s a basic example of how to convert decimal odds into probabilities using the default multiplicative method.

import penaltyblog as pb

# Odds for a Home Win, Draw, and Away Win
odds = [2.7, 2.3, 4.4]

result = pb.implied.calculate_implied(odds)

print(f"Probabilities: {result.probabilities}")
print(f"Margin: {result.margin:.4f}")
print(f"Method Used: {result.method.value}")

Probabilities: [0.35873803615739097, 0.4211272598369373, 0.22013470400567173]
Margin: 0.0324
Method Used: multiplicative

Main Function#

All calculations are performed through this central function. It accepts various odds formats and allows you to specify the desired calculation method.

penaltyblog.implied.calculate_implied(
    odds: Union[List[float], List[str], OddsInput],
    method: Union[str, ImpliedMethod] = ImpliedMethod.MULTIPLICATIVE,
    odds_format: Union[str, OddsFormat] = OddsFormat.DECIMAL,
    market_names: Optional[List[str]] = None,
) -> ImpliedProbabilities

Description#

Calculate implied probabilities from odds using the specified method.

Parameters

  • odds (List[float] | List[str] | OddsInput): The odds to convert. Can be a list of values or an OddsInput object.

  • method (str | ImpliedMethod, optional): The method to use. Defaults to "multiplicative".

  • odds_format (str | OddsFormat, optional): The format of the provided odds. Defaults to "decimal".

  • market_names (List[str], optional): Names for each market outcome.

Returns

ImpliedProbabilities: A type-safe container with the calculated probabilities and metadata.

Data Models#

The submodule uses type-safe dataclasses for handling odds input and probability output. This ensures your code is clear, predictable, and less prone to errors.

OddsInput#

The OddsInput class is used to standardize various odds formats (Decimal, American, Fractional) before calculation. While it’s often used internally, you can instantiate it directly.

Attributes:

  • odds: The list of original odds.

  • odds_format: The format of the odds (e.g., OddsFormat.DECIMAL).

  • market_names: The names for each outcome.

Methods:

  • to_decimal(): Converts the stored odds to decimal format.

ImpliedProbabilities Output#

The ImpliedProbabilities class is the return type for all calculations. It’s a container holding the results and useful metadata.

Attributes:

  • probabilities: A list of the calculated “true” probabilities.

  • margin: The original margin (overround) from the bookmaker’s odds.

  • method: The method used for the calculation (e.g., ImpliedMethod.SHIN).

  • market_names: The names for each outcome.

  • method_params: A dictionary containing any special parameters returned by the method (e.g., Shin’s z or Power’s k).

Properties:

probabilities_dict: Returns the probabilities as a dictionary mapped to the market names.

Available Methods & Formats#

You can easily specify which calculation method to use and what format the input odds are in.

Calculation Methods#

The method parameter accepts a string or an ImpliedMethod enum member. Each method represents a different theory of how the bookmaker’s margin is applied.

  • MULTIPLICATIVE (default)

  • ADDITIVE

  • POWER

  • SHIN

  • DIFFERENTIAL_MARGIN_WEIGHTING

  • ODDS_RATIO

  • LOGARITHMIC

Odds Formats#

The odds_format parameter accepts a string or an OddsFormat enum member.

  • DECIMAL (default)

  • AMERICAN

  • FRACTIONAL

Advanced Usage#

Using Different Methods and Formats#

Here’s how to calculate probabilities from American odds using Shin’s method. This example also shows how to access method-specific parameters from the result.

import penaltyblog as pb
from penaltyblog.implied.models import ImpliedMethod, OddsFormat

american_odds = ["+170", "+130", "+340"]
market_names = ["Home", "Draw", "Away"]

result = pb.implied.calculate_implied(
    odds=american_odds,
    method=ImpliedMethod.SHIN,
    odds_format=OddsFormat.AMERICAN,
    market_names=market_names,
)

print(f"Shin's Probabilities: {result.probabilities}")

# Access method-specific parameters returned by some methods
if result.method_params and "z" in result.method_params:
    print(f"Shin's z parameter: {result.method_params['z']:.4f}")

Shin's Probabilities: [0.35934391959159157, 0.42324384818283234, 0.21741223222458853]
Shin's z parameter: 0.0162