EDuRec

EDuRec is a PyTorch Lightning recommendation system for e-learning datasets. It combines collaborative graph signals, user and item side information, item text representations, and sequential user history to recommend educational resources.

This repository is part of the Master's Thesis by Francisco de Paula Algar Munoz at the Menendez Pelayo International University.

Project Description

The project implements and evaluates a hybrid educational recommender for implicit and explicit student-resource interactions. The codebase includes:

• Dataset loaders and preprocessing for mars, itm, and doris.
• The proposed EDuRec model, implemented with PyTorch, PyTorch Geometric, and Lightning.
• Training, testing, dataset inspection, hyperparameter optimization, benchmark evaluation, and ablation commands through a Typer CLI.
• RecBole-based comparisons against classical and state-of-the-art recommenders.
• Ranking metrics at multiple cutoffs, including Precision, Recall, NDCG, Hit Rate, MAP, and MRR.

Installation

The project uses Python 3.12 or newer and uv for dependency management.

git clone https://github.com/Pacatro/EDuRec.git
cd EDuRec
uv sync

For development dependencies such as pytest and mlflow, use:

uv sync --group dev

The repository expects raw datasets under data/raw/<dataset>. The included loaders currently support:

• data/raw/mars
• data/raw/itm
• data/raw/doris

Usage

All commands are exposed through the edurec CLI.

uv run edurec --help

Global options:

-d, --device [auto|cpu|cuda]  Device to use
-r, --random-state INTEGER    Random seed
-v, --verbose                 Verbose output
-h, --help                    Show help

Inspect a Dataset

Print basic statistics and sample rows from a dataset.

uv run edurec dataset --dataset explicit_mars --max_rows 10

Options:

-d, --dataset [explicit_mars|implicit_mars|itm|doris]  Dataset to use
-m, --max_rows INTEGER          Number of rows to show

Train EDuRec

Train the proposed model on one dataset. If --dataset is omitted, the command iterates through all registered datasets.

uv run edurec train --dataset explicit_mars --use_processed --save_model

Common options:

-d, --dataset [explicit_mars|implicit_mars|itm|doris]
-e, --epochs INTEGER            Default: from saved train config
-l, --lr FLOAT                  Default: from saved train config
-b, --batch_size INTEGER        Default: from saved train config
-p, --patience INTEGER          Default: from saved train config
-v, --val_size FLOAT            Default: 0.1
-t, --test_size FLOAT           Default: 0.2
-k, --top_k INTEGER             Default: 20
-R, --remove_sparse             Remove sparse users/items
-i, --min_interactions INTEGER  Default: 3
-a, --adaptive_k                Use adaptive-k metrics where supported
-D, --debug                     Fast debug run
-S, --save_model                Save checkpoint, config, and metrics
-P, --use_processed             Reuse cached processed data
-M, --models-folder TEXT        Default: models
-C, --configs-folder TEXT       Default: configs
-E, --experiment-name TEXT      Optional logger experiment name

Test a Saved Model

Load the most recent saved model for a dataset and evaluate it on the test split.

uv run edurec test --dataset explicit_mars --use_processed

Options include dataset, batch size, validation/test split sizes, top-k, adaptive-k, sparse filtering, and the models folder.

Evaluate EDuRec and SOTA Models

Run the proposed EDuRec model and RecBole baselines on the selected dataset. If --dataset is omitted, all datasets are evaluated.

uv run edurec eval --dataset itm --use-processed --top-k 5 --top-k 10 --top-k 20

Default SOTA models:

• ItemKNN
• NeuMF
• LightGCN
• MultiVAE
• SGL
• SASRec
• BERT4Rec

Useful options:

-d, --dataset [explicit_mars|implicit_mars|itm|doris]
-e, --epochs INTEGER            Default: from saved train config
-l, --lr FLOAT                  Default: from saved train config
-b, --batch-size INTEGER        Default: from saved train config
-p, --patience INTEGER          Default: from saved train config
-k, --top-k INTEGER             Repeat for multiple cutoffs
-R, --remove-sparse / -K, --keep-sparse
-I, --min-interactions INTEGER  Default: 3
-P, --use-processed / -N, --no-use-processed
-c, --cfg-path FILE             Extra RecBole config
-m, --sota-model TEXT           Repeat to choose baseline models
-a, --adaptive-k / -A, --fixed-k

Results are written to results/evaluations/<dataset>/, with one CSV per model and seed, the detailed evaluation_results.csv, and the aggregated evaluation_summary.csv.

Optimize Hyperparameters

Run Optuna-based hyperparameter optimization for EDuRec.

