{"id":14155340,"url":"https://github.com/KarelZe/tclf","last_synced_at":"2025-08-06T01:31:03.943Z","repository":{"id":183243964,"uuid":"669804786","full_name":"KarelZe/tclf","owner":"KarelZe","description":"A scikit-learn compatible classifier to perform trade classification in Python.","archived":false,"fork":false,"pushed_at":"2024-12-02T17:41:30.000Z","size":2978,"stargazers_count":16,"open_issues_count":2,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-02T18:50:17.748Z","etag":null,"topics":["empirical","finance","microstructure","python","rule-based-classifier","scikit-learn","trade-classification"],"latest_commit_sha":null,"homepage":"https://karelze.github.io/tclf/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KarelZe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-23T13:39:15.000Z","updated_at":"2024-12-02T13:01:11.000Z","dependencies_parsed_at":"2024-02-01T20:28:53.335Z","dependency_job_id":"828af5cb-403f-4c0f-9b57-a379f60462dd","html_url":"https://github.com/KarelZe/tclf","commit_stats":{"total_commits":106,"total_committers":5,"mean_commits":21.2,"dds":"0.44339622641509435","last_synced_commit":"05ea91e05041416cfec75b26befa29c0dd18138d"},"previous_names":["karelze/tclf"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarelZe%2Ftclf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarelZe%2Ftclf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarelZe%2Ftclf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarelZe%2Ftclf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KarelZe","download_url":"https://codeload.github.com/KarelZe/tclf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228821404,"owners_count":17977166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["empirical","finance","microstructure","python","rule-based-classifier","scikit-learn","trade-classification"],"created_at":"2024-08-17T08:02:53.046Z","updated_at":"2025-08-06T01:31:03.930Z","avatar_url":"https://github.com/KarelZe.png","language":"Python","readme":"# Trade Classification With Python\n\n[![GitHubActions](https://github.com/karelze/tclf//actions/workflows/tests.yaml/badge.svg)](https://github.com/KarelZe/tclf/actions)\n[![codecov](https://codecov.io/gh/KarelZe/tclf/branch/main/graph/badge.svg?token=CBM1RXGI86)](https://codecov.io/gh/KarelZe/tclf/tree/main/graph)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=KarelZe_tclf\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=KarelZe_tclf)\n\n![Logo](https://karelze.github.io/tclf/img/header.png)\n\n**Documentation ✒️:** [https://karelze.github.io/tclf/](https://karelze.github.io/tclf/)\n\n**Source Code 🐍:** [https://github.com/KarelZe/tclf](https://github.com/KarelZe/tclf)\n\n`tclf` is a [`scikit-learn`](https://scikit-learn.org/stable/)-compatible implementation of trade classification algorithms to classify financial markets transactions into buyer- and seller-initiated trades.\n\nThe key features are:\n\n* **Easy**: Easy to use and learn.\n* **Sklearn-compatible**: Compatible to the sklearn API. Use sklearn metrics and visualizations.\n* **Feature complete**: Wide range of supported algorithms. Use the algorithms individually or stack them like LEGO blocks.\n\n## Installation\n\n**pip**\n```console\npip install tclf\n```\n\n**[uv⚡](https://github.com/astral-sh/uv)**\n```console\nuv add tclf\n```\n\n## Supported Algorithms\n\n- (Rev.) CLNV rule[^1]\n- (Rev.) EMO rule[^2]\n- (Rev.) LR algorithm[^6]\n- (Rev.) Tick test[^5]\n- Depth rule[^3]\n- Quote rule[^4]\n- Tradesize rule[^3]\n\nFor a primer on trade classification rules visit the [rules section 🆕](https://karelze.github.io/tclf/rules/) in our docs.\n\n## Minimal Example\n\nLet's start simple: classify all trades by the quote rule and all other trades, which cannot be classified by the quote rule, randomly.\n\nCreate a `main.py` with:\n```python title=\"main.py\"\nimport numpy as np\nimport pandas as pd\n\nfrom tclf.classical_classifier import ClassicalClassifier\n\nX = pd.DataFrame(\n    [\n        [1.5, 1, 3],\n        [2.5, 1, 3],\n        [1.5, 3, 1],\n        [2.5, 3, 1],\n        [1, np.nan, 1],\n        [3, np.nan, np.nan],\n    ],\n    columns=[\"trade_price\", \"bid_ex\", \"ask_ex\"],\n)\n\nclf = ClassicalClassifier(layers=[(\"quote\", \"ex\")], strategy=\"random\")\nclf.fit(X)\nprobs = clf.predict_proba(X)\n```\nRun your script with\n```console\n$ python main.py\n```\nIn this example, input data is available as a pd.DataFrame with columns conforming to our [naming conventions](https://karelze.github.io/tclf/naming_conventions/).\n\nThe parameter `layers=[(\"quote\", \"ex\")]` sets the quote rule at the exchange level and `strategy=\"random\"` specifies the fallback strategy for unclassified trades.\n\n## Advanced Example\nOften 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.\n\n```python title=\"main.py\" hl_lines=\"6  16 17 20\"\nimport numpy as np\nfrom sklearn.metrics import accuracy_score\n\nfrom tclf.classical_classifier import ClassicalClassifier\n\nX = np.array(\n    [\n        [1.5, 1, 3, 2, 2.5],\n        [2.5, 1, 3, 1, 3],\n        [1.5, 3, 1, 1, 3],\n        [2.5, 3, 1, 1, 3],\n        [1, np.nan, 1, 1, 3],\n        [3, np.nan, np.nan, 1, 3],\n    ]\n)\ny_true = np.array([-1, 1, 1, -1, -1, 1])\nfeatures = [\"trade_price\", \"bid_ex\", \"ask_ex\", \"bid_best\", \"ask_best\"]\n\nclf = ClassicalClassifier(\n    layers=[(\"quote\", \"ex\"), (\"quote\", \"best\")], strategy=\"random\", features=features\n)\nclf.fit(X)\nacc = accuracy_score(y_true, clf.predict(X))\n```\nIn 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.\n\nLike before, column/feature names must follow our [naming conventions](https://karelze.github.io/tclf/naming_conventions/).\n\n## Other Examples\n\nFor more practical examples, see our [examples section](https://karelze.github.io/tclf/option_trade_classification).\n\n## Development\n\nWe are using [`tox`](https://tox.wiki/en/latest/user_guide.html) with [`uv`](https://docs.astral.sh/uv/) for development.\n\n```bash\ntox -e lint\ntox -e format\ntox -e test\ntox -e build\n```\n\n## Citation\n\nIf you are using the package in publications, please cite as:\n\n```latex\n@software{bilz_tclf_2023,\n    author = {Bilz, Markus},\n    license = {BSD 3},\n    month = nov,\n    title = {{tclf} -- trade classification with python},\n    url = {https://github.com/KarelZe/tclf},\n    version = {0.0.1},\n    year = {2023}\n}\n```\n\n## Footnotes\n\n  [^1]: \u003cdiv class=\"csl-entry\"\u003eChakrabarty, B., Li, B., Nguyen, V., \u0026amp; Van Ness, R. A. (2007). Trade classification algorithms for electronic communications network trades. \u003ci\u003eJournal of Banking \u0026amp; Finance\u003c/i\u003e, \u003ci\u003e31\u003c/i\u003e(12), 3806–3821. \u003ca href=\"https://doi.org/10.1016/j.jbankfin.2007.03.003\"\u003ehttps://doi.org/10.1016/j.jbankfin.2007.03.003\u003c/a\u003e\u003c/div\u003e\n  \u003cspan class=\"Z3988\" title=\"url_ver=Z39.88-2004\u0026amp;ctx_ver=Z39.88-2004\u0026amp;rfr_id=info%3Asid%2Fzotero.org%3A2\u0026amp;rft_id=info%3Adoi%2F10.1016%2Fj.jbankfin.2007.03.003\u0026amp;rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal\u0026amp;rft.genre=article\u0026amp;rft.atitle=Trade%20classification%20algorithms%20for%20electronic%20communications%20network%20trades\u0026amp;rft.jtitle=Journal%20of%20Banking%20%26%20Finance\u0026amp;rft.volume=31\u0026amp;rft.issue=12\u0026amp;rft.aufirst=Bidisha\u0026amp;rft.aulast=Chakrabarty\u0026amp;rft.au=Bidisha%20Chakrabarty\u0026amp;rft.au=Bingguang%20Li\u0026amp;rft.au=Vanthuan%20Nguyen\u0026amp;rft.au=Robert%20A.%20Van%20Ness\u0026amp;rft.date=2007\u0026amp;rft.pages=3806%E2%80%933821\u0026amp;rft.spage=3806\u0026amp;rft.epage=3821\"\u003e\u003c/span\u003e\n  [^2]: \u003cdiv class=\"csl-entry\"\u003eEllis, K., Michaely, R., \u0026amp; O’Hara, M. (2000). The accuracy of trade classification rules: Evidence from nasdaq. \u003ci\u003eThe Journal of Financial and Quantitative Analysis\u003c/i\u003e, \u003ci\u003e35\u003c/i\u003e(4), 529–551. \u003ca href=\"https://doi.org/10.2307/2676254\"\u003ehttps://doi.org/10.2307/2676254\u003c/a\u003e\u003c/div\u003e\n  \u003cspan class=\"Z3988\" title=\"url_ver=Z39.88-2004\u0026amp;ctx_ver=Z39.88-2004\u0026amp;rfr_id=info%3Asid%2Fzotero.org%3A2\u0026amp;rft_id=info%3Adoi%2F10.2307%2F2676254\u0026amp;rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal\u0026amp;rft.genre=article\u0026amp;rft.atitle=The%20accuracy%20of%20trade%20classification%20rules%3A%20evidence%20from%20nasdaq\u0026amp;rft.jtitle=The%20Journal%20of%20Financial%20and%20Quantitative%20Analysis\u0026amp;rft.volume=35\u0026amp;rft.issue=4\u0026amp;rft.aufirst=Katrina\u0026amp;rft.aulast=Ellis\u0026amp;rft.au=Katrina%20Ellis\u0026amp;rft.au=Roni%20Michaely\u0026amp;rft.au=Maureen%20O'Hara\u0026amp;rft.date=2000\u0026amp;rft.pages=529%E2%80%93551\u0026amp;rft.spage=529\u0026amp;rft.epage=551\"\u003e\u003c/span\u003e\n  [^3]: \u003cdiv class=\"csl-entry\"\u003eGrauer, C., Schuster, P., \u0026amp; Uhrig-Homburg, M. (2023). \u003ci\u003eOption trade classification\u003c/i\u003e. \u003ca href=\"https://doi.org/10.2139/ssrn.4098475\"\u003ehttps://doi.org/10.2139/ssrn.4098475\u003c/a\u003e\u003c/div\u003e\n  \u003cspan class=\"Z3988\" title=\"url_ver=Z39.88-2004\u0026amp;ctx_ver=Z39.88-2004\u0026amp;rfr_id=info%3Asid%2Fzotero.org%3A2\u0026amp;rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Adc\u0026amp;rft.type=document\u0026amp;rft.title=Option%20trade%20classification\u0026amp;rft.aufirst=Caroline\u0026amp;rft.aulast=Grauer\u0026amp;rft.au=Caroline%20Grauer\u0026amp;rft.au=Philipp%20Schuster\u0026amp;rft.au=Marliese%20Uhrig-Homburg\u0026amp;rft.date=2023\"\u003e\u003c/span\u003e\n  [^4]: \u003cdiv class=\"csl-entry\"\u003eHarris, L. (1989). A day-end transaction price anomaly. \u003ci\u003eThe Journal of Financial and Quantitative Analysis\u003c/i\u003e, \u003ci\u003e24\u003c/i\u003e(1), 29. \u003ca href=\"https://doi.org/10.2307/2330746\"\u003ehttps://doi.org/10.2307/2330746\u003c/a\u003e\u003c/div\u003e\n  \u003cspan class=\"Z3988\" title=\"url_ver=Z39.88-2004\u0026amp;ctx_ver=Z39.88-2004\u0026amp;rfr_id=info%3Asid%2Fzotero.org%3A2\u0026amp;rft_id=info%3Adoi%2F10.2307%2F2330746\u0026amp;rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal\u0026amp;rft.genre=article\u0026amp;rft.atitle=A%20day-end%20transaction%20price%20anomaly\u0026amp;rft.jtitle=The%20Journal%20of%20Financial%20and%20Quantitative%20Analysis\u0026amp;rft.volume=24\u0026amp;rft.issue=1\u0026amp;rft.aufirst=Lawrence\u0026amp;rft.aulast=Harris\u0026amp;rft.au=Lawrence%20Harris\u0026amp;rft.date=1989\u0026amp;rft.pages=29\"\u003e\u003c/span\u003e\n  [^5]: \u003cdiv class=\"csl-entry\"\u003eHasbrouck, J. (2009). Trading costs and returns for U.s. Equities: Estimating effective costs from daily data. \u003ci\u003eThe Journal of Finance\u003c/i\u003e, \u003ci\u003e64\u003c/i\u003e(3), 1445–1477. \u003ca href=\"https://doi.org/10.1111/j.1540-6261.2009.01469.x\"\u003ehttps://doi.org/10.1111/j.1540-6261.2009.01469.x\u003c/a\u003e\u003c/div\u003e\u003cspan class=\"Z3988\" title=\"url_ver=Z39.88-2004\u0026amp;ctx_ver=Z39.88-2004\u0026amp;rfr_id=info%3Asid%2Fzotero.org%3A2\u0026amp;rft_id=info%3Adoi%2F10.1111%2Fj.1540-6261.2009.01469.x\u0026amp;rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal\u0026amp;rft.genre=article\u0026amp;rft.atitle=Trading%20costs%20and%20returns%20for%20U.s.%20Equities%3A%20estimating%20effective%20costs%20from%20daily%20data\u0026amp;rft.jtitle=The%20Journal%20of%20Finance\u0026amp;rft.volume=64\u0026amp;rft.issue=3\u0026amp;rft.aufirst=Joel\u0026amp;rft.aulast=Hasbrouck\u0026amp;rft.au=Joel%20Hasbrouck\u0026amp;rft.date=2009\u0026amp;rft.pages=1445%E2%80%931477\u0026amp;rft.spage=1445\u0026amp;rft.epage=1477\"\u003e\u003c/span\u003e\n  [^6]: \u003cdiv class=\"csl-entry\"\u003eLee, C., \u0026amp; Ready, M. J. (1991). Inferring trade direction from intraday data. \u003ci\u003eThe Journal of Finance\u003c/i\u003e, \u003ci\u003e46\u003c/i\u003e(2), 733–746. \u003ca href=\"https://doi.org/10.1111/j.1540-6261.1991.tb02683.x\"\u003ehttps://doi.org/10.1111/j.1540-6261.1991.tb02683.x\u003c/a\u003e\u003c/div\u003e\n  \u003cspan class=\"Z3988\" title=\"url_ver=Z39.88-2004\u0026amp;ctx_ver=Z39.88-2004\u0026amp;rfr_id=info%3Asid%2Fzotero.org%3A2\u0026amp;rft_id=info%3Adoi%2F10.1111%2Fj.1540-6261.1991.tb02683.x\u0026amp;rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal\u0026amp;rft.genre=article\u0026amp;rft.atitle=Inferring%20trade%20direction%20from%20intraday%20data\u0026amp;rft.jtitle=The%20Journal%20of%20Finance\u0026amp;rft.volume=46\u0026amp;rft.issue=2\u0026amp;rft.aufirst=Charles\u0026amp;rft.aulast=Lee\u0026amp;rft.au=Charles%20Lee\u0026amp;rft.au=Mark%20J.%20Ready\u0026amp;rft.date=1991\u0026amp;rft.pages=733%E2%80%93746\u0026amp;rft.spage=733\u0026amp;rft.epage=746\"\u003e\u003c/span\u003e\n","funding_links":[],"categories":["scikit-learn"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKarelZe%2Ftclf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKarelZe%2Ftclf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKarelZe%2Ftclf/lists"}