How wangskygit/kehgn-r works
1. What this repo is
- KeGCN-R is a training/evaluation repository for graph-based prediction on company subgraphs.
- The core idea is to combine a GCN-style graph encoder with optional pre-trained knowledge embeddings (“KE”) for each entity/company.
2. Primary runtime and dependencies
- The code is a Python 3.9 / PyTorch 1.11 project.
- Data handling and evaluation rely on pandas, scipy, and sklearn.
- Knowledge embeddings are produced outside the repo with DGL-KE and then loaded in as an offline artifact.
3. Input data boundary
- The repository expects unpacked dataset folders in the working directory.
- Each dataset contains:
- .npy adjacency matrices for company subgraphs
- fv.csv with features and labels
- The year column in fv.csv is a special field used for constructing the “trust-worthy” test split, not as a model feature.
4. Offline embedding boundary
- A second external input is a pretraining result directory from DGL-KE.
- This acts as a separate knowledge source that can be fused into the model or disabled with -wke.
- Architecturally, this creates a two-stream setup: graph data from the dataset, and entity embeddings from the KE checkpoint.
5. Training entrypoint
- main.py is the orchestration layer.
- It likely parses CLI flags such as --model, --dataset, -d, -lr, --device, and -wke, then:
- loads data
- builds the chosen model
- runs training
- evaluates on the test split
- The README examples show that main.py is the only user-facing entrypoint for normal runs.
6. Model subsystem
- model.py is the main model registry/implementation file.
- It contains the KeGCN family:
- KeGCN
- KeGCNR (the “R” variant used in the paper/repo name)
- The model boundary is likely where graph features, structural messages, and optional KE vectors are combined before classification/regression.
7. Graph neural network layers
- layer.py holds reusable graph-layer building blocks.
- This is the architectural seam where low-level message passing, graph aggregation, or residual/attention-style operations are implemented.
- model.py likely assembles these layers into the full KeGCN/KeGCN-R architecture.
8. Loss and optimization
- loss.py isolates the training objective(s).
- This is where task-specific supervision is separated from the model definition, which makes it easier to swap objectives or compare variants.
- In diagrams, this is the “prediction head → loss” boundary after the model forward pass.
9. Baselines and experiments
- baseline.py suggests alternative non-KeGCN approaches for comparison.
- exp.py likely contains experiment runners, evaluation helpers, or ablation logic.
- These files define the experimental boundary around the core model so the repo can reproduce paper comparisons and ablations like “KeGCNR w/o ke”.
10. Evaluation / split logic
- tm.py and sieve.py appear to support dataset partitioning, trustworthiness filtering, or sample selection.
- Because the README explicitly mentions a year-based trustworthy test set, these modules are likely part of the data-splitting and test-set construction path.
- This is important architecturally because the evaluation split is not a trivial random split; it depends on dataset metadata.
11. Utilities
- util.py is the shared support layer for common tasks such as seeding, I/O, logging, metrics, or tensor/data conversion.
- In the architecture, this is the cross-cutting helper boundary used by training, evaluation, and preprocessing code.
12. End-to-end data flow
- Dataset files and KE embeddings are loaded from disk.
- main.py builds the selected model variant.
- The model consumes graph structure from .npy adjacency matrices plus tabular features from fv.csv.
- If enabled, KE vectors are merged into the representation.
- The output is passed to the task loss in loss.py, optimized with PyTorch, and evaluated on the designated split logic implemented by the supporting modules.
13. Key architectural toggle
- The -wke flag is the main switch that changes the model boundary:
- enabled: graph-only / no knowledge embedding branch
- disabled: graph + KE hybrid model
- For an architecture diagram, this is the clearest branch point in the system.
14. What to emphasize in a diagram
- Show three main layers:
1. offline artifacts: datasets and KE checkpoint
2. training orchestration: main.py plus split/eval utilities
3. model stack: model.py / layer.py / loss.py
- The most important integration point is the fusion of graph structure with pre-trained knowledge embeddings.
Main entry points: main.py main.py · model.py model.py · layer.py layer.py · loss.py loss.py
Components 16
Offline inputs
Dataset folders and pre-trained knowledge embeddings consumed from disk.
- Dataset files · Unpacked company-subgraph datasets with adjacency .npy files and fv.csv features/labels.
- KE checkpoint · External DGL-KE pretraining artifacts loaded as optional entity embeddings.
Training flow
Entry point, splitting, evaluation, and experiment plumbing.
- main.py · CLI orchestration for loading data, building the model, training, and evaluation.
main.py - util.py · Cross-cutting helpers for seeding, I/O, metrics, logging, and tensor/data handling.
util.py - tm.py · Support for trustworthy test split construction and related dataset partitioning.
tm.py - sieve.py · Sample filtering or selection support used by evaluation and split construction.
sieve.py - exp.py · Experiment runners, ablations, and evaluation helpers around the core training loop.
exp.py - baseline.py · Alternative comparison models and non-KeGCN reference methods.
baseline.py
Model stack
KeGCN variants, reusable layers, and training objective.
- model.py · Main KeGCN/KeGCNR implementation and architecture assembly.
model.py - layer.py · Reusable message-passing and aggregation building blocks for the encoder.
layer.py - loss.py · Task loss and optimization target used after the model forward pass.
loss.py - Graph encoder · Learns structural representations from company subgraph topology.
- KE fusion · Merges optional pre-trained knowledge embeddings with graph representations.
- Prediction head · Maps the fused representation to the task output before loss computation.
- KeGCN · Hybrid graph-plus-knowledge model variant.
- KeGCNR · Repository-named KeGCN-R variant used in the paper and main runs.
Connections 21
- Dataset files → main.py: load graph data · Main reads adjacency matrices and fv.csv features/labels.
- KE checkpoint → main.py: load KE · Main optionally loads pre-trained entity embeddings.
- main.py → tm.py: build split · Constructs the trustworthy test split and related partitions.
- main.py → sieve.py: filter samples · Applies dataset selection or filtering for evaluation setup.
- main.py → model.py: instantiate · Chooses the requested model variant and wires inputs.
- main.py → baseline.py: run baselines · Routes comparison runs to baseline implementations.
- main.py → exp.py: orchestrate exp · Invokes experiment and ablation workflows.
- main.py → util.py: shared helpers · Uses common utilities during training and evaluation.
- model.py → layer.py: compose layers · Builds the encoder from reusable graph-layer blocks.
- model.py → Graph encoder: encode graph · Turns company subgraph structure into learned embeddings.
- model.py → KE fusion: merge KE · Integrates optional knowledge embeddings when enabled.
- model.py → Prediction head: predict · Produces task outputs from fused representations.
- Graph encoder → layer.py: message passing · Uses the lower-level GCN/message-passing layers.
- KE fusion → KE checkpoint: consume embeddings · Reads the offline KE artifact as a secondary input stream.
- Prediction head → loss.py: compute loss · Feeds predictions into the task objective.
- model.py → KeGCN: implements · Contains the KeGCN family implementation.
- model.py → KeGCNR: implements · Contains the KeGCN-R variant used by the repo.
- KeGCN → KE fusion: with KE · Hybrid branch that includes knowledge embeddings.
- KeGCNR → KE fusion: with KE · Paper/repo variant that combines graph and knowledge streams.
- KeGCNR → Graph encoder: graph branch · Structural encoder path shared with the hybrid model.
- main.py → loss.py: optimize · Coordinates training with the shared loss module.