Skip to main content

📈 TinyCTA

A Lightweight Python Package for Commodity Trading Advisor Strategies.

PyPI version MIT License Coverage Downloads CodeFactor OpenSSF Scorecard Rhiza


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.

Metadata

Release files for TinyCTA 0.13.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for TinyCTA 0.13.3
File Size Uploaded Provenance Actions
tinycta-0.13.3.tar.gz 1.7 MB With provenance Details for tinycta-0.13.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for TinyCTA 0.13.3
File Interpreter ABI Platform Actions
tinycta-0.13.3-py3-none-any.whl Python 3 none any Details for tinycta-0.13.3-py3-none-any.whl

Total release size: 1.7 MB

Release files / tinycta-0.13.3.tar.gz

Download URL tinycta-0.13.3.tar.gz
Size 1.7 MB
Tags Source
SHA-256 checksum
How to use checksums
0b1c15a80ef42ebdae62a1f8a2f5d6a84998b27b18f613b0e22b976f559ff266
BLAKE2b-256 checksum
How to use checksums
643ee486c5be7a6e38e602bb4ae937207ab4400fff934b79c3caffd191581e3d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.

Transparency log

Release files / tinycta-0.13.3-py3-none-any.whl

Download URL tinycta-0.13.3-py3-none-any.whl
Size 18.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
03089bb70f293890a2bd6d9617dbd552694ccffd071394add3d4952b79e56471
BLAKE2b-256 checksum
How to use checksums
a1421c7f2a564e5332ba13827b0edb96726bf716ebb8f21d824089b60a9d7419
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.

Transparency log

Security for TinyCTA 0.13.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tinycta-0.13.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.13.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page