finance calcs

Standard financial calculations

Overview

finance-calcs provides composable Polars expression metrics plus a smaller set of explicitly eager statistical, preprocessing, post-trade, and native kernel helpers. It is designed for lazy execution where the algorithm permits it, namespace-style ergonomics, and direct interoperability with the rest of the finance-* stack.

The public API follows a few rules:

• every expression metric accepts and returns pl.Expr
• metrics are exposed once, with optional window= and period= controls rather than separate rolling, monthly, and annual variants
• functions are also available through the .fcalcs namespace on both pl.Expr and pl.Series
• examples use synthetic but realistic fixtures from finance-datagen

Return, risk, and tail expression metrics accept periodic returns rather than prices. Convert prices first with simple_returns or log_returns. These metrics treat floating-point NaN and Polars null values as missing. Compound returns treat missing observations as neutral, while statistical aggregations exclude them.

Materializing helpers are not available through .fcalcs: native ADX, SAR, and GARCH kernels accept numeric sequences and return NumPy arrays; GPD fits and several statistical helpers accept pl.Series; preprocessing and post-trade summaries accept concrete pl.DataFrame inputs.

Implemented coverage

See the Examples page for workflows with generated data and the API page for a complete grouped reference for every public function.

Quick start

Generate a deterministic daily equity path with finance-datagen, then compute return and risk metrics as Polars expressions.

import polars as pl
from finance_datagen import generate_prices

import finance_calcs as fc

prices = generate_prices(symbol="ACME", seed=7)

out = prices.with_columns(
    pl.col("price").fcalcs.simple_returns().alias("ret"),
).select(
    fc.returns(pl.col("ret")).alias("total_return"),
    pl.col("ret").fcalcs.annualized_return().alias("ann_return"),
    pl.col("ret").fcalcs.volatility().alias("ann_vol"),
    pl.col("ret").fcalcs.sharpe().alias("sharpe"),
    pl.col("ret").fcalcs.max_drawdown().alias("max_drawdown"),
)

Use finance-datagen.ohlc_from_close when calculations need OHLCV bars:

from finance_datagen import ohlc_from_close

bars = ohlc_from_close(prices["price"], symbol="ACME", seed=7)

features = bars.with_columns(
    pl.col("close").fcalcs.sma(20).alias("sma_20"),
    pl.col("close").fcalcs.rsi(14).alias("rsi_14"),
    fc.atr(pl.col("high"), pl.col("low"), pl.col("close")).alias("atr_14"),
    fc.obv(pl.col("close"), pl.col("volume")).alias("obv"),
)

Period and frequency slices

Use period= for calendar-style slices and keep window= for rolling row-count windows. A period can be a finance_enums.Frequency, any alias accepted by finance_enums.to_frequency(), any Polars dt.truncate() duration string, or a precomputed bucket expression.

import polars as pl
from finance_enums import Frequency

monthly = prices.with_columns(
    pl.col("price").fcalcs.simple_returns().alias("ret"),
).with_columns(
    fc.period_bucket(pl.col("timestamp"), Frequency.Month).alias("month"),
    pl.col("ret").fcalcs.returns(period="month", date=pl.col("timestamp")).alias("month_return"),
    pl.col("ret").fcalcs.sharpe(period="1q", date=pl.col("timestamp")).alias("quarter_sharpe"),
)

For fiscal periods, strategy regimes, or exchange-calendar grids built upstream, pass the bucket expression directly:

bucketed = prices.with_columns(
    pl.col("price").fcalcs.simple_returns().alias("ret"),
    pl.col("timestamp").dt.year().alias("fiscal_year"),
).with_columns(
    fc.returns(pl.col("ret"), period=pl.col("fiscal_year")).alias("fiscal_return"),
)

Stack integration

finance-calcs is intended to pair with:

• finance-datagen for synthetic fixtures and test inputs
• finance-dates for calendar-aware date handling upstream
• finance-enums for shared enum-backed trading semantics upstream

That keeps calculations focused on typed expressions instead of schema cleanup, string parsing, or calendar repair.