説明できるクラスタリングで「なぜ同じ群？」がわかる！高速クラスタ分析ライブラリ CLASSIX

ひとことでいうと

CLASSIX（クラシックス）は、高速・省メモリ・説明可能という三拍子をそろえた Python 向けのクラスタリングライブラリです。データを「グループ」に集約してから「クラスタ」に統合する二段階の処理で、任意の形状のデータに対応します。最大の特徴は .explain() メソッドで、「なぜこの 2 点が同じクラスタに入ったのか」をテキストや図で出力できる点です。scikit-learn の API に慣れた方なら、.fit() を呼ぶだけですぐ使い始められます。名称は CLustering by Aggregation with Sorting-based Indexing の略に、説明可能性（explainability）を表す「X」を加えた造語です。

こんな人におすすめ

大規模データを扱うエンジニア：画像特徴量・遺伝子発現量・テキスト埋め込みなど、数百万件規模のデータを高速に分類したい方。Cython 拡張を有効にすれば純 Python モードに比べて最大 40 倍程度の速度向上が期待できます。
説明責任が求められる現場の担当者：マーケティングのセグメンテーションや医療データの分類など、「なぜこの 2 件が同じグループか」をステークホルダーに説明しなければならない業務に最適です。.explain() が自然言語で根拠を出力します。
研究者・論文再現性を重視するユーザー：リポジトリ内の exps/ ディレクトリに掲載論文の全実験コードが収録されており、scikit-learn や hdbscan との比較をそのまま再現できます。

インストールと基本的な使い方

Step 1: パッケージをインストールする

PyPI と conda-forge の両方から入手できます。NumPy のバージョンによってコマンドが少し異なります。

# NumPy 1.26.4 以下の場合
pip install classixclustering

# NumPy 2.x 以上の場合（公式推奨）
pip install classixclustering --no-cache-dir

# conda 環境の場合
conda install -c conda-forge classixclustering

C コンパイラ（Linux なら gcc、Windows なら MSVC）がある環境では、インストール時に Cython 拡張が自動でビルドされ高速化されます。コンパイラがない場合でも純 Python モードで動作するため、まずは試してみましょう。

Step 2: Cython の有効・無効を確認する

インストール後に以下のコードを実行すると、Cython が有効かどうかを確認できます。Cython が使えると処理速度が大幅に上がるため、本番環境では有効化をおすすめします。

import classix
classix.cython_is_available(verbose=1)

# Cython を意図的に無効化したい場合
classix.__enable_cython__ = False

Step 3: データをクラスタリングする

scikit-learn 互換の API なので、.fit() を呼ぶだけで動作します。verbose=0 にするとログ出力を抑制できます。

import classix
from sklearn.datasets import make_blobs

data, labels = make_blobs(n_samples=1000, centers=5, n_features=10, random_state=0)

clx = classix.CLASSIX(radius=0.1, minPts=10, verbose=0)
clx.fit(data)

print(clx.labels_)          # 各データ点のクラスタラベル
clx.explain(data=data, plot=True)  # テキスト＋図での説明を出力

clx.labels_ には各データ点がどのクラスタに属するかが配列で返されます。.explain() を呼ぶと、指定した 2 点がどのグループを経由してつながっているかを段階的に説明してくれます。

動かしてみた

CLASSIX の動作環境について、README と conda-forge のメタデータをもとに整理しました。

項目	内容
Python	3.8 以上（3.12 対応確認済み）
OS	Linux / Windows / macOS
必須依存	NumPy, SciPy, Pandas, Matplotlib
任意（高速化用）	Cython（C コンパイラが必要）

Linux 環境で Cython を有効にするには、apt-get install -y build-essential で gcc を導入してから pip install classixclustering を実行するのが最も確実です。コンパイラが見つからない場合は Cython のビルドは自動でスキップされ、純 Python モードにフォールバックします。大量のデータを扱う予定がある場合は、Cython を有効にした環境を用意しておくと快適です。

ブラウザ上のインタラクティブデモ（Gradio 製）も用意されており、radius と minPts をスライダーで調整しながら合成データへの分類結果をリアルタイムで確認できます。コードを書く前に挙動のイメージをつかむのに便利です。

実践のコツ：パラメータ調整のはじめの一歩

CLASSIX のパラメータ調整で最初に押さえるべきは radius と minPts の 2 つです。この 2 つを理解するだけで、ほとんどのユースケースに対応できます。

