Trade Classification With Python

Documentation ✒️: https://karelze.github.io/tclf/

Source Code 🐍: https://github.com/KarelZe/tclf

tclf is a scikit-learn-compatible implementation of trade classification algorithms to classify financial markets transactions into buyer- and seller-initiated trades.

The key features are:

• Easy: Easy to use and learn.
• Sklearn-compatible: Compatible to the sklearn API. Use sklearn metrics and visualizations.
• Feature complete: Wide range of supported algorithms. Use the algorithms individually or stack them like LEGO blocks.
• DataFrame-agnostic: Works with any narwhals-compatible DataFrame, including pandas, Polars, and cuDF.

Installation

pip

pip install tclf

uv⚡

uv add tclf

Supported Algorithms

• (Rev.) CLNV rule¹
• (Rev.) EMO rule²
• (Rev.) LR algorithm³
• (Rev.) Tick test⁴
• Depth rule⁵
• Quote rule⁶
• Tradesize rule⁵

For a primer on trade classification rules visit the rules section 🆕 in our docs.

Minimal Example

Let's start simple: classify all trades by the quote rule and all other trades, which cannot be classified by the quote rule, randomly.

tclf accepts any narwhals-compatible DataFrame — pandas, Polars, cuDF, and more — as well as plain numpy arrays.

Polars

import polars as pl

from tclf.classical_classifier import ClassicalClassifier

X = pl.DataFrame({
    "trade_price": [1.5, 2.5, 1.5, 2.5, 1.0, 3.0],
    "bid_ex": [1.0, 1.0, 3.0, 3.0, None, None],
    "ask_ex": [3.0, 3.0, 1.0, 1.0, 1.0, None],
})

clf = ClassicalClassifier(layers=[("quote", "ex")], strategy="random")
clf.fit(X)
probs = clf.predict_proba(X)

pandas

import numpy as np
import pandas as pd

from tclf.classical_classifier import ClassicalClassifier

X = pd.DataFrame(
    [
        [1.5, 1, 3],
        [2.5, 1, 3],
        [1.5, 3, 1],
        [2.5, 3, 1],
        [1, np.nan, 1],
        [3, np.nan, np.nan],
    ],
    columns=["trade_price", "bid_ex", "ask_ex"],
)

clf = ClassicalClassifier(layers=[("quote", "ex")], strategy="random")
clf.fit(X)
probs = clf.predict_proba(X)

Run your script with

$ python main.py

In this example, input data has columns conforming to our naming conventions.

The parameter layers=[("quote", "ex")] sets the quote rule at the exchange level and strategy="random" specifies the fallback strategy for unclassified trades.

Advanced Example

Often it is desirable to classify both on exchange level data and nbbo data. Also, data might only be available as a numpy array. So let's extend the previous example by classifying using the quote rule at exchange level, then at nbbo and all other trades randomly.

import numpy as np
from sklearn.metrics import accuracy_score

from tclf.classical_classifier import ClassicalClassifier

X = np.array([
    [1.5, 1, 3, 2, 2.5],
    [2.5, 1, 3, 1, 3],
    [1.5, 3, 1, 1, 3],
    [2.5, 3, 1, 1, 3],
    [1, np.nan, 1, 1, 3],
    [3, np.nan, np.nan, 1, 3],
])
y_true = np.array([-1, 1, 1, -1, -1, 1])
features = ["trade_price", "bid_ex", "ask_ex", "bid_best", "ask_best"]

clf = ClassicalClassifier(
    layers=[("quote", "ex"), ("quote", "best")], strategy="random", features=features
)
clf.fit(X)
acc = accuracy_score(y_true, clf.predict(X))

In this example, input data is available as np.arrays with both exchange ("ex") and nbbo data ("best"). We set the layers parameter to layers=[("quote", "ex"), ("quote", "best")] to classify trades first on subset "ex" and remaining trades on subset "best". Additionally, we have to set ClassicalClassifier(..., features=features) to pass column information to the classifier.

Like before, column/feature names must follow our naming conventions.

Other Examples

For more practical examples, see our examples section.

Development

We are using uv for development. uv sync creates a virtual environment with all development dependencies.

uv sync                                      # install package and dev dependencies
uv run pytest                                # run tests
uv run ruff check src tests                  # lint
uv run ruff format src tests                 # format
uv run ty check src                          # type check
uv run prek run --all-files                  # run prek hooks
uv run zensical serve                        # serve docs at http://localhost:8000
uv build                                     # build distribution

Citation

If you are using the package in publications, please cite as:

@software{bilz_tclf_2023,
    author = {Bilz, Markus},
    license = {BSD 3},
    month = nov,
    title = {{tclf} -- trade classification with python},
    url = {https://github.com/KarelZe/tclf},
    version = {0.4.0},
    year = {2023}
}

Footnotes