{"id":22229802,"url":"https://github.com/graph-com/neighborhood-aware-temporal-network","last_synced_at":"2025-07-02T15:36:55.312Z","repository":{"id":59035082,"uuid":"531761560","full_name":"Graph-COM/Neighborhood-Aware-Temporal-Network","owner":"Graph-COM","description":"Yuhong Luo and Pan Li. Neighborhood-aware scalable temporal network representation learning. In Learning on Graphs, 2022.","archived":false,"fork":false,"pushed_at":"2023-05-06T03:50:30.000Z","size":520,"stargazers_count":28,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T06:51:15.339Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Graph-COM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-02T02:58:15.000Z","updated_at":"2025-01-27T15:11:24.000Z","dependencies_parsed_at":"2024-12-03T01:12:33.887Z","dependency_job_id":"eed16254-4f7a-45d0-b9a3-56ae38b11532","html_url":"https://github.com/Graph-COM/Neighborhood-Aware-Temporal-Network","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Graph-COM/Neighborhood-Aware-Temporal-Network","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Graph-COM%2FNeighborhood-Aware-Temporal-Network","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Graph-COM%2FNeighborhood-Aware-Temporal-Network/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Graph-COM%2FNeighborhood-Aware-Temporal-Network/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Graph-COM%2FNeighborhood-Aware-Temporal-Network/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Graph-COM","download_url":"https://codeload.github.com/Graph-COM/Neighborhood-Aware-Temporal-Network/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Graph-COM%2FNeighborhood-Aware-Temporal-Network/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263166930,"owners_count":23424279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-03T01:12:28.006Z","updated_at":"2025-07-02T15:36:55.259Z","avatar_url":"https://github.com/Graph-COM.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eNeighborhood-Aware-Temporal-Network (NAT)\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://arxiv.org/abs/2209.01084\"\u003e\u003cimg src=\"https://img.shields.io/badge/-Paper-grey?logo=gitbook\u0026logoColor=white\" alt=\"Paper\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/Graph-COM/Neighborhood-Aware-Temporal-Network\"\u003e\u003cimg src=\"https://img.shields.io/badge/-Github-grey?logo=github\" alt=\"Github\"\u003e\u003c/a\u003e\n    \u003c!---\u003ca href=\"https://proceedings.mlr.press/v162/miao22a.html\"\u003e \u003cimg alt=\"License\" src=\"https://img.shields.io/static/v1?label=Pub\u0026message=ICML%2722\u0026color=blue\"\u003e \u003c/a\u003e---!\u003e\n\u003c/p\u003e\n\nThis repository contains the official implementation of NAT as described in the paper: [Neighborhood-aware Scalable Temporal Network\nRepresentation Learning](https://arxiv.org/abs/2209.01084)(LoG 2022) by Yuhong Luo, and Pan Li.\n\n## Introduction\nIn a temporal network, the joint neighborhood of a set of nodes often provides crucial structural information on predicting whether they may interact at a certain time. However, all previous works either fail to capture such information or depend on extremely time-consuming feature construction approaches.  Most temporal networks learn a vector representation for each node, and predict whether two node may interact (aka. a link) based on a combination (e.g. the inner product) of the two vector representations. However, they fail the simple example in Fig. 1 Left because they learn the same representation for nodes in different parts of the graph. Some recent works provide theoretically powerful solutions by constructing joint neighborhood structural features. However, their methods are computationally expensive and do not scale to large temporal networks.\n\nTo address these issues, this work proposes Neighborhood-Aware Temporal network model (NAT). For each node in the network, NAT abandons the commonly-used one-single-vector-based representation while adopting a novel dictionary-type neighborhood representation. Such a dictionary representation records a down-sampled set of the neighboring nodes as keys, and allows fast construction of structural features for a joint neighborhood of multiple nodes. We also design dedicated data structure termed N-cache to support parallel access and update of those dictionary representations on GPUs. A high-level abstraction is provided in Fig. 1 Right and a more detail learning procudure is provided in Fig. 2.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"./figures/introduction.png\" width=85% height=85%\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003eFigure 1.\u003c/em\u003e The introduction of NAT. Left: the task is to predict that $u$ prefers to interact with $v$ more than \u003cem\u003ew\u003c/em\u003e at timestamp $t_3$ following the principle of triadic closure in social network. Middle: Traditional methods fail this task because they learn the same representations for node $v$ and node $w$. Right: construct joint neighborhood features based on N-caches. Node $a$ appears as a key in the first hop N-caches of both $u$ and $v$. Joining these keys can provide structural features that encodes common-neighbor information for prediction. \u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"./figures/Algorithm_fig_2.png\" width=85% height=85%\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003eFigure 2.\u003c/em\u003e The architecture of NAT. Left: Neighborhood representations of a node and the update procedures of these representations within the N-caches. Right: The construction of joint structural features using the neighborhood representations. \u003c/p\u003e\n\n## Requirements\n* `python \u003e= 3.7`, `PyTorch \u003e= 1.4`, please refer to their official websites for installation details.\n* Other dependencies:\n```{bash}\npandas==1.4.3\ntqdm==4.41.1\nnumpy==1.23.1\nscikit_learn==1.1.2\n```\nRefer to `environment.yml` for more details.\n\nWe have tested our code on `Python 3.9` with `PyTorch 1.9.0`, and `CUDA 10.1`. Please follow the following steps to create a virtual environment and install the required packages.\n\nClone the repository:\n```\ngit clone https://github.com/Graph-COM/Neighborhood-Aware-Temporal-Network\ncd Neighborhood-Aware-Temporal-Network\n```\n\nCreate a virtual environment:\n```\nconda create --name nat python=3.9 -y\nconda activate nat\n```\n\nInstall dependencies:\n```\nconda install -y pytorch==1.9.0 torchvision==0.10.0 torchaudio==0.9.0 cudatoolkit=10.2 -c pytorch\npip install -U scikit-learn\nconda install tqdm==4.41.1\n```\n\n\n## Training Commands\n\n#### Examples:\n\n* To train **NAT** with Wikipedia dataset in transductive training, using 32 1-hop N-cache, 16 2-hop N-cache, neighborhood representation of 4 dimensions , and with overriding probability alpha = 0.7:\n```bash\npython main.py -d wikipedia --pos_dim 16 --bs 100 --n_degree 32 16 --n_hop 2 --mode t --bias 1e-5 --seed 2 --verbosity 1 --drop_out 0.1 --attn_n_head 2 --ngh_dim 4 --self_dim 72 --replace_prob 0.7 --run 5\n```\nTo train in inductive training, change `mode` from `t` to `i`. Here is an example of inductive training on Wiki-talk, using 16 1-hop neighbors with neighborhood representation size 4 and 72 dimensions of self representations.\n```bash\npython main.py -d wiki-talk-temporal --pos_dim 16 --bs 100 --n_degree 16 --n_hop 1 --mode i --bias 1e-5 --seed 2 --verbosity 1 --drop_out 0.1 --attn_n_head 1 --ngh_dim 4 --self_dim 72 --run 5\n```\n\n## Usage Summary\n```\nusage: Interface for Neighbourhood-aware Scalable Learning for Temporal Networks\n       [-h]\n       [-d {wikipedia,reddit,socialevolve,uci,enron,socialevolve_1month,socialevolve_2weeks,sx-askubuntu,sx-superuser,wiki-talk-temporal,mooc}]\n       [-m {t,i}] [--n_degree [N_DEGREE [N_DEGREE ...]]] [--n_hop N_HOP]\n       [--bias BIAS] [--pos_dim POS_DIM] [--self_dim SELF_DIM]\n       [--ngh_dim NGH_DIM] [--linear_out] [--attn_n_head ATTN_N_HEAD]\n       [--time_dim TIME_DIM] [--n_epoch N_EPOCH] [--bs BS] [--lr LR]\n       [--drop_out DROP_OUT] [--replace_prob REPLACE_PROB]\n       [--tolerance TOLERANCE] [--seed SEED] [--verbosity VERBOSITY]\n       [--run RUN]\n```\n\n### optional arguments:\n```\n  -h, --help            show this help message and exit\n  -d {wikipedia,reddit,socialevolve,uci,enron,socialevolve_1month,socialevolve_2weeks,sx-askubuntu,sx-superuser,wiki-talk-temporal,mooc}, --data {wikipedia,reddit,socialevolve,uci,enron,socialevolve_1month,socialevolve_2weeks,sx-askubuntu,sx-superuser,wiki-talk-temporal,mooc}\n                        data sources to use, try wikipedia or reddit\n  -m {t,i}, --mode {t,i}\n                        transductive (t) or inductive (i)\n  --n_degree [N_DEGREE [N_DEGREE ...]]\n                        a list of neighbor sampling numbers for different\n                        hops, when only a single element is input n_layer will\n                        be activated\n  --n_hop N_HOP         number of hops the N-cache is used\n  --bias BIAS           the hyperparameter alpha controlling sampling\n                        preference with time closeness, default to 0 which is\n                        uniform sampling\n  --pos_dim POS_DIM     dimension of the positional embedding\n  --self_dim SELF_DIM   dimension of the self representation\n  --ngh_dim NGH_DIM     dimension of the neighborhood representation\n  --linear_out          whether to linearly project each node's\n  --attn_n_head ATTN_N_HEAD\n                        number of heads used in tree-shaped attention layer,\n                        we only use the default here\n  --time_dim TIME_DIM   dimension of the time embedding\n  --n_epoch N_EPOCH     number of epochs\n  --bs BS               batch_size\n  --lr LR               learning rate\n  --drop_out DROP_OUT   dropout probability for all dropout layers\n  --replace_prob REPLACE_PROB\n                        probability for storing new neighbors to N-cache\n                        replacing old ones\n  --tolerance TOLERANCE\n                        toleratd margainal improvement for early stopper\n  --seed SEED           random seed for all randomized algorithms\n  --verbosity VERBOSITY\n                        verbosity of the program output\n  --run RUN             number of model runs\n```\n\n## Instructions on Acquiring Datasets\nPreprocessed datasets: Reddit, Wikipedia, SocialEvolve, Enron, and UCI can be downloaded from [here](https://drive.google.com/drive/folders/1umS1m1YbOM10QOyVbGwtXrsiK3uTD7xQ?usp=sharing) to `processed/`. Then run the following:\n```{bash}\ncd processed/\nunzip data.zip\n```\nYou may check that each dataset corresponds to three files: one `.csv` containing timestamped links, and two ``.npy`` as node \u0026 link features. Note that some datasets do not have node \u0026 link features, in which case the `.npy` files will be all zeros.\n\nRaw data for Ubuntu can be downloaded using this [link](https://snap.stanford.edu/data/sx-askubuntu.txt.gz) and Wiki-talk using this [link](https://snap.stanford.edu/data/wiki-talk-temporal.txt.gz) to `processed`. Run the following to preprocess the data.\n```{bash}\npython process.py --dataset sx-askubuntu\npython process.py --dataset wiki-talk-temporal\n```\n\n#### Use your own data\nPut your data under `processed` folder. The required input data includes `ml_${DATA_NAME}.csv`, `ml_${DATA_NAME}.npy` and `ml_${DATA_NAME}_node.npy`. They store the edge linkages, edge features and node features respectively.\n\nThe `.csv` file has following columns\n```\nu, i, ts, label, idx\n```\n, which represents source node index, target node index, time stamp, edge label and the edge index.\n\n`ml_${DATA_NAME}.npy` has shape of [#temporal edges + 1, edge features dimention]. Similarly, `ml_${DATA_NAME}_node.npy` has shape of [#nodes + 1, node features dimension].\n\n\nAll node index starts from `1`. The zero index is reserved for `null` during padding operations. So the maximum of node index equals to the total number of nodes. Similarly, maxinum of edge index equals to the total number of temporal edges. The padding embeddings or the null embeddings is a vector of zeros.\n\n## Acknowledgement\nOur implementation adapts the code [here](https://github.com/snap-stanford/CAW) as the code base and extensively adapts it to our purpose. We also adapts an efficient implementation of GAT [here](https://github.com/gordicaleksa/pytorch-GAT)  for the output attention layer. We thank the authors for sharing their code.\n## Reference\n\nIf you find our paper and repo useful, please cite our paper:\n```bibtex\n@article{luo2022neighborhood,\n  title       = {Neighborhood-aware Scalable Temporal Network Representation Learning},\n  author      = {Luo, Yuhong and Li, Pan},\n  journal     = {Learning on Graphs Conference},\n  year        = {2022}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraph-com%2Fneighborhood-aware-temporal-network","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraph-com%2Fneighborhood-aware-temporal-network","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraph-com%2Fneighborhood-aware-temporal-network/lists"}