tribal 0.1.7

No project description provided

Tribal

Transductive inference-based clustering algorithms Python package

About

Tribal is a Python package containing three clustering algorithms based on transductive inference for partially labeled data. The goal of the algorithms is to enable determining the assignment of input data to specific clusters based on existing labeled data. Two of the proposed algorithms are based on graph constructions derived from the input data, while the third relies solely on neighborhood proximity. The implementations emphasize both computational efficiency and the ability for users to customize parameters. The package also features an implementation of visualization methonds for two-dimensional or three-dimensional data. The package was designed in a modular manner to facilitate future extensions and updates. Additionally, the provided documentation and a set of practical examples support users in quickly deploying the algorithms in real-world projects.

Authors and Contributors

Authors and Maintainers: Wojciech Grabias, Krzysztof Sawicki
Guidance and contributions: prof. Marek Gągolewski

How to Install

To install via pip (see PyPI):

pip install tribal

Example of use

All implemented algorithms can be imported via the path transatlantic.transductive_clustering.
These are the classes MSTL, GMKNN, and TDBSCAN.

import tribal
from tribal.transductive_clustering import MSTL , GMKNN , TDBSCAN

alg1 = MSTL()
alg2 = GMKNN(k=7)
alg3 = TDBSCAN(eps=0.1, k=4, new_clusters=False)

The process is analogous to the scikit-learn package and is identical for each of the implemented algorithms.
The user is required to provide data points as a list of lists or any other structure that can be cast to an object of the class np.ndarray, as well as initial labels as a one-dimensional list of integers (with the value -1 used to indicate missing labels).
The algorithm is executed on the provided data using the fit() method.

X = [[...] , [...] , ...] # Input data
y = [...] # Initial labels

alg1.fit(X , y)

To obtain the output labels of the algorithm, you should refer to the labels_ attribute.

final_labels = alg1.labels_

The two aforementioned steps can be combined into a single step by calling the fit_predict() method.

X = [[...] , [...] , ...] # Input data
y = [...] # Initial labels

final_labels = alg1.fit_predict(X , y)

Additional functionalities related to algorithms

In the case of graph algorithms, it is possible to gain insight into the algorithm's execution by generating a graph that represents the graph responsible for the specific stages of the program.

alg1.draw_transitional_graph("mst")
alg1.draw_result_graph()

In the case of the first algorithm, a minimum spanning tree is generated based on the initial data. For the second algorithm, the following options are available:

• knn - k-nearest neighbors graph
• mknn - mutual k-nearest neighbors graph
• informative edges - represents a stage aimed at removing insignificant edges

alg2.draw_transitional_graph("knn") # Options : knn, gmknn ,informative_edges
alg2.draw_result_graph()

Testing data

During the development of the project, the algorithms were tested on data from the Clustering Benchmark project.

License

Tribal Package for Python

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License Version 3, 19 November 2007, published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License Version 3 for more details. You should have received a copy of the License along with this program. If this is not the case, refer to https://www.gnu.org/licenses/.

References

Gagolewski M., genieclust: Fast and robust hierarchical clustering, SoftwareX 15, 2021, 100722. DOI: 10.1016/j.softx.2021.100722. https://genieclust.gagolewski.com/.

Gagolewski M., A framework for benchmarking clustering algorithms, SoftwareX 20, 2022, 101270. DOI: 10.1016/j.softx.2022.101270. https://clustering-benchmarks.gagolewski.com/.