# wzh9969/contrastive-htc architecture

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

- Interactive diagram: https://gitdiagram.com/wzh9969/contrastive-htc
- Repository: https://github.com/wzh9969/contrastive-htc

## Overview

##### Main Components
- Data / Preprocessing Layer:
- Three main dataset directories (data/WebOfScience, data/nyt, data/rcv1) each containing scripts to preprocess and load data.
- Includes specific preprocessing scripts (e.g., preprocess_wos.py, preprocess_rcv1.py) and data conversion scripts (e.g., data_wos.py, data_rcv1.py, data_nyt.py).
- Model / Training Layer:
- The training module (train.py) which accepts several hyperparameters and options to select contrastive learning mode and graph encoder usage.
- The “model” directory containing key modules:
· contrast.py: likely implements the contrastive learning loss or methodology.
· graph.py: handles graph- or tree-structured encoding to incorporate hierarchy.
· optim.py: manages optimization strategies.
- The main training routine handles data ingestion, batch processing, model training (with options for gradient accumulation, warmup, etc.), and checkpoint saving.
- Evaluation / Testing Layer:
- test.py and eval.py provide endpoints for model evaluation.
- They use checkpoints (stored in checkpoints/DATA-NAME) based on best macro-F1 and micro-F1 values.
- Utilities and Configuration:
- Global utilities in utils.py.
- Requirement file (requirement.txt) and additional configuration via command-line arguments (as described in the README).

##### Relationships and Interactions
- Data flows from the raw datasets into the preprocessing scripts. Preprocessed data is then fed into the training module.
- The training script calls the modules inside the “model” directory (contrast.py, graph.py, optim.py) that together implement the contrastive learning architecture and incorporate hierarchical relationships.
- Once trained, the resulting model checkpoints are passed to the testing script, which evaluates performance using test.py and/or eval.py.
- Utility functions (in utils.py) support common tasks across preprocessing, training, and evaluation.

##### Important Architectural Patterns and Design Principles
- Modular Design: The project separates the concerns of data handling, model architecture, training procedures, and evaluation.
- Layered Architecture: Separate “data” (loading/preprocessing), “model” (learning components), and “evaluation” layers enable clear responsibilities.
- Command-Line Configurability: The use of arguments in train.py and test.py allows flexibility and reproducibility, with different settings for various datasets.
- Extensibility: The modularity (especially with model components separated into contrast, graph, etc.) provides points where additional improvements or alternative encodings can be integrated.

##### Relevant Technologies and Frameworks
- Python (>=3.6)
- PyTorch (for neural network implementation)
- Transformers (for language models)
- Fairseq (for sequence modeling)
- PyTorch Geometric, torch-scatter, and torch-sparse (for graph operations)

##### Elements
- Clear labels for each component:
▪ For example: “Data Preprocessing – WebOfScience”, “Contrastive Module”, “Graph Encoder”, “Training Engine”, “Evaluation Module”.

- The data ingestion and preprocessing pipelines (for each dataset).
- The core model training pipeline which integrates contrastive learning and hierarchical graph encoding.
- The evaluation/testing procedures that access saved checkpoints.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data & Preprocessing Layer
    subgraph "Data & Preprocessing"
        subgraph "WebOfScience"
            WebPre["Preprocessing"]:::dataLayer
            WebData["Data Conversion"]:::dataLayer
        end
        subgraph "NYT"
            Nyt["Data Loading"]:::dataLayer
        end
        subgraph "RCV1"
            RcvPre["Preprocessing"]:::dataLayer
            RcvData["Data Conversion"]:::dataLayer
        end
    end

    %% Training Layer
    subgraph "Training"
        TrainingEngine["Training Engine"]:::trainingLayer
        subgraph "Model Modules"
            Contrast["Contrastive Module"]:::trainingLayer
            GraphEnc["Graph Encoder Module"]:::trainingLayer
            Optimizer["Optimization Engine"]:::trainingLayer
        end
        subgraph "Utilities & Config"
            Utils["Utilities"]:::trainingLayer
            Requirements["Requirements"]:::trainingLayer
        end
    end

    %% Evaluation Layer
    subgraph "Evaluation"
        Eval["Evaluation Module (eval.py)"]:::evaluationLayer
        Test["Testing Module (test.py)"]:::evaluationLayer
    end

    %% External Dependencies
    ExtDep["External Dependencies: PyTorch, Transformers, Fairseq, PyTorch Geometric, torch-scatter, torch-sparse"]:::external

    %% Connections from Data to Training
    WebPre -->|"preprocessed data"| TrainingEngine
    WebData -->|"converted data"| TrainingEngine
    Nyt -->|"loaded data"| TrainingEngine
    RcvPre -->|"preprocessed data"| TrainingEngine
    RcvData -->|"converted data"| TrainingEngine

    %% Training engine invokes model modules and utilities
    TrainingEngine -->|"triggers"| Contrast
    TrainingEngine -->|"triggers"| GraphEnc
    TrainingEngine -->|"triggers"| Optimizer
    TrainingEngine -->|"uses"| Utils
    TrainingEngine -->|"reads"| Requirements

    %% Interaction among model modules
    Contrast -->|"feeds into"| GraphEnc

    %% Training outputs checkpoints to Evaluation
    TrainingEngine -->|"checkpoints"| Eval
    TrainingEngine -->|"checkpoints"| Test

    %% Evaluation optionally uses utilities
    Utils ---|"support"| Eval
    Utils ---|"support"| Test

    %% External Dependencies support the training & evaluation processes
    ExtDep ---|"libraries support"| TrainingEngine
    ExtDep ---|"libraries support"| Eval
    ExtDep ---|"libraries support"| Test

    %% Click Events for Component Mappings
    click WebPre "https://github.com/wzh9969/contrastive-htc/blob/main/data/WebOfScience/preprocess_wos.py"
    click WebData "https://github.com/wzh9969/contrastive-htc/blob/main/data/WebOfScience/data_wos.py"
    click Nyt "https://github.com/wzh9969/contrastive-htc/blob/main/data/nyt/data_nyt.py"
    click RcvPre "https://github.com/wzh9969/contrastive-htc/blob/main/data/rcv1/preprocess_rcv1.py"
    click RcvData "https://github.com/wzh9969/contrastive-htc/blob/main/data/rcv1/data_rcv1.py"
    click TrainingEngine "https://github.com/wzh9969/contrastive-htc/blob/main/train.py"
    click Contrast "https://github.com/wzh9969/contrastive-htc/blob/main/model/contrast.py"
    click GraphEnc "https://github.com/wzh9969/contrastive-htc/blob/main/model/graph.py"
    click Optimizer "https://github.com/wzh9969/contrastive-htc/blob/main/model/optim.py"
    click Eval "https://github.com/wzh9969/contrastive-htc/blob/main/eval.py"
    click Test "https://github.com/wzh9969/contrastive-htc/blob/main/test.py"
    click Utils "https://github.com/wzh9969/contrastive-htc/blob/main/utils.py"
    click Requirements "https://github.com/wzh9969/contrastive-htc/blob/main/requirement.txt"

    %% Classes and Styles
    classDef dataLayer fill:#ccf,stroke:#66f,stroke-width:2px;
    classDef trainingLayer fill:#cfc,stroke:#0a0,stroke-width:2px;
    classDef evaluationLayer fill:#fcf,stroke:#f0a,stroke-width:2px;
    classDef external fill:#ffe,stroke:#aa0,stroke-width:2px,stroke-dasharray: 5 5;
```