まず radius=1, minPts=1 で全体像をつかむ。クラスタ数が多すぎれば radius を大きくし、少なすぎれば小さくします。
minPts でノイズを制御する。小さいクラスタが目立つ場合は minPts を上げると、近隣クラスタへ再割り当て（または -1 のノイズ扱い）されます。
verbose=1 でログを見ながら調整する。何グループ・何クラスタに分かれたかが出力されるので、過剰分割や過少分割を素早く検知できます。
clx.clusterSizes_ でクラスタサイズを確認する。特定クラスタが極端に大きい場合は radius を小さくするサインです。
post_alloc=True（デフォルト）を使う。minPts 未満の小クラスタを自動で近くの大クラスタに統合してくれます。ノイズとして明示したい場合は post_alloc=False に変更します。
新規データへの予測には .predict() を使う。一度 .fit() したモデルを使い回せるため、バッチ処理や本番推論にも対応できます。

clx = classix.CLASSIX(
    sorting='pca',       # PCA 主軸でソートして高速化
    radius=0.15,
    minPts=14,
    group_merging='density',
    verbose=1
)
clx.fit(X)
print(clx.clusterSizes_)   # 各クラスタのサイズ一覧

活用例

コロナウイルス変異株の系統分類：README のデモでは 572 万件のゲノムデータを 3 特徴量で 25 クラスタに分類する例が示されています。特定の 2 系統がどのグループを経由してつながるかを経路として出力できるため、バイオインフォマティクスの解析に適しています。
顧客セグメンテーションの根拠説明：購買履歴や行動ログの埋め込みベクトルをクラスタリングし、.explain() で各セグメントの特性をチームに説明できます。「なぜこの顧客層が同じグループか」という根拠提示が、ブラックボックスなアルゴリズムでは難しいところをカバーします。
画像のセグメンテーション：リポジトリ内の exps/run_img_seg.py に画像ピクセルのクラスタリングサンプルが含まれています。色や特徴量に基づいた領域分割に応用できます。
テキスト埋め込みのクラスタリング：BERT や Sentence Transformers で生成した文書ベクトルを CLASSIX に入力することで、トピックの自動分類やドキュメントの類似グループ化が行えます。.explain() で分類根拠を出力できるため、社内レポートへの組み込みにも使いやすいです。
異常検知の前処理：post_alloc=False に設定してノイズラベル -1 を活用することで、外れ値候補の一次スクリーニングとして機能させられます。後続の異常検知モデルへの入力データ整理に役立ちます。
論文実験の再現・比較検証：exps/ 内のスクリプトをそのまま実行することで、CLASSIX と scikit-learn・hdbscan などとの速度・精度比較を自分の環境で再現できます。アルゴリズムの学習や研究のベースラインとして活用できます。

用語とポイント解説

グループ（Group） CLASSIX が最初に作る小単位の集合です。指定した radius の範囲内にあるデータ点をまとめたもので、後の「クラスタ」の材料になります。

クラスタ（Cluster） 隣接するグループを統合して得られる最終的な分類結果です。minPts 未満のクラスタはノイズとして扱われるか、近隣クラスタに再割り当てされます。

radius グループの大きさを決める主要パラメータです。データは内部で自動スケーリングされるため、設定値は正規化後のスケールに対応します。大きいほどグループ数が減り処理が速くなりますが、細かい構造が失われます。

minPts 最小クラスタサイズです。これを下回るクラスタはノイズ（-1）として扱われるか、post_alloc=True の場合は近隣クラスタへ統合されます。

sorting='pca' データを PCA の第 1 主軸に沿ってソートしてからグループ化を行うオプションです。比較回数を減らし処理を高速化します。デフォルト設定として推奨されています。

group_merging グループをクラスタへ統合する方式を指定します。'density'（密度ベース）と 'distance'（距離ベース）が選べます。データの形状に応じて使い分けると精度が上がります。

.explain() メソッド 2 つのデータ点がなぜ同じクラスタに属するのかを、経由したグループの経路を含めてテキストと図で説明します。他のクラスタリング手法にはない CLASSIX 固有の機能です。

post_alloc minPts 未満の小クラスタの扱いを制御するフラグです。True（デフォルト）では近隣クラスタへ再割り当て、False ではノイズラベル -1 として返します。

Cython 拡張 Python コードを C にコンパイルして実行速度を向上させるしくみです。C コンパイラが必要ですが、なくても純 Python モードで動作します。大規模データを扱う場合は有効化が特に効果的です。

clx.clusterSizes_ フィット後に参照できる属性で、各クラスタに属するデータ点の個数を配列で返します。クラスタが均等に分かれているかどうかの確認に使います。

ぜひ顧客セグメンテーションの根拠説明や大規模なゲノム・テキストデータのクラスタ分析などに活用してみてはいかがでしょうか。