{"id":36632508,"url":"https://github.com/sbobek/knac","last_synced_at":"2026-01-12T09:40:01.163Z","repository":{"id":41997120,"uuid":"362084824","full_name":"sbobek/knac","owner":"sbobek","description":"Knowledge Augmented Clustering","archived":false,"fork":false,"pushed_at":"2024-03-06T10:17:07.000Z","size":14696,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-09-28T09:07:23.552Z","etag":null,"topics":["clustering","explainability","interpretability","unsupervised","xai"],"latest_commit_sha":null,"homepage":"https://knac-toolkit.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sbobek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-04-27T11:17:56.000Z","updated_at":"2024-03-06T10:43:14.000Z","dependencies_parsed_at":"2024-03-06T11:33:18.443Z","dependency_job_id":null,"html_url":"https://github.com/sbobek/knac","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sbobek/knac","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbobek%2Fknac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbobek%2Fknac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbobek%2Fknac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbobek%2Fknac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sbobek","download_url":"https://codeload.github.com/sbobek/knac/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbobek%2Fknac/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337740,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["clustering","explainability","interpretability","unsupervised","xai"],"created_at":"2026-01-12T09:39:59.319Z","updated_at":"2026-01-12T09:40:01.029Z","avatar_url":"https://github.com/sbobek.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI](https://img.shields.io/pypi/v/knac-toolkit)](https://pypi.org/project/knac-toolkit/)  ![License](https://img.shields.io/github/license/sbobek/knac)\n ![PyPI - Downloads](https://img.shields.io/pypi/dm/knac-toolkit) [![Documentation Status](https://readthedocs.org/projects/knac-toolkit/badge/?version=latest)](https://tsproto.readthedocs.io/en/latest/?badge=latest)\n   \n# Google Colab Tutorial\nPlease follow the tutorial on using KnAC in text-clustering and fil in the survey at the end: [Colab Notebook](https://colab.research.google.com/drive/1SJaG_wW0h1_JaPk40vPNP3dpTJGa1xXG)\n# Knowledge Augmented Clustering (KnAC)\nKnAC is a toolk for expert knowledge extension with a usage of automatic clustering algorithms.\nIt allows to refine expert-based labeling with splits and merges recommendations of expert labeling augmented with explanations.\nThe explanations were formulated as rules and therefore can be easily interpreted incorporated with expert knowledge.\n\nPossible integration witth [CLAMP](https://github.com/sbobek/clamp) and [LUX](https://github.com/sbobek/lux) is currently under development.\n\nThe overall workflow for KnAC is presented in Figure below:\n![Workflow for KnAC](https://raw.githubusercontent.com/sbobek/knac/main/pix/workflow.png \"Title\")\n\n\n## Install\nKnAC can be installed from either [PyPI](https://pypi.org/project/knac) or directly from source code [GitHub](https://github.com/sbobek/knac)\n\nTo install form PyPI:\n\n```\npip install knac-toolkit\n```\n\nTo install from  source:\n\n``` python\ngit clone  https://github.com/sbobek/knac\ncd knac\npip install .\n```\nAfter that you can install and run `jupyter lab` and anvigate to `examples`   direcotry to run notebooks.\n\n## Splitting example\nSynthetic datasets with clusters to split is presented below. Columns in the figure represent clustering performed with expert knowledge, automated clustering, and $H^{split}$ matrix. In this example it is visible that expert knowledge clustering defined cluster 1 which should in fact be merged according to wht is seen in the data.\n\n![](https://raw.githubusercontent.com/sbobek/knac/main/pix/split-toy-example.png)\n\nFor such a cese we will get following KnAC recommendations:\n\n``` python\nknac_splits = KnacSplits(confidence_threshold=0.9,silhouette_weight=0.2) \nknac_splits_recoms = knac_splits.fit_transform(confusion_matrix,\n                                              y=None, data=data, \n                                              labels_automatic=data['Automatic_Clusters'].astype(str), \n                                              labels_expert=XX2['Expert_Clusters'])\n\nExpert_Clusters\n1    [(1, 2), 0.8332849823568992]\n```\n\nWhich should be read as: Split expert cluster 1 into clusters 1 and 2 with confidence 0.83\n\nFor this recommendation, following justifications describing differences between expert clusters to split, showing that the most important difference between the clusters is in the **x1** variable and its value around 0.9, which is consisten with what we can see in the plot above.\n\n``` python\njustify_splits_tree(expert_to_split=expert_to_split, \n               split_recoms=split_recoms, \n               data=data, \n               features=features, \n               target_automatic='Automatic_Clusters')\n               \n['if (x1 \u003e -0.903) then class: 2 (proba: 100.0%) | based on 100 samples',\n 'if (x1 \u003c= -0.903) then class: 1 (proba: 100.0%) | based on 100 samples']\n               \n```\n\n## Merging example\nSynthetic datasets with clusters to merge is presented below. Columns in the figure represent clustering performed with expert knowledge, automated clustering, and $H^{merge}$ matrix. In this example it is visible that expert knowledge clustering defined cluster 0 and 3 which should in fact be merged according to wht is seen in the data.\n\n![](https://raw.githubusercontent.com/sbobek/knac/main/pix/merge-toy-example.png)\n\nFor such a cese we will get following KnAC recommendations:\n\n``` python\nknac1_merges = KnacMerges(confidence_threshold=0.9, \n                    metric='centroids_link',           \n                    metric_weight=0.2)       \nknac_merges_recoms=knac1_merges.fit_transform(confusion_matrix,data=data[['x1','x2']].values,labels_expert=data['Expert_Clusters'])\n\nC1\tC2\tsimilarity\n0\t3\t0.958983\n```\n\nWhich should be read as: automatically discovered clusters C1 and C2 should be merged, as the similiarity (begin combinantion of link metric choosen and similarity indistribution between expret clusters) is equal to 0.93.\n\n\nFor this recommendation, following justifications describing differences between expert clusters to merge, showing that the most important difference between the clusters to merge is in the **x2** variable and its value around -5. It is the xpert role to decide if this difference is significant taking into account the domain knowledge (in this case one can assume that the difference describe by the rule sis not relevant for distinguising two separate clusters based on such condition).\n\n``` python\njustify_merges_tree(merge_recoms=merge_recoms, data=data, features=features, target_expert='Expert_Clusters')\n\n['if (x2 \u003c= -5.065) then class: 0 (proba: 98.21%) | based on 56 samples',\n 'if (x2 \u003e -5.065) then class: 3 (proba: 97.78%) | based on 45 samples']\n```\n\n\n# Cite this work\n\n```\n@Article{bobek2022knac,\n  author=\"Bobek, Szymon\n  and Kuk, Micha{\\l}\n  and Brzegowski, Jakub\n  and Brzychczy, Edyta\n  and Nalepa, Grzegorz J.\",\n  title=\"KnAC: an approach for enhancing cluster analysis with background knowledge and explanations\",\n  journal=\"Applied Intelligence\",\n  year=\"2022\",\n  month=\"Nov\",\n  day=\"23\",\n  issn=\"1573-7497\",\n  doi=\"10.1007/s10489-022-04310-9\",\n  url=\"https://doi.org/10.1007/s10489-022-04310-9\"\n}\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbobek%2Fknac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsbobek%2Fknac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbobek%2Fknac/lists"}