📈 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.

```python +RHIZA_SKIP 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`.

```python +RHIZA_SKIP
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 (Polars)
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.

📈 TinyCTA¶