kelly manual

Overview

The Kelly criterion is a formula from probability theory that determines the optimal fraction of a bankroll to wager on a bet with positive expected value. Given the probability of winning and the odds offered, the Kelly formula maximizes the expected logarithm of wealth over repeated bets — in other words, it is the strategy that produces the highest long-run growth rate.

kelly.el brings this calculation into Emacs. The package provides a single interactive command, kelly, which prompts for the win probability and the betting odds, then displays the recommended wager amount along with the expected net profit. All computation is done in the minibuffer: no external dependencies, no buffers, no files.

The package supports five different odds formats commonly used in sports betting and prediction markets: fractional (British), decimal (European), moneyline (American), implied probability, and implied percentage. It also supports fractional Kelly betting, a widely used risk-reduction strategy in which only a fixed fraction of the full Kelly recommendation is wagered.

The development repository is on GitHub.

Installation

Manual installation

Clone the repository and add its location to your load path:

(add-to-list 'load-path "path/to/kelly")
(require 'kelly)

Replace "path/to/kelly" with the actual path to your local clone.

Package managers

With any of the common package managers, add the appropriate form to your init file:

;; with vc (Emacs 30 or later)
(use-package kelly
  :vc (:url "https://github.com/benthamite/kelly"))

;; with elpaca
(use-package kelly
  :ensure (:host github :repo "benthamite/kelly"))

;; with straight
(use-package kelly
  :straight (:host github :repo "benthamite/kelly"))

;; with quelpa
(use-package kelly
  :quelpa (kelly :fetcher github :repo "benthamite/kelly"))

Requirements

kelly.el requires Emacs 25.1 or later. It has no external dependencies.

User options

All user options belong to the kelly customization group and can be configured interactively via M-x customize-group RET kelly RET or by setting them in your init file.

Odds format

The user option kelly-b-parameter-format controls which odds format the kelly command prompts for (Calculating the optimal wager). The b parameter in the Kelly formula represents the net odds received on a win; different betting traditions express the same information in different ways.

Five formats are supported:

fractional-odds (default)

Fractional (British) odds. A value of 3 means you receive 3 units of profit for every 1 unit wagered, plus your stake back.

decimal-odds

Decimal (European) odds. A value of 4.0 means a total return of 4 units per 1 unit wagered (equivalent to fractional odds of 3). Must be greater than 1.

moneyline-odds

Moneyline (American) odds. Positive values (e.g. +300) indicate profit on a 100-unit stake; negative values (e.g. -150) indicate how much you must stake to win 100 units.

implied-probability

The probability implied by the betting odds, expressed as a decimal between 0 and 1 exclusive (e.g. 0.25).

implied-percent

The same implied probability expressed as a percentage between 0 and 100 exclusive (e.g. 25).

The choice of format is purely a matter of convenience; all formats are converted internally to fractional odds before the Kelly calculation is performed.

;; Use decimal (European) odds
(setopt kelly-b-parameter-format 'decimal-odds)

Fractional Kelly

The user option kelly-fraction is a multiplier applied to the computed Kelly fraction. Its default value is 1, meaning the full Kelly recommendation is used.

In practice, the full Kelly criterion can lead to large swings in bankroll size, and many bettors prefer a more conservative approach. Setting kelly-fraction to a value between 0 and 1 scales the recommended wager down proportionally. For example, a value of 0.5 (“half Kelly”) recommends wagering half of what the full Kelly formula suggests.

;; Use half Kelly for a more conservative strategy
(setopt kelly-fraction 0.5)

The value must be a positive number. If it is zero, negative, or not a number, kelly-calculate signals an error (Core calculation).

Bankroll

The user option kelly-bankroll specifies the total amount of capital available for wagering. The Kelly criterion expresses its recommendation as a fraction of the bankroll, so this value is needed to translate the fraction into a concrete monetary amount.

The default value is nil. When nil, the kelly command prompts for a bankroll amount on the first invocation and stores the entered value in this variable for subsequent calls within the same session. If you want to avoid the prompt, set it in your init file:

(setopt kelly-bankroll 10000)

The user option kelly-bankroll-currency specifies the currency symbol displayed alongside monetary amounts in the output. The default value is "$". Change it to match your local currency:

(setopt kelly-bankroll-currency "EUR")

Commands

Calculating the optimal wager

The command kelly is the main entry point to the package. Invoke it with M-x kelly RET to calculate the optimal wager for a bet.

The command prompts for two inputs in sequence:

1. Win probability — your estimated probability that the bet will win, as a decimal between 0 and 1 exclusive. For example, enter 0.6 if you believe there is a 60% chance of winning.

2. Betting odds — the odds offered on the bet, in whatever format kelly-b-parameter-format is set to (Odds format).

After collecting these inputs, the command computes the Kelly fraction using kelly-calculate (Core calculation) and displays a message in the echo area with two pieces of information:

• The amount to wager, shown as both an absolute monetary value and a percentage of the bankroll.
• The expected net profit, shown as both an absolute value and as a return-on-investment percentage.

If the Kelly fraction is zero or negative — meaning the bet has non-positive expected value at the given odds — the command instead displays a message advising against wagering.

Here is an example session using the default settings (fractional odds, full Kelly, $1000 bankroll):

1. M-x kelly RET
2. Win probability: 0.6 RET
3. Fractional odds: 2 RET

The output might read:

Amount to wager: $400.00 (40.00% of bankroll). Expected net profit: $320.00 (80.00% return on investment).

Functions

The following public functions are available for programmatic use. They allow you to integrate Kelly criterion calculations into custom Elisp workflows without going through the interactive prompts.

Core calculation

The function kelly-calculate takes two arguments: a win probability p (a number between 0 and 1) and net fractional odds b (a positive number). It returns the Kelly fraction scaled by kelly-fraction (Fractional Kelly).

The underlying formula is:

The function validates its inputs: it signals an error if b is zero (which would cause division by zero) or if kelly-fraction is not a positive number.

;; 60% win probability, 2:1 fractional odds, full Kelly
(let ((kelly-fraction 1))
  (kelly-calculate 0.6 2))  ; => 0.4

Expected value and wager sizing

The function kelly-get-expectation computes the expected net profit per unit wagered, given a win probability p and net odds b. The formula is p * b - (1 - p). A positive return value indicates a bet with positive expected value.

The function kelly-get-wager-amount multiplies the Kelly fraction by the bankroll to produce the absolute wager amount.

Bankroll management

The function kelly-get-bankroll returns the current value of kelly-bankroll (Bankroll). If kelly-bankroll is nil, it prompts the user via kelly-read-bankroll and stores the result.

The function kelly-read-bankroll prompts interactively for a positive bankroll amount without modifying any global variable. It can be called directly if you want to update the bankroll mid-session:

(setopt kelly-bankroll (kelly-read-bankroll))

Odds conversion

Each odds format has a dedicated reader function that prompts the user for input and returns the equivalent fractional odds value. These are:

• kelly-read-fractional-odds — Reads fractional odds directly (must be positive).
• kelly-read-decimal-odds — Reads decimal odds (must be greater than 1) and subtracts 1 to convert to fractional.
• kelly-read-moneyline-odds — Reads moneyline odds (any non-zero number) and converts to fractional.
• kelly-read-implied-probability — Reads a probability between 0 and 1 exclusive and converts to fractional odds via (1 - p) / p.
• kelly-read-implied-percent — Reads a percentage between 0 and 100 exclusive and converts to fractional odds via (100 - pct) / pct.

All reader functions validate their input in a loop, re-prompting if the entered value is out of range. The appropriate reader is selected automatically by kelly-read-b based on the value of kelly-b-parameter-format (Odds format).