# sisinflab/personalized-popularity-awareness architecture

> Architecture diagram of the GitHub repository sisinflab/personalized-popularity-awareness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sisinflab/personalized-popularity-awareness
- Repository: https://github.com/sisinflab/personalized-popularity-awareness

## Overview

This repository reproduces music-recommendation experiments comparing global and personalized popularity with sequential Transformer recommenders. The principal workflow loads Last.fm-1K or Yandex interactions, splits them temporally, configures and trains recommenders, then evaluates ranked results with NDCG. Dataset statistics and the API/recommender abstraction are useful supporting layers. The graph preserves the documented popularity, BERT4Rec, SASRec, and popularity-augmented model families. Some subsystem links rely on the README or source-index references; unsampled implementation details are not inferred.

Main entry points: [`evaluation/configs`](https://github.com/sisinflab/personalized-popularity-awareness/tree/main/evaluation/configs) (Experiment configurations), [`datasets/datasets_register.py`](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/datasets/datasets_register.py) (Dataset registry), [`evaluation/evaluate_recommender.py`](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/evaluation/evaluate_recommender.py) (Recommender evaluator), [`evaluation/run_experiment.py`](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/evaluation/run_experiment.py) (Experiment runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Music data"]
  node_events["Interaction API<br/>[track_event.py]"]
  node_yandex["Yandex loader<br/>[yandex.py]"]
  node_lastfm["Last.fm loader<br/>[lastfm1k.py]"]
  node_registry["Dataset registry"]
  node_stats["Dataset statistics<br/>[dataset_stats.py]"]
end

subgraph group_experiment["Experiment evaluation"]
  node_runner["Experiment runner<br/>[run_experiment.py]"]
  node_configs["Experiment configurations"]
  node_split["Temporal splitting<br/>[split_actions.py]"]
  node_evaluator["Recommender evaluator"]
  node_ndcg["NDCG metrics<br/>[ndcg.py]"]
end

subgraph group_recommend["Recommendation methods"]
  node_contract["Recommender API<br/>[recommender.py]"]
  node_popularity["Popularity recommenders"]
end

subgraph group_models["Sequential models"]
  node_bert["BERT4Rec<br/>[bert4rec_gts.py]"]
  node_bertpop["BERT4Rec popularity"]
  node_sasrec["SASRec<br/>[sasrec.py]"]
  node_sasrecgts["SASRec GTS<br/>[sasrec_gts.py]"]
  node_sasrecpop["SASRec popularity<br/>[sasrec_gts_pop.py]"]
  node_gsasrec["gSASRec GTS<br/>[gsasrec_gts.py]"]
  node_gsasrecpop["gSASRec popularity<br/>[gsasrec_gts_pop.py]"]
end

node_researcher(("Experiment runner"))

node_researcher -->|"starts"| node_runner
node_runner -->|"loads datasets"| node_registry
node_registry -->|"selects loader"| node_yandex
node_registry -->|"selects loader"| node_lastfm
node_yandex -->|"creates events"| node_events
node_lastfm -->|"creates events"| node_events
node_runner -->|"runs evaluation"| node_evaluator
node_configs -->|"configures runs"| node_runner
node_configs -->|"selects split"| node_split
node_configs -->|"selects metric"| node_ndcg
node_configs -->|"selects model"| node_popularity
node_configs -->|"selects model"| node_bert
node_configs -->|"selects model"| node_bertpop
node_configs -->|"selects model"| node_sasrecgts
node_configs -->|"selects model"| node_sasrecpop
node_configs -->|"selects model"| node_gsasrec
node_configs -->|"selects model"| node_gsasrecpop
node_evaluator -->|"splits actions"| node_split
node_evaluator -->|"trains and requests"| node_contract
node_evaluator -->|"calculates metrics"| node_ndcg
node_popularity -->|"implements API"| node_contract
node_bert -->|"implements API"| node_contract
node_bertpop -->|"implements API"| node_contract
node_sasrecgts -->|"uses backbone"| node_sasrec
node_sasrecpop -->|"uses backbone"| node_sasrec
node_gsasrec -->|"uses backbone"| node_sasrec
node_gsasrecpop -->|"uses backbone"| node_sasrec
node_registry -.->|"supports statistics"| node_stats

click node_events "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/api/track_event.py"
click node_yandex "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/datasets/yandex.py"
click node_lastfm "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/datasets/lastfm1k.py"
click node_registry "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/datasets/datasets_register.py"
click node_stats "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/datasets/dataset_stats.py"
click node_runner "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/evaluation/run_experiment.py"
click node_configs "https://github.com/sisinflab/personalized-popularity-awareness/tree/main/evaluation/configs"
click node_split "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/evaluation/split_actions.py"
click node_evaluator "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/evaluation/evaluate_recommender.py"
click node_ndcg "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/evaluation/metrics/ndcg.py"
click node_contract "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/recommender.py"
click node_popularity "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/popularity_recommender.py"
click node_bert "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/BERT4Rec/bert4rec_gts.py"
click node_bertpop "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/BERT4Rec/bert4rec_gts_pop.py"
click node_sasrec "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/SASRec/sasrec.py"
click node_sasrecgts "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/SASRec/sasrec_gts.py"
click node_sasrecpop "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/SASRec/sasrec_gts_pop.py"
click node_gsasrec "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/SASRec/gsasrec_gts.py"
click node_gsasrecpop "https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/SASRec/gsasrec_gts_pop.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_events,node_yandex,node_lastfm,node_registry,node_stats toneBlue
class node_runner,node_configs,node_split,node_evaluator,node_ndcg toneAmber
class node_contract,node_popularity toneMint
class node_bert,node_bertpop,node_sasrec,node_sasrecgts,node_sasrecpop,node_gsasrec,node_gsasrecpop toneRose
class node_researcher toneIndigo
```

## Components

### Music data

- [Interaction API](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/api/track_event.py): `api/track_event.py`
- [Yandex loader](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/datasets/yandex.py): `datasets/yandex.py`
- [Last.fm loader](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/datasets/lastfm1k.py): `datasets/lastfm1k.py`
- [Dataset registry](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/datasets/datasets_register.py): `datasets/datasets_register.py`
- [Dataset statistics](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/datasets/dataset_stats.py): `datasets/dataset_stats.py`

### Experiment evaluation

- [Experiment runner](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/evaluation/run_experiment.py): `evaluation/run_experiment.py`
- [Experiment configurations](https://github.com/sisinflab/personalized-popularity-awareness/tree/main/evaluation/configs): `evaluation/configs`
- [Temporal splitting](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/evaluation/split_actions.py): `evaluation/split_actions.py`
- [Recommender evaluator](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/evaluation/evaluate_recommender.py): `evaluation/evaluate_recommender.py`
- [NDCG metrics](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/evaluation/metrics/ndcg.py): `evaluation/metrics/ndcg.py`

### Recommendation methods

- [Recommender API](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/recommender.py): `recommenders/recommender.py`
- [Popularity recommenders](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/popularity_recommender.py): `recommenders/popularity_recommender.py`

### Sequential models

- [BERT4Rec](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/BERT4Rec/bert4rec_gts.py): `recommenders/sequential/BERT4Rec/bert4rec_gts.py`
- [BERT4Rec popularity](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/BERT4Rec/bert4rec_gts_pop.py): `recommenders/sequential/BERT4Rec/bert4rec_gts_pop.py`
- [SASRec](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/SASRec/sasrec.py): `recommenders/sequential/SASRec/sasrec.py`
- [SASRec GTS](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/SASRec/sasrec_gts.py): `recommenders/sequential/SASRec/sasrec_gts.py`
- [SASRec popularity](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/SASRec/sasrec_gts_pop.py): `recommenders/sequential/SASRec/sasrec_gts_pop.py`
- [gSASRec GTS](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/SASRec/gsasrec_gts.py): `recommenders/sequential/SASRec/gsasrec_gts.py`
- [gSASRec popularity](https://github.com/sisinflab/personalized-popularity-awareness/blob/main/recommenders/sequential/SASRec/gsasrec_gts_pop.py): `recommenders/sequential/SASRec/gsasrec_gts_pop.py`

### Other components

- **Experiment runner**

## Connections

- Experiment runner → Experiment runner: starts
- Experiment runner → Dataset registry: loads datasets (evidence: `evaluation/run_experiment.py`)
- Dataset registry → Yandex loader: selects loader (evidence: `datasets/datasets_register.py`)
- Dataset registry → Last.fm loader: selects loader (evidence: `datasets/datasets_register.py`)
- Yandex loader → Interaction API: creates events (evidence: `datasets/yandex.py`)
- Last.fm loader → Interaction API: creates events (evidence: `datasets/lastfm1k.py`)
- Experiment runner → Recommender evaluator: runs evaluation (evidence: `evaluation/run_experiment.py`)
- Experiment configurations → Experiment runner: configures runs
- Experiment configurations → Temporal splitting: selects split (evidence: `evaluation/configs/yandex_all.py`)
- Experiment configurations → NDCG metrics: selects metric (evidence: `evaluation/configs/yandex_all.py`)
- Experiment configurations → Popularity recommenders: selects model (evidence: `evaluation/configs/yandex_all.py`)
- Experiment configurations → BERT4Rec: selects model (evidence: `evaluation/configs/yandex_all.py`)
- Experiment configurations → BERT4Rec popularity: selects model (evidence: `evaluation/configs/yandex_all.py`)
- Experiment configurations → SASRec GTS: selects model (evidence: `evaluation/configs/yandex_all.py`)
- Experiment configurations → SASRec popularity: selects model (evidence: `evaluation/configs/yandex_all.py`)
- Experiment configurations → gSASRec GTS: selects model (evidence: `evaluation/configs/yandex_all.py`)
- Experiment configurations → gSASRec popularity: selects model (evidence: `evaluation/configs/yandex_all.py`)
- Recommender evaluator → Temporal splitting: splits actions (evidence: `evaluation/evaluate_recommender.py`)
- Recommender evaluator → Recommender API: trains and requests (evidence: `evaluation/evaluate_recommender.py`)
- Recommender evaluator → NDCG metrics: calculates metrics (evidence: `evaluation/evaluate_recommender.py`)
- Popularity recommenders → Recommender API: implements API (evidence: `recommenders/popularity_recommender.py`)
- BERT4Rec → Recommender API: implements API (evidence: `recommenders/sequential/BERT4Rec/bert4rec_gts.py`)
- BERT4Rec popularity → Recommender API: implements API (evidence: `recommenders/sequential/BERT4Rec/bert4rec_gts_pop.py`)
- SASRec GTS → SASRec: uses backbone (evidence: `recommenders/sequential/SASRec/sasrec_gts.py`)
- SASRec popularity → SASRec: uses backbone (evidence: `recommenders/sequential/SASRec/sasrec_gts_pop.py`)
- gSASRec GTS → SASRec: uses backbone (evidence: `recommenders/sequential/SASRec/gsasrec_gts.py`)
- gSASRec popularity → SASRec: uses backbone (evidence: `recommenders/sequential/SASRec/gsasrec_gts_pop.py`)
- Dataset registry → Dataset statistics: supports statistics (evidence: `datasets/stats/lastfm1k_dataset.py`)
