GraphSage Documentation

Install the required dependencies including TensorFlow, numpy, scipy, sklearn, and networkx (note: networkx must be <= 1.11) using the provided requirements file.

$ pip install -r requirements.txt

You can run GraphSage in a pre-configured virtual environment using Docker.

Standard CPU Image: Build and run a bash session:

$ docker build -t graphsage .
$ docker run -it graphsage bash

To start a Jupyter Notebook instead of bash:

$ docker run -it -p 8888:8888 graphsage

GPU Image (requires nvidia-docker): Build and run using the GPU-specific Dockerfile:

$ docker build -t graphsage:gpu -f Dockerfile.gpu .
$ nvidia-docker run -it graphsage:gpu bash

When running GraphSage, use the following flags to tune performance and behavior:

• --identity_dim: Set this to a value in the range [64, 256] if your task does not require generalizing to unseen data. This embeds unique node IDs as attributes, which can increase performance on static graphs. Do not use dense one-hot vectors as features instead; use this flag to handle sparsity.
• --sigmoid: Required for multi-output datasets (like PPI) where individual nodes can belong to multiple classes. By default, the model assumes a one-hot categorical setting.
• --model: Specifies the aggregator variant (see Model Variants).
• --train_prefix: Specifies the prefix for required data files.
• --base_log_dir: Specifies the directory where logs and outputs are stored (defaults to the current directory).

To run the model, you must provide a --train_prefix that points to the following files:

• <train_prefix>-G.json: A NetworkX-specified JSON file describing the graph. Nodes must have val and test attributes.
• <train_prefix>-id_map.json: A JSON dictionary mapping graph node IDs to consecutive integers.
• <train_prefix>-class_map.json: A JSON dictionary mapping graph node IDs to classes.
• <train_prefix>-feats.npy (Optional): A NumPy-stored array of node features, ordered by id_map.json.
• <train_prefix>-walks.txt (Optional): A text file of random walk co-occurrences (one pair per line). Required only for the unsupervised version.

To generate the <prefix>-walks.txt file for unsupervised training, use the run_walks function in graphsage.utils.

Specify the aggregator type using the --model flag. Available variants include:

• graphsage_mean: Mean-based aggregator.
• graphsage_seq: LSTM-based aggregator.
• graphsage_maxpool: Max-pooling aggregator.
• graphsage_meanpool: Mean-pooling aggregator (element-wise mean instead of max).
• gcn: GCN-based aggregator.
• n2v: DeepWalk implementation.

Outputs are stored in a subdirectory of --base_log_dir following the pattern: <sup/unsup>-<data_prefix>/graphsage-<model_description>/.

• Supervised Training: Outputs F1 scores.
• Unsupervised Training: Trains embeddings and stores them in a NumPy file named val.npy. The corresponding node order is specified in val.txt (a per-line list of node IDs).

Note: Unsupervised log outputs and embeddings can be large (5-10GB for full datasets).