uv run edurec optim --dataset explicit_mars --trials 30 --use_processed

The command saves the best model and training configurations, trial log, and study database under results/optimization/<dataset>/. It also writes the best configuration for each dataset to configs/model/<dataset>.yaml and configs/train/<dataset>.yaml, so they can be reused by training and evaluation. Use --configs-folder to choose a different folder.

Saved Configurations

The configs/ folder keeps one model configuration and one independent training configuration per evaluated dataset:

configs/model/<dataset>.yaml   Model architecture hyperparameters
configs/train/<dataset>.yaml   Training hyperparameters (epochs, lr, batch size,
                               patience, weight decay, top-k, alpha, adaptive-k)

When a config file exists for the dataset being run, training, evaluation, and ablation commands load it. Explicit CLI flags always take precedence over the saved configurations, which in turn take precedence over the global defaults in edurec/settings.py.

Run Ablations

Evaluate EDuRec variants across multiple random seeds.

uv run edurec ablation --dataset doris --seeds 13,42,77,101,2026 --use_processed

Implemented main variants:

• base: ID-only dot-product baseline.
• full: full EDuRec architecture.
• no_graph: removes LightGCN and graph contrastive learning.
• no_features: removes both user and item feature encoders.
• no_user_features / no_item_features: removes one side-feature encoder.
• no_text: removes the text embeddings from the user/item feature encoders.
• no_sequence: removes SASRec history encoding.
• no_context: removes the independent interaction-context representation.
• sum_fusion: replaces MaskedGatedFusion with a direct sum of the module representations.
• no_gcl: removes graph contrastive learning.
• no_item_bias: removes the learned item-popularity bias.
• dot_product: replaces the MLP scorer with dot-product scoring.

Aggregated outputs are saved to results/ablations/<dataset>/.

Model Architecture

EDuRec builds user and item representations from multiple complementary modules:

• Graph encoder: a LightGCN-style encoder over the user-item interaction graph produces collaborative user and item embeddings.
• Feature encoders: MLP encoders transform dense and categorical user/item features into the shared embedding space.
• Text features: preprocessed text embeddings are consumed by the user/item feature encoders together with the other dense features.
• Sequential encoder: a SASRec-style Transformer encodes each user's recent item history.
• Gated fusion: learned global gates weight and combine the available user and item representations.
• Scorer: the final user and item embeddings are scored with either an MLP scorer or a dot-product scorer. An optional item bias can be added.

Module availability is inferred from each processed dataset when the model configuration is built. Feature encoders, the sequential encoder, contextual inputs, and their fusion slots are omitted when their required data is absent. Single-source representations also bypass the fusion layer, avoiding unused parameters and computation.

Sequential history modules additionally require a real chronological interaction field. Datasets without one are split randomly and do not allocate history tensors; a synthetic row index is not considered a valid timestamp. Interaction context has an independent encoder and remains available without a sequential history. It is kept separate from the user representation: the final scorer consumes user, item, and context representations explicitly.

Training uses cross-entropy over all candidate items. When enabled, graph contrastive learning applies edge dropout to create two graph views and adds an InfoNCE loss for user and item embeddings.

Implemented Experiments

Proposed Model Evaluation

uv run edurec eval trains EDuRec, evaluates the best checkpoint on the test split, and reports Precision, Recall, NDCG, Hit Rate, MAP, and MRR at the configured top-k values.

SOTA Benchmark Evaluation

The same evaluation command exports RecBole atomic files and runs the baseline models with aligned split files, learning rate, epoch count, patience, batch size, and top-k settings. Sequential baselines receive prebuilt histories for the original train, validation, and test splits instead of asking RecBole to split the merged interaction file again.

Final ranking metrics use one shared evaluator for every model. Each positive test interaction is one query with one target, and EDuRec and the RecBole baselines use the same full item catalog, seen-item mask, and TorchMetrics implementations for Precision, Recall, NDCG, Hit Rate, MAP, and MRR.

Hyperparameter Optimization

uv run edurec optim runs Optuna studies for EDuRec and saves the best model and training configurations as YAML for later training, evaluation, or ablation experiments.

Ablation Study

uv run edurec ablation evaluates architecture variants across configurable seeds and records metrics, parameter counts, and per-run configuration files. This is intended to isolate the contribution of graph modeling, side features, text features, sequential history, context, gated fusion, graph contrastive learning, item bias, and the scoring function.

Author

Francisco de Paula Algar Munoz

Advisors

Amelia Zafra Gomez

License

This project is licensed under the MIT License. See LICENSE for details.