PolyClustX

A Unified Framework for Multi-View and Multimodal Representation Learning and Clustering from Feature Views to Attributed Graphs

Prepare data, compare algorithms, tune hyperparameters and visualize results through one Python API, command line or graphical interface. Work with one or many feature views, optional graphs and optional ground-truth labels.

Documentation · Models · Examples

Install

Python 3.10+ is required. Installation includes PyTorch, the interface and Optuna; Hugging Face datasets use ordinary HTTP downloads.

From PyPI:

python -m pip install polyclustx

Or install the repository:

git clone https://github.com/AbdelheqMokhtari/PolyClustX.git
cd PolyClustX
python -m pip install .

Choose how you want to work: Interface · Python · CLI.

1. Interactive interface

polyclustx-display

Open the printed address, normally http://localhost:8501. If the launcher is not found, use python -m polyclustx.display.

Load a dataset, inspect its features/graphs, and compose named views. Prepare models, run comparisons or searches, visualize results and download reports from the independent pages. Variant controls appear only for datasets with alternate representations. Interface guide.

2. Python package

Compare two methods on two feature views of a small offline dataset:

from sklearn.datasets import load_wine
from sklearn.preprocessing import StandardScaler
from polyclustx.data import MultiViewDataset
from polyclustx.models import LMGEC, MultiViewKMeans
from polyclustx.metrics import clustering_accuracy, nmi_score
from polyclustx.experiment import Experiment

X, labels = load_wine(return_X_y=True)  # small, offline example
X = StandardScaler().fit_transform(X)
data = MultiViewDataset([X[:, :6], X[:, 6:]], labels=labels, name="Wine")

results = Experiment(
    datasets=data,
    models=[
        LMGEC(n_clusters=3, embedding_dim=3, max_iter=20, random_state=42),
        MultiViewKMeans(n_clusters=3, random_state=42),
    ],
    metrics={"ACC": clustering_accuracy, "NMI": nmi_score},
    runs=3,
    save_path="experiments/comparison",
).run()

run() prints a model-configuration table followed by a results table for each dataset. No extra print is needed. Example result output:

Results — Wine
┌────────┬──────────────────┬────────────────────┐
│ Metric │            LMGEC │    MultiViewKMeans │
├────────┼──────────────────┼────────────────────┤
│ ACC    │ 0.9551 (±0.0000) │ 0.9663 (±0.0000) * │
│ NMI    │ 0.8352 (±0.0000) │ 0.8770 (±0.0000) * │
│ Alphas │   [0.481, 0.519] │                    │
│ Time   │            0.03s │              0.02s │
└────────┴──────────────────┴────────────────────┘

Values are means and standard deviations over three runs; * marks the best mean. Timing and numerical results can vary between environments. Tables adapt to terminal width and remain scrollable in notebooks. The JSON/CSV reports are saved separately; to download one bundle:

results.export("experiments/comparison.zip")

Use load_data("acm") instead of constructing data to work with a catalog dataset. For several datasets, pass datasets={"Study A": data_a, "Study B": data_b}; prepare estimators with the K needed for your study.

For a learned embedding and a plot, fit a model directly:

from polyclustx.visualization import plot_clusters

model = data.fit(LMGEC(n_clusters=3, embedding_dim=3, random_state=42))
plot_clusters(model.embedding_, model.labels_, method="pca")

Experiment guide.

3. Command line

polyclustx models
polyclustx datasets
lmgec --help
lmgec acm --embedding-dim 8 --runs 3
scm acm --embedding-dim 16 --max-iter 50
idec acm --hidden-dims '128,64' --pretrain-epochs 20

Each method has its own command and parameter help. Use --variant for a dataset variant, --clusters to override K, and --output to select the report directory. Without an explicit K, labeled datasets use their number of reference classes.

Search candidates or continuous ranges:

lmgec acm --search grid --vary 'temperature=[0.5,1,2]' --objective nmi
lmgec acm --search optuna --vary 'temperature={"low":0.1,"high":5.0}' --trials 10
multiview-kmeans acm --no-benchmark --clusters 3 --metrics silhouette db

Compare several methods and datasets in one report:

polyclustx experiment --datasets acm dblp --models lmgec scm --runs 3
polyclustx experiment --datasets acm --models lmgec scm --param lmgec.embedding_dim=8
polyclustx experiment --config examples/experiment_plan.yaml

The example plan keeps larger studies readable: name configurations, set per-model parameters, choose datasets and specify repeats. Dataset-specific default K is handled automatically. Short commands may conflict with other installed tools; use a dedicated environment or polyclustx lmgec acm.

Interface: polyclustx-display is a standalone command. See the CLI guide with complete examples.

Datasets

37 dataset families provide 66 MATLAB representation files. All download links are direct Hugging Face URLs: no extra download package or account is needed.

Missing observations are independent of these categories. Simulate them with load_data("acm", 0.2, random_state=42), or align your own views using sample IDs. Different methods support different inputs; see the method table below.

Multi-view attributed graph clustering (MVAGC)

Multi-view clustering (MVC)

Multimodal clustering (MMC)

Multimodal attributed graph clustering (MMAGC)

Alternate feature representations

Variants reuse the same samples with different encoders, rather than adding new families. Select one with load_data("pascal", variant="clip"). Grocery-S and Reddit-S are separate smaller datasets, each with its own variants.

Pascal and COCO default to ResNet + Doc2Vec (2048/300 columns). MMAGC defaults to CLIP-ViT + Gemma-7B (768/3072 columns). ESP-Game, IAPR-TC12, MIRFlickr and NUS-WIDE have VGG-16/BERT source representations but store processed 100/100-column views in the supplied MAT files. Actual shapes are always available in data.feature_dims and the interface. Photo/Arts origins and Grocery-S subset construction remain undocumented; reference links provide background rather than verified provenance for every processed artifact.

See dataset descriptions, graph meanings and all variants. If an upload is still pending, its loader reports the unavailable file; the same download link becomes usable once published.

Load data and choose views

from polyclustx.data import load_data, load_mat

data = load_data("acm", views={
    "Co-authorship": ("X1_features", "A1_PAP"),
    "Shared subjects": ("X1_features", "A2_PLP"),
    "Both relations": ("X1_features", ["A1_PAP", "A2_PLP"]),
    "Keywords only": "X1_features",
})
# The same feature is reused; each view has the graphs you selected.

captions = load_data("pascal", variant="clip")
my_data = load_mat("my_data.mat")  # recognizes X*, A* and labels

One named entry creates a single view; several graphs in one entry are fused at fitting/preparation time. Source files and previous experiment results stay unchanged. Loading and composition guide.

Available methods

Graphs ✓ means the method uses supplied adjacency matrices. Missing views ✓ means native support for an observation mask.

Capabilities differ by method. Some single-view and multi-view cases are framework adaptations; UMC uses supplied features without pretrained encoders. See algorithm details, assumptions and references. These implementations do not claim to reproduce the papers' benchmark scores.

Explore and visualize

The interface provides dataset preparation, named models, repeated experiments, hyperparameter search, visualizations and JSON/CSV/ZIP exports. Labels enable benchmark metrics; without labels, use internal metrics. Interface guide.

The notebooks are unexecuted tutorials for you to run. Start with the end-to-end study to compare methods on Iris and Wine, add graphs, visualize embeddings and losses, search hyperparameters and export results.

Documentation

Browse the documentation, start with the worked examples, or follow the interactive interface guide.

Research affiliations

Centre Borelli · Université Paris Cité. Institutional marks remain separate from PolyClustX and do not imply endorsement.

References

Cite the original papers when using these methods in research. Reference code links identify the implementations that informed the framework adaptations.

License

The software license and third-party notices are in LICENSE. Institutional logos are not covered by the software's MIT license. Cite the original algorithm papers when publishing results.