TinyCTA 0.13.3

A lightweight Python package for Commodity Trading Advisor (CTA) strategies

📈 TinyCTA

A Lightweight Python Package for Commodity Trading Advisor Strategies.

---

Quick Links: 📚 Repository • 📦 PyPI • 🐛 Issues • 💬 Discussions

---

📋 Overview

TinyCTA provides essential tools for quantitative finance and algorithmic trading, particularly for trend-following strategies. The package includes:

• Polars-based signal processing: oscillators, moving-average crossovers, and volatility-adjusted returns
• Robust volatility estimation via rolling median absolute deviation
• Linear algebra utilities that handle matrices with missing values
• Matrix shrinkage techniques commonly used in portfolio optimization

This package is designed to be the foundation for implementing CTA strategies in just a few lines of code, hence the name "TinyCTA".

📖 New here? Follow the end-to-end CTA tutorial to go from raw prices through signals and the Engine to cash positions.

🚀 Installation

Using pip

pip install tinycta

The core install keeps a minimal dependency footprint (numpy, polars, pydantic, cvx-linalg). The optional Optuna-based hyperparameter-optimisation layer (tinycta.hyper) is installed via the hyper extra:

pip install "tinycta[hyper]"

From source

Clone the repository and install using the provided Makefile:

git clone https://github.com/tschm/tinycta.git
cd tinycta
make install

This will install uv (a fast Python package installer) and create a virtual environment with all dependencies.

💻 Usage

Oscillator signal (Polars)

import polars as pl
from tinycta.osc import osc

prices = pl.DataFrame({"A": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]})
result = prices.with_columns(osc(pl.col("A"), fast=2, slow=6).alias("osc_A"))

Moving-average crossover (Polars)

import polars as pl
from tinycta.ewma import ma_cross

prices = pl.DataFrame({"A": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]})
result = prices.with_columns(
    ma_cross(pl.col("A"), fast=2, slow=6).alias("sig_A")
)

Volatility-adjusted returns (Polars)

import polars as pl
from tinycta.util import vol_adj, adj_log_prices

prices = pl.DataFrame({"A": [100, 101, 99, 102, 98, 103]})
result = prices.with_columns(
    vol_adj(pl.col("A"), vola=3, clip=4.2).alias("vol_adj_A"),
    adj_log_prices(pl.col("A"), vola=3, clip=4.2).alias("adj_log_A"),
)

Linear algebra operations

import numpy as np
from tinycta.linalg import solve

matrix = np.array([[1.0, 0.5], [0.5, 1.0]])
rhs = np.array([1.0, 2.0])
solution = solve(matrix, rhs)
print(np.round(solution, 10) + 0)

[0. 2.]

Position-sizing engine

The Engine turns aligned price and expected-return (mu) frames into correlation-shrinkage-optimized cash positions. It is configured by a validated Config.

import polars as pl
from tinycta.config import Config
from tinycta.engine import Engine

prices = pl.DataFrame({"date": [1, 2, 3, 4], "A": [100.0, 101.0, 102.0, 103.0]})
mu = pl.DataFrame({"date": [1, 2, 3, 4], "A": [0.0, 0.1, 0.2, 0.1]})

cfg = Config(vola=2, corr=2, clip=4.2, shrink=0.5)
engine = Engine(prices=prices, mu=mu, cfg=cfg)
positions = engine.cash_position  # Polars DataFrame of per-asset cash positions

Config is a frozen Pydantic model: vola, corr (must be >= vola) and clip must be positive, and shrink must lie in [0, 1].

Hyperparameter optimization

tinycta.hyper.optimize runs an Optuna study over a function that builds a portfolio from a trial and scores it by Sharpe ratio, returning a frozen Study.

from tinycta.hyper import optimize

def suggest_portfolio(trial):
    fast = trial.suggest_int("fast", 2, 20)
    slow = trial.suggest_int("slow", fast + 1, 100)
    # ... build and return a jquantstats Portfolio from the suggested params ...
    return build_portfolio(fast, slow)

study = optimize(suggest_portfolio, n_trials=100, seed=42)
print(study.best_params, study.best_value)

📚 API Reference

Signal Processing (tinycta.osc, tinycta.ewma, tinycta.util)

• osc(x, fast, slow, min_samples=1) — analytically scaled EWMA-difference oscillator (Polars)
• ma_cross(prices, fast, slow, min_samples=1) — sign of fast-vs-slow EWM crossover: -1, 0, or +1 (Polars)
• vol_adj(x, vola, clip, min_samples=1) — clipped, volatility-adjusted log returns (Polars)
• adj_log_prices(x, vola, clip, min_samples=1) — cumulative sum of volatility-adjusted log returns (Polars)

Signal Utilities (tinycta.signal)

• moving_absolute_deviation(price, com=32) — robust rolling volatility estimate via median absolute deviation (pandas)
• shrink2id(matrix, lamb=1.0) — shrink a matrix towards the identity matrix

Linear Algebra (tinycta.linalg)

• valid(matrix) — extract the finite subset of a matrix by filtering NaN rows/columns
• a_norm(vector, matrix=None) — matrix-norm of a vector
• inv_a_norm(vector, matrix=None) — inverse matrix-norm of a vector
• solve(matrix, rhs) — solve a linear system, handling matrices with NaN values

Position-Sizing Engine (tinycta.engine, tinycta.config)

• Config(vola, corr, clip, shrink) — frozen Pydantic config; corr >= vola, vola/corr/clip > 0, shrink ∈ [0, 1]
• Engine(prices, mu, cfg) — correlation-aware position optimizer; .cash_position returns per-asset cash positions
  • .assets, .ret_adj, .vola, .cor — intermediate per-asset/per-timestamp quantities

Hyperparameter Optimization (tinycta.hyper)

• optimize(suggest_portfolio_fn, n_trials=100, seed=42) — run an Optuna study scored by Sharpe; returns a Study
• Study — frozen result wrapper exposing best_params, best_value, n_completed, n_trials, and .plot(output_dir)

🛠️ Development

Setting up the development environment

make install

Running tests

make test

Code formatting and linting

make fmt

Cleaning up

make clean

📄 License

TinyCTA is licensed under the MIT License. See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.