HGHC

Code for Hypergraph-Based High-Order Correlation Analysis for Large-Scale Long-Tailed Data Classification.

Installation

Python 3.11 or later.

pip install -r requirements.txt

Data

Each dataset directory contains four files:

Datasets/
└── Amazon-LT-1000/
    ├── asins_1000.pkl
    ├── features_1000.pkl
    ├── labels_1000.pkl
    └── user_products_1000.json

For Amazon-LT-10000 and Amazon-LT-100000, use the corresponding directory name and filename suffix.

• The item file stores item identifiers as prefix–ASIN pairs.
• The feature file contains a features matrix and matching prefixes/asins, pairs, or unique asins.
• The label file contains integer labels. Without identifiers, its rows must follow the feature file order.
• The user file is a JSON array of {"user": "...", "items": [{"prefix": "...", "asin": "..."}]} records.

Prepare a dataset:

python main.py prepare --data-dir ./Datasets/Amazon-LT-1000 --output ./data/Amazon-LT-1000

By default, hyperedges with fewer than two items are removed and identical member sets are merged. Use --min-edge-size and --keep-duplicate-edges to configure this step.

Training

python main.py train --data ./data/Amazon-LT-1000 --output ./runs/Amazon-LT-1000 --seeds 0 --device cuda:0

The training set contains 50 × number of classes samples, with at least three per class. The validation set has the same total size by default; --val-size sets another size. Remaining samples form the test set. The model with the lowest validation cross-entropy is evaluated on the test set.

Omit --seeds 0 to run seeds 0–9. Use --device cpu for CPU execution. Use --without-hsmote to run HGHC without oversampling.

Settings are defined in config.py. A JSON file passed through --config can override them. To supply an existing split, use --split-file split.npz with one seed; the file must contain disjoint integer arrays named train, val, and test, covering all dataset rows and satisfying the training size above.

Each seed directory saves the model, split, synthetic vertices, training history, predictions, and metrics. summary.json contains the mean and sample standard deviation across seeds. Use a new output directory for a new run.

Evaluation

Evaluate a saved model:

python main.py evaluate --data ./data/Amazon-LT-1000 --run ./runs/Amazon-LT-1000/seed_0 --device cuda:0

Both training and evaluation accept:

Option	Choices	Training default
--f1-average	macro, micro, weighted	macro
--auc-mode	ovr, ovo	ovr
--auc-average	macro, weighted	macro

Evaluation uses the saved metric settings unless overridden. Metric values range from 0 to 1; outputs record their definitions, and dataset.json stores the class mapping. For binary classification, AUC uses the second class as the positive class. Add --output metrics.json to save a separate evaluation file.

Files

File	Content
main.py	Data preparation, training, and evaluation commands
config.py	Model and training settings
data.py	Input loading, item alignment, hypergraph construction, and splits
models.py	Encoders, decoder, and classifier
hsmote.py	HSMOTE training and vertex generation
ppr.py	Approximate PPR and top-k selection
training.py	MHEN training and inference
metrics.py	Accuracy, F1, and AUC