# edogawa-liang/113-2_research architecture

> Architecture diagram of the GitHub repository edogawa-liang/113-2_research, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/edogawa-liang/113-2_research
- Repository: https://github.com/edogawa-liang/113-2_research

## Overview

##### Project Type and Purpose
- This is a research‐oriented pipeline for graph‐based machine learning.
- Purpose:
- Stage 1: train baseline GNN/MLP on graph datasets (Cora, Citeseer, Amazon).
- Tools & analysis for distance metrics, coverage, plotting, and result summarization.

##### Top‐Level Components
a. Data Ingestion & Preprocessing
- Modules: data/dataset_loader.py, data/data_modifier.py, data/prepare_split.py, data/split_unknown_to_test.py, data/feature2node.py, data/node2feature.py
- Purpose: load raw graph, split into train/val/test, optionally convert each feature into a new node (feature‐to‐node).

b. Stage 1 – Baseline Model Training
- Entry point: training_main.py
- Modules: trainer/gnn_trainer.py (for GCN), trainer/mlp_trainer.py (for MLP)
- Models: models/basic_GCN.py, models/basic_mlp.py

- Entry point: stage2_expsubg.py
- Subcomponents (in subgraph_selector/):
- random_selector.py
- random_walk_selector.py
- explainer_selector.py (wraps GNNExplainer, CFExplainer)
- cf_remaining_graph.py, remaining_graph.py
- CFExplainer code under models/cf_explanation/

- Tools: tools/stage2_node_share.py, tools/check_cf_summary2.py
- Purpose: summarize which nodes are shared across explanations, verify explainer success.

e. Stage 3 – Training on Remaining Graph
- Entry point: train_remaining_main.py (and test_remaining_main.py)

f. Analysis & Visualization
- Modules in analysis/: scripts to compute distances (distance_from_test_to_selected.py, etc.), degree change tests, coverage tests.
- Tools in tools/: plot_stage2.py, result_summary.py, cal_node_imp.py.
- Final results saved as Excel in “Final Result/0601”, “Final Result/0614”.

g. Command Scripts
- command/*.sh and command*.txt orchestrate multi‐dataset runs, parameter sweeps, feature-to-node experiments.

##### Relationships & Data Flow
- Raw Dataset → Data Ingestion → Split into train/val/test →
→ Stage 1 Trainer → Trained Baseline Model →
→ Stage 2.5 Storage & Summaries →
→ Performance Metrics → Analysis & Visualization → Excel/Plots in Final Result.

##### Architectural Patterns & Principles
- Pipeline stages (linear, modular)
- Separation of concerns: data vs. model vs. explanation vs. analysis
- Reusability: the same trainer and model code is reused in Stage 1 and Stage 3

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing
    subgraph "Data Ingestion & Preprocessing"
        direction TB
        DL["Dataset Loader"]:::data
        DM["Data Modifier"]:::data
        PS["Prepare Split"]:::data
        SU["Split Unknown to Test"]:::data
        F2N["Feature-to-Node Converter"]:::data
        N2F["Node-to-Feature Converter"]:::data
    end

    %% Stage 1 – Baseline Model Training
    subgraph "Stage 1: Baseline Training"
        direction TB
        TM["training_main.py"]:::train
        GCN["GCN Trainer"]:::train
        MLP["MLP Trainer"]:::train
        BG["Basic GCN Model"]:::train
        BM["Basic MLP Model"]:::train
    end

    %% Stage 2 – Explanation Subgraph Generation
    subgraph "Stage 2: Explanation Generation"
        direction TB
        S2["stage2_expsubg.py"]:::explain
        RS["Random Selector"]:::explain
        RW["RandomWalk Selector"]:::explain
        ES["Explainer Selector"]:::explain
        CRG["CF Remaining Graph"]:::explain
        RG["Remaining Graph"]:::explain
        BP["Basic GCN Perturb"]:::explain
        CE["CF Explainer"]:::explain
        EX["Explainer Core"]:::explain
    end

    %% Stage 2.5 – Subgraph Storage & Summarization
    subgraph "Stage 2.5: Storage & Summaries"
        direction TB
        NS["stage2_node_share.py"]:::storage
        CS["check_cf_summary2.py"]:::storage
        CI["cal_node_imp.py"]:::storage
        RSU["result_summary.py"]:::storage
    end

    %% Stage 3 – Training on Remaining Graph
    subgraph "Stage 3: Remaining Graph Training"
        direction TB
        TRM["train_remaining_main.py"]:::train
        TSTM["test_remaining_main.py"]:::train
        GCN2["GCN Trainer"]:::train
        MLP2["MLP Trainer"]:::train
        BG2["Basic GCN Model"]:::train
        BM2["Basic MLP Model"]:::train
    end

    %% Analysis & Visualization
    subgraph "Analysis & Visualization"
        direction TB
        A1["distance_from_test_to_selected.py"]:::analysis
        A2["dist_change_vs_unchange.py"]:::analysis
        A3["degree_test2hop_change_vs_unchange.py"]:::analysis
        A4["num_test2hop_change_vs_unchange.py"]:::analysis
        A5["check_pred_result.py"]:::analysis
        A6["plot_stage2.py"]:::analysis
        A7["test_degree_change_vs_unchange.py"]:::analysis
        AP["plot_stage2.py (tools)"]:::analysis
    end

    %% Command Orchestrator
    subgraph "Command Orchestrator"
        direction TB
        C1["analysis.sh"]:::orchestrator
        C2["command.txt"]:::orchestrator
        C3["command2.txt"]:::orchestrator
        C4["command3.txt"]:::orchestrator
        C5["command4.txt"]:::orchestrator
        C6["command5.sh"]:::orchestrator
        C7["command6.sh"]:::orchestrator
        C8["command6-2.sh"]:::orchestrator
        C9["command6_Amazon_feature2node.sh"]:::orchestrator
        C10["command6_cf.sh"]:::orchestrator
    end

    %% Final Results Storage
    FR["Final Results (.xlsx)"]:::storage

    %% Connections
    DL --> DM --> PS --> SU --> F2N --> N2F --> TM
    TM --> GCN --> BG
    TM --> MLP --> BM
    BG --> S2
    BM --> S2
    S2 --> RS
    S2 --> RW
    S2 --> ES
    S2 --> CRG
    S2 --> RG
    ES --> BP --> CE --> EX
    EX --> NS --> CS --> CI --> RSU
    RSU --> TRM
    TRM --> GCN2 --> BG2
    TRM --> MLP2 --> BM2
    BG2 --> A1
    BM2 --> A1
    A1 --> A2 --> A3 --> A4 --> A5 --> A6 --> A7 --> AP
    AP --> FR
    C1 --> DL
    C1 --> TM
    C1 --> S2
    C1 --> TRM
    C1 --> A1
    C1 --> AP

    %% Click Events
    click DL "https://github.com/edogawa-liang/113-2_research/blob/main/data/dataset_loader.py"
    click DM "https://github.com/edogawa-liang/113-2_research/blob/main/data/data_modifier.py"
    click PS "https://github.com/edogawa-liang/113-2_research/blob/main/data/prepare_split.py"
    click SU "https://github.com/edogawa-liang/113-2_research/blob/main/data/split_unknown_to_test.py"
    click F2N "https://github.com/edogawa-liang/113-2_research/blob/main/data/feature2node.py"
    click N2F "https://github.com/edogawa-liang/113-2_research/blob/main/data/node2feature.py"
    click TM "https://github.com/edogawa-liang/113-2_research/blob/main/training_main.py"
    click GCN "https://github.com/edogawa-liang/113-2_research/blob/main/trainer/gnn_trainer.py"
    click MLP "https://github.com/edogawa-liang/113-2_research/blob/main/trainer/mlp_trainer.py"
    click BG "https://github.com/edogawa-liang/113-2_research/blob/main/models/basic_GCN.py"
    click BM "https://github.com/edogawa-liang/113-2_research/blob/main/models/basic_mlp.py"
    click S2 "https://github.com/edogawa-liang/113-2_research/blob/main/stage2_expsubg.py"
    click RS "https://github.com/edogawa-liang/113-2_research/blob/main/subgraph_selector/random_selector.py"
    click RW "https://github.com/edogawa-liang/113-2_research/blob/main/subgraph_selector/random_walk_selector.py"
    click ES "https://github.com/edogawa-liang/113-2_research/blob/main/subgraph_selector/explainer_selector.py"
    click CRG "https://github.com/edogawa-liang/113-2_research/blob/main/subgraph_selector/cf_remaining_graph.py"
    click RG "https://github.com/edogawa-liang/113-2_research/blob/main/subgraph_selector/remaining_graph.py"
    click BP "https://github.com/edogawa-liang/113-2_research/blob/main/models/cf_explanation/basic_GCN_perturb.py"
    click CE "https://github.com/edogawa-liang/113-2_research/blob/main/models/cf_explanation/cf_explainer.py"
    click EX "https://github.com/edogawa-liang/113-2_research/blob/main/models/explainer.py"
    click NS "https://github.com/edogawa-liang/113-2_research/blob/main/tools/stage2_node_share.py"
    click CS "https://github.com/edogawa-liang/113-2_research/blob/main/tools/check_cf_summary2.py"
    click CI "https://github.com/edogawa-liang/113-2_research/blob/main/tools/cal_node_imp.py"
    click RSU "https://github.com/edogawa-liang/113-2_research/blob/main/tools/result_summary.py"
    click TRM "https://github.com/edogawa-liang/113-2_research/blob/main/train_remaining_main.py"
    click TSTM "https://github.com/edogawa-liang/113-2_research/blob/main/test_remaining_main.py"

    %% Styles
    classDef data fill:#cce5ff,stroke:#3399ff;
    classDef train fill:#ccffcc,stroke:#33cc33;
    classDef explain fill:#ffe6cc,stroke:#ff9933;
    classDef storage fill:#f2f2f2,stroke:#999999;
    classDef analysis fill:#e5ccff,stroke:#9933ff;
    classDef orchestrator fill:#e6e6e6,stroke:#666666;
```
