# hypernetwork-research-group/hypernegative architecture

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

- Interactive diagram: https://gitdiagram.com/hypernetwork-research-group/hypernegative
- Repository: https://github.com/hypernetwork-research-group/hypernegative

## Overview

##### Project type and purpose
- This is a Python library (“hypernegative”) for evaluating Hyperlink Prediction (HLP) algorithms with pluggable Negative Sampling (NS) methods.
- It exposes both a CLI (e.g. imdb_pipeline) and a Python API (DatasetLoader, HLP algorithms, NS algorithms).

##### Main components (to become “packages”
1. hyperlink_prediction
- datasets (ARB, IMDB, generic Hypergraph)
- loader (DatasetLoader)
- core classes: HyperlinkPredictionAlgorithm, HyperlinkPredictionBase, HyperlinkPredictionResult
2. negative_sampling
- HypergraphNegativeSamplingAlgorithm, result classes
3. pipelines
- CLI entrypoints (e.g. imdb_pipeline) that orchestrate dataset loading, negative sampling, HLP execution
4. utils
- data‐splitting, method‐selector helpers
5. External Dependencies
- PyTorch
- PyTorch Geometric

##### Relationships and data flow
- pipelines → invoke DatasetLoader (from hyperlink_prediction.loader)
- DatasetLoader → pulls raw data from hyperlink_prediction.datasets
- pipelines → use a NegativeSampler (from negative_sampling) to generate negative edges
- pipelines → feed positive + negative samples to a HyperlinkPredictionAlgorithm
- HyperlinkPredictionAlgorithm → emits HyperlinkPredictionResult
- utils support HLP and NS via helper functions

##### Architectural patterns and design principles
- Modular, layered pipeline: clear separation of data ingestion, negative sampling, prediction, and result reporting
- “Plug‐and‐play” strategy pattern: HLP methods and NS strategies implement common base interfaces
- CLI as a thin orchestration layer over core library

5. Hierarchically: pipelines → loader/datasets/ns → hlp core → results, with utils/helpers alongside.
6. External dependencies to the periphery.

This will yield a clean, accurate representation of Hypernegative’s architecture, highlighting modularity, extensibility points, and the core pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Pipelines Package
    subgraph "Pipelines"
        direction TB
        IMDB["imdb_pipeline.py"]:::module
    end

    %% Hyperlink Prediction Package
    subgraph "Hyperlink Prediction"
        direction TB
        subgraph Datasets
            direction TB
            ARB["arb_dataset.py"]:::module
            IMDB_DS["imdb_dataset.py"]:::module
            HYPER["dataset_hypergraph.py"]:::module
        end
        LOADER["dataloader.py"]:::module
        subgraph Core
            direction TB
            ALG["hyperlink_prediction_algorithm.py"]:::module
            BASE["hyperlink_prediction_base.py"]:::module
            RESULT_HP["hyperlink_prediction_result.py"]:::module
        end
    end

    %% Negative Sampling Package
    subgraph "Negative Sampling"
        direction TB
        NS_PROC["hypergraph_negative_sampling.py"]:::module
        NS_ALGO["hypergraph_negative_sampling_algorithm.py"]:::module
        NS_RES["hypergraph_negative_sampling_result.py"]:::module
    end

    %% Utils Package
    subgraph "Utils"
        direction TB
        SPLIT["hyperlink_train_test_split.py"]:::module
        SELECT["set_negative_samplig_method.py"]:::module
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        TORCH["PyTorch"]:::external
        PTG["PyTorch Geometric"]:::external
    end

    %% Data Flow and Dependencies
    IMDB -->|"loads data"| LOADER
    LOADER -->|"pulls raw data"| Datasets
    IMDB -->|"samples negatives"| NS_PROC
    IMDB -->|"runs HLP"| ALG
    ALG -->|"returns results"| RESULT_HP
    SPLIT -.-> IMDB
    SELECT -.-> NS_PROC
    TORCH -.-> ALG
    TORCH -.-> NS_ALGO
    PTG -.-> ALG
    PTG -.-> NS_ALGO

    %% Click Events
    click ARB "https://github.com/hypernetwork-research-group/hypernegative/blob/main/hyperlink_prediction/datasets/arb_dataset.py"
    click IMDB_DS "https://github.com/hypernetwork-research-group/hypernegative/blob/main/hyperlink_prediction/datasets/imdb_dataset.py"
    click HYPER "https://github.com/hypernetwork-research-group/hypernegative/blob/main/hyperlink_prediction/datasets/dataset_hypergraph.py"
    click LOADER "https://github.com/hypernetwork-research-group/hypernegative/blob/main/hyperlink_prediction/loader/dataloader.py"
    click ALG "https://github.com/hypernetwork-research-group/hypernegative/blob/main/hyperlink_prediction/hyperlink_prediction_algorithm.py"
    click BASE "https://github.com/hypernetwork-research-group/hypernegative/blob/main/hyperlink_prediction/hyperlink_prediction_base.py"
    click RESULT_HP "https://github.com/hypernetwork-research-group/hypernegative/blob/main/hyperlink_prediction/hyperlink_prediction_result.py"
    click NS_PROC "https://github.com/hypernetwork-research-group/hypernegative/blob/main/negative_sampling/hypergraph_negative_sampling.py"
    click NS_ALGO "https://github.com/hypernetwork-research-group/hypernegative/blob/main/negative_sampling/hypergraph_negative_sampling_algorithm.py"
    click NS_RES "https://github.com/hypernetwork-research-group/hypernegative/blob/main/negative_sampling/hypergraph_negative_sampling_result.py"
    click IMDB "https://github.com/hypernetwork-research-group/hypernegative/blob/main/pipelines/imdb_pipeline.py"
    click SPLIT "https://github.com/hypernetwork-research-group/hypernegative/blob/main/utils/hyperlink_train_test_split.py"
    click SELECT "https://github.com/hypernetwork-research-group/hypernegative/blob/main/utils/set_negative_samplig_method.py"

    %% Styles
    classDef module fill:#f0f0f0,stroke:#cccccc,color:#000000;
    classDef external fill:#f5f5dc,stroke:#cccccc,color:#000000;
    classDef pipelines fill:#ffdead,stroke:#333333,color:#000000;
    classDef hyperlink fill:#add8e6,stroke:#333333,color:#000000;
    classDef negative fill:#98fb98,stroke:#333333,color:#000000;
    classDef utils fill:#dda0dd,stroke:#333333,color:#000000;
    
    %% Assign package-level coloring to modules
    class IMDB pipelines;
    class ARB,IMDB_DS,HYPER,LOADER,ALG,BASE,RESULT_HP hyperlink;
    class NS_PROC,NS_ALGO,NS_RES negative;
    class SPLIT,SELECT utils;
    class TORCH,PTG external;
```
