Graph Embeddings with Cleora

This project evaluates the quality of node embeddings obtained using Cleora on the Walmart-trips dataset. It demonstrates how to generate embeddings for a hypergraph, evaluate their quality for node classification, and visualize them using dimensionality reduction.

Project Structure

• source/ – Contains the main Python scripts:
  • cleora_walmart_embeddings.py: Main script for generating and evaluating embeddings
  • demo.py: Example script demonstrating basic Cleora usage
• notebooks/ – Jupyter notebooks with interactive analysis
• figures/ – Generated visualizations:
  • Performance comparison plots
  • UMAP visualizations of embeddings
• reports/ – Detailed analysis reports
• data/ – Dataset files (Walmart-trips hypergraph)

Dataset

The Walmart-trips dataset is a hypergraph where hyperedges are sets of co-purchased products at Walmart. Products are assigned to one of ten broad departments, which serve as node labels.

Dataset statistics:

• Number of nodes: 88,860
• Number of hyperedges: 69,906
• Mean / median hyperedge size: 6.6 / 5
• Rank of hypergraph (maximum hyperedge size): 25
• Number of node classes: 11

Tasks

Task 1: Quality Evaluation of Node Embeddings

We evaluate the quality of node embeddings obtained using Cleora by:

1. Preparing the Walmart-trips dataset in the CLEORA input scheme
2. Producing embeddings with different settings of Markov random walk steps (3, 5, and 7)
3. Evaluating the embeddings for node classification

Task 2: Visualization of Embeddings

We visualize the embeddings by:

1. Reducing the dimension to 2 using UMAP
2. Plotting the embeddings, highlighting the clusters with colors

Usage

To run the main script:

uv run python src/cleora_walmart_embeddings.py

This will generate embeddings, evaluate them, and create visualizations in the figures/ directory.

Results

The evaluation shows that:

1. Walk Length Impact: Longer walk lengths (5 and 7) generally perform better than shorter ones (3), suggesting that capturing more global structure in the hypergraph is beneficial for node classification.

2. Classification Performance: The embeddings achieve moderate accuracy (around 35%), which is significantly better than random guessing (9% for 11 classes).

3. Visualization: The UMAP visualization confirms that the embeddings capture meaningful relationships between nodes, with distinct clusters forming for different product categories.

Detailed results can be found in the reports/ directory.

Requirements

• Python 3.12+
• pycleora
• umap-learn
• numpy
• pandas
• matplotlib
• scikit-learn