# hieptk/accent architecture

> Architecture diagram of the GitHub repository hieptk/accent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hieptk/accent
- Repository: https://github.com/hieptk/accent

## Overview

##### Main Components
a. Data Layer:
- Data for NCF: Located in NCF/data with the MovieLens training file (movielens_train.tsv).
- Data for RCF: Located in RCF/data, including train.csv, test.csv, u.data, auxiliary-mapping.txt, and relational_data.csv.
b. Model Components:
- NCF Module:
- Core implementation files in NCF/src (e.g., train.py, experiment.py, get_rec.py, etc.).
- A specific “influence” submodule in NCF/src/influence for influence function implementation.
- Scripts folder (NCF/src/scripts) which contains auxiliary and support scripts.
- RCF Module:
- Main implementation files in RCF/src (e.g., train.py, experiment.py, rcf.py, pure_attention.py, etc.).
c. Common Utilities:
- Commons directory contains template and helper scripts (e.g., accent_template.py, fia_template.py, explanation_algorithm_template.py, helper.py).
- Other standalone files like compare.py for evaluation and significance testing.
d. Environment and Configuration:
- Requirements file (requirements.txt) and an initialization script (init) to set up the environment.
- LICENSE and README provide context for experimental setup and usage.

##### Relationships and Interactions
- Data Flow:
- Data is preprocessed (as shown by scripts like generate_data.py in RCF/src and load_movielens.py in NCF/src/scripts) and fed into each recommender system.
- Each system (NCF and RCF) has its own training pipeline (train.py) that reads from the data layer, builds a model using the provided frameworks (such as TensorFlow), and saves the trained models (e.g., “pretrain-rcf” directory for RCF).
- Experiment and Explanation Pipeline:
- Once a model is trained, the experiment scripts (experiment.py in both NCF/src and RCF/src) invoke different counterfactual explanation algorithms.
- These experiments result in output CSV files containing the evaluation results (with scores, predicted results, and counterfactual explanations).
- Evaluation and Significance Testing:
- The compare.py script is used to analyze the explanation quality, run t-tests and McNemar’s tests, and generate comparative metrics between the results of different explanation methods.
- Common Modules and Reusability:
- Shared functionality is abstracted out in the “commons” directory and reusable helper functions that support both NCF and RCF pipelines.

##### Architectural Patterns and Design Principles
- Modularity: The project is split into two parallel modules (NCF and RCF) with similar structures, encapsulating the functionality for different recommender models.
- Separation of Concerns: Data processing, model training, explanation generation, and evaluation are all separated into distinct directories and scripts.
- Reusability: Common functionalities such as helper functions and templates are isolated into their own directory (commons), promoting code reuse.
- Experimentation Workflow: The design clearly supports conducting experiments and statistical testing, an important element of research codebases.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% NCF Module
    subgraph "NCF Module"
        NCFData["NCF Data"]:::ncf
        NCFTrain["NCF Training Module"]:::ncf
        NCFInfluence["NCF Influence Submodule"]:::ncf
        NCFAux["NCF Auxiliary Scripts"]:::ncf
        NCFExp["NCF Experimentation Module"]:::ncf
    end

    %% RCF Module
    subgraph "RCF Module"
        RCFData["RCF Data"]:::rcf
        RCFTrain["RCF Training Module"]:::rcf
        RCFExplain["RCF Explanation Scripts"]:::rcf
        RCFExp["RCF Experimentation Module"]:::rcf
    end

    %% Common and Evaluation
    subgraph "Common & Evaluation"
        Common["Common Utilities"]:::common
        Eval["Evaluation Module"]:::evaluation
    end

    %% Environment and Configuration
    subgraph "Environment & Config"
        Env["Environment & Config"]:::env
    end

    %% Data Flow and Dependencies for NCF
    NCFData -->|"feeds"| NCFTrain
    NCFInfluence -->|"supports"| NCFTrain
    NCFAux -->|"assists"| NCFTrain
    NCFTrain -->|"trains"| NCFExp
    NCFExp -->|"outputs"| Eval

    %% Data Flow and Dependencies for RCF
    RCFData -->|"feeds"| RCFTrain
    RCFTrain -->|"trains"| RCFExp
    RCFExplain -->|"provides"| RCFExp
    RCFExp -->|"outputs"| Eval

    %% Common Utilities Usage
    Common -->|"utilizes"| NCFTrain
    Common -->|"utilizes"| NCFExp
    Common -->|"utilizes"| RCFTrain
    Common -->|"utilizes"| RCFExp

    %% Environment & Config Influence
    Env -->|"configures"| NCFTrain
    Env -->|"configures"| RCFTrain
    Env -->|"configures"| Common

    %% Click Events
    click NCFData "https://github.com/hieptk/accent/blob/main/NCF/data/movielens_train.tsv"
    click RCFData "https://github.com/hieptk/accent/tree/main/RCF/data"
    click NCFTrain "https://github.com/hieptk/accent/blob/main/NCF/src/train.py"
    click NCFExp "https://github.com/hieptk/accent/blob/main/NCF/src/experiment.py"
    click NCFInfluence "https://github.com/hieptk/accent/tree/main/NCF/src/influence"
    click NCFAux "https://github.com/hieptk/accent/tree/main/NCF/src/scripts"
    click RCFTrain "https://github.com/hieptk/accent/blob/main/RCF/src/train.py"
    click RCFExp "https://github.com/hieptk/accent/blob/main/RCF/src/experiment.py"
    click RCFExplain "https://github.com/hieptk/accent/tree/main/RCF/src"
    click Common "https://github.com/hieptk/accent/tree/main/commons"
    click Eval "https://github.com/hieptk/accent/blob/main/compare.py"
    click Env "https://github.com/hieptk/accent/blob/main/requirements.txt"

    %% Class Definitions
    classDef ncf fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef rcf fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef common fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef env fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef evaluation fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
