Kolmo Stats API

Overview

kolmo-stats is the package name on pip. kolmo_stats is the Python import module. The library is built for analysts, traders, and risk teams working with crude oil, refined products, natural gas, LNG, and related derivatives.

Install

pip install kolmo-stats

Requires Python 3.10 or newer. Runtime dependencies are numpy, pandas, scipy, and networkx.

Import a few functions

from kolmo_stats import crack_spread, curve_shape, historical_var
from kolmo_stats import npv, breakeven_price, lng_arbitrage

Intent: keep imports explicit. The package is designed for readable scripts and notebooks.

Quickstart

import numpy as np
from kolmo_stats import (
    crack_spread, curve_shape, curve_slope,
    historical_var, npv, breakeven_price, lng_arbitrage,
)

# Brent forward curve
brent = {"M1": 84.5, "M2": 83.2, "M3": 82.1, "M6": 80.5, "M12": 78.0}
print(curve_shape(brent))  # "backwardation"
print(curve_slope(brent))  # negative means backwardation

# Refinery margin
crack = crack_spread(crude=80, gasoline=103, distillate=110, ratio="3-2-1")
print(f"3-2-1 crack: ${crack:.2f}/bbl")

# LNG arbitrage
arb = lng_arbitrage(
    14.0,
    3.5,
    freight_cost=2.0,
    liquefaction_cost=2.5,
    regas_cost=0.3,
    boil_off_cost=0.2,
)
print(f"LNG arb: ${arb:.2f}/MMBtu")

# Historical VaR
returns = np.random.randn(500) * 2
print(f"VaR 95%: ${historical_var(returns):,.0f}")

# Project NPV
cashflows = [80, 120, 140, 130, 110, 90, 70, 50, 30]
print(f"NPV: ${npv(cashflows, discount_rate=0.12, initial_investment=400):.1f}M")

# Breakeven oil price
price = breakeven_price(
    capex=500_000_000,
    fixed_opex=[30_000_000] * 15,
    variable_opex_per_unit=12.0,
    production=[5_000_000] * 15,
    discount_rate=0.10,
)
print(f"Breakeven: ${price:.2f}/bbl")

Core Workflows

Read a forward curve

from kolmo_stats import curve_shape, calendar_spread, prompt_spread

brent = {"M1": 84.5, "M2": 83.2, "M3": 82.1, "M6": 80.5}

shape = curve_shape(brent)
spread = calendar_spread(brent, "M1", "M6")
prompt = prompt_spread(brent)

Intent: turn a contract dictionary into curve structure, prompt spread, and near-minus-far spread.

Check physical and regional spreads

from kolmo_stats import crack_spread, brent_wti_spread, ttf_jkm_spread

margin = crack_spread(
    crude=80,
    gasoline=103,
    distillate=110,
    ratio="3-2-1",
)
atlantic_basis = brent_wti_spread(brent=84.5, wti=80.0)
lng_signal = ttf_jkm_spread(ttf=10.8, jkm=13.2)

Intent: compare refinery margin, oil basis, and gas hub differentials in the same script.

Stress a book

from kolmo_stats import scenario_pnl, historical_var, expected_shortfall

positions = {"brent": 1_000_000, "ttf": -350_000}
scenario = {"brent": -0.05, "ttf": 0.08}

pnl = scenario_pnl(positions, scenario)
var_95 = historical_var([-2.1, 0.4, 1.2, -0.8, -3.0], confidence=0.95)
es_95 = expected_shortfall([-2.1, 0.4, 1.2, -0.8, -3.0], confidence=0.95)

Intent: pair scenario PnL with distribution-based tail risk.

Value a project

from kolmo_stats import npv, breakeven_price

cashflows = [80, 120, 140, 130, 110]
value = npv(cashflows, discount_rate=0.12, initial_investment=400)

price = breakeven_price(
    capex=500_000_000,
    fixed_opex=[30_000_000] * 15,
    variable_opex_per_unit=12.0,
    production=[5_000_000] * 15,
    discount_rate=0.10,
)

Intent: use the same plain-function style for economics as for market analytics.

explain=True

Most analytics functions accept explain=True and return a dictionary with the result, plain-English explanation, formula, and key inputs.

from kolmo_stats import crack_spread

print(crack_spread(80, 103, 110, ratio="3-2-1", explain=True))
# {
#   "result": 25.33,
#   "explanation": "Gross refinery crack spread proxy using the 3-2-1 ratio.",
#   "formula": "((2 * gasoline) + distillate - (3 * crude)) / 3",
#   "inputs": {"crude": 80.0, "gasoline": 103.0, "distillate": 110.0, "ratio": "3-2-1"}
# }

Repo Docs

The GitHub repository contains contributor guidance, market conventions, examples, tests, and the source package under src/kolmo_stats/.

Local development

git clone https://github.com/GBR24/kolmo_stats.git
cd kolmo_stats
pip install -e ".[dev]"
python -m pytest

Reference

The public API is grouped by job and exported from kolmo_stats.