Package: residual2vec
Python package for residual2vec graph embedding algorithmresidual2vec is an algorithm to embed networks to a vector space while controlling for various structural properties such as degree. If you use this package, please cite:S. Kojaku, J. Yoon, I. Constantino, and Y.-Y. Ahn, Residual2Vec: Debiasing graph embedding using random graphs. NerurIPS (2021). [link will be added when available]Preprint (arXiv)BibTex entry:@inproceedings{kojaku2021neurips,
 title={Residual2Vec: Debiasing graph embedding using random graphs},
 author={Sadamori Kojaku and Jisung Yoon and Isabel Constantino and Yong-Yeol Ahn},
 booktitle ={Advances in Neural Information Processing Systems},
 editor ={},
 pages ={},
 publisher ={Curran Associates, Inc.},
 volume ={},
 year ={2021}}Installpipinstallresidual2vecRequirementsThis code is tested in Python 3.7 and 3.8, and has dependencies with
the following packages:- numpy==1.19.0
- scipy==1.7.1
- scikit-learn==1.0
- faiss-cpu==1.7.0
- numba==0.50.0
- torch==1.10.0
- tqdm==4.48.2Exampleresidual2vec has two versions, one optimized with a matrix factorization, and the other optimized with a stochatic gradient descent aglorithm.The residual2vec with a matrix factorization is used in the original paper and runs faster than the other version for networks of upto 100k nodes.importresidual2vecasrvmodel=rv.residual2vec_matrix_factorization(window_length=10,group_membership=None)model.fit(G)emb=model.transform(dim=64)# or equivalently emb = model.fit(G).transform(dim = 64)G: adjacency matrix of the input graph.numpy.arrayorscipy.sparse.csr_matrixcan be accepted.window_length: the length of context window.group_membership: an array of node labels. Used to debias the structural bias correlated with the node labels.dim: Dimension of the embeddingemb: 2D numpy array of shape (N,dim), whereNis the number of nodes. Theith row in the array (i.e.,emb[i, :]) represents the embedding vector of theith node in the given adjacency matrixG.A limitation of the matrix-factorization-based implementation is that it is memory demanding, especially for dense or large networks.
The other version is implemented to circumvent this problem by using the stochastic gradient descent (SGD) algorithm, that
incrementally updates the embedding with a small chunk of data instead of deriving the whole embedding in one go.importresidual2vecasrvnoise_sampler=rv.ConfigModelNodeSampler()# sampler for the negative samplingmodel=rv.residual2vec_sgd(noise_sampler,window_length=10)model.fit(G)emb=model.transform(dim=64)# or equivalently emb = model.fit(G).transform(dim = 64)Theresidual2vec_sgdhas an additional argumentnoise_sampler, which is a class that samples context nodes for a given center node.
Several samplers are implemented in this package:ErdosRenyiNodeSampler: Sampler based on the Erdos Renyi random graph (i.e., sample context node with the same probability)ConfigModelNodeSampler: Sampler based on the configuration model (i.e., sample context node with probability proportional to its degree)SBMNodeSampler: Sampler based on the stochastic block model (i.e., sample context node using the stochastic block model)ConditionalContextSampler: Sampling a random context node conditioned on the group to which a given context node blongs. The group membership needs to be given when creating this instance (experimental).TheSBMNodeSampleris useful to negate the bias due to a group structure in networks (i.e., structure correlated with a discrete label of nodes):importresidual2vecasrvgroup_membership=[0,0,0,0,1,1,1,1]noise_sampler=rv.SBMNodeSampler(window_length=10,group_membership=group_membership)# sampler for the negative samplingmodel=rv.residual2vec_sgd(noise_sampler,window_length=10)model.fit(G)emb=model.transform(dim=64)# or equivalently emb = model.fit(G).transform(dim = 64)An added bonus for the SGD-based approach is that it offers a way to customize the noise distribution, which is useful to debias a particular bias in embedding.
Implement the following class inherited fromrv.NodeSampler:importresidual2vecasrvclassCustomNodeSampler(rv.NodeSampler):deffit(self,A):#Fit the sampler#:param A: adjacency matrix#:type A: scipy.csr_matrixpassdefsampling(self,center_node,n_samples):#Sample context nodes from the graph for center nodes#:param center_node: ID of center node#:type center_node: int#:param n_samples: number of samples per center node#:type n_samples: intpassSee theresidual2vec/node_samplersfor examples.