Python SHiP-framework

Welcome to the official Python bindings for the SHiP (Similarity-Hierarchical-Partitioning) clustering framework.

The SHiP framework offers a modular and extensible approach to hierarchical clustering based on similarity trees, ultrametric hierarchies, and flexible partitioning strategies.

This Python package exposes several submodules:

Modules Overview

SHiP Module
The central interface to the SHiP framework. It allows you to construct similarity trees from your data, build hierarchical clusterings, and extract flat partitions with customizable parameters and algorithms.
Ultrametric Tree Submodule
Contains an overview (Enum class) of all available similarity trees used to represent relationships between data points. These trees form the basis for hierarchy construction. Different tree types, such as DCTree and others, can be selected from here when constructing an SHiP object.
Partitioning Submodule
Provides an overview (Enum class) of all available tree partitioning methods. These partitioning methods operate on the hierarchical trees to produce a flat clustering. Examples include methods like the Elbow method and fixed-K partitioning. They can be used in the fit or fit_predict method of an constructed SHiP object.
Logger Submodule
This modules contains settings to defines log levels. Use this submodule to select the verbosity of messages during tree and hierarchy construction, and also partitioning.

Getting Started

Import the main SHiP class to construct a similarity tree and cluster the tree by using one of the available partitioning methods:

from SHiP import SHiP

# Initialize with your data and preferred tree type
ship = SHiP(data=my_data, treeType="DCTree")

# Perform clustering with chosen parameters
labels = ship.fit_predict(hierarchy=2, partitioningMethod="Elbow")

For more detailed usage and examples, please refer to the module-specific documentation pages.

The SHiP framework is implemented in C++ for performance (for C++ documentation, see C++ API) and exposes a Python interface via pybind11 for easy integration in Python workflows.

Feel free to explore the submodules to see all the options applicable to SHiP.

Modules