Neural Overlapping Community Detection (NOCD)

A state-of-the-art Graph Convolutional Network for discovering overlapping communities.

---

🔍 Overview

The Neural Overlapping Community Detection (NOCD) algorithm identifies overlapping communities in graph-structured data by learning node embeddings via a Graph Convolutional Network (GCN) and reconstructing the adjacency matrix with a Bernoulli decoder.

---

⚙️ Class Definition

class soft_clustering.NOCD(
    random_state: int = None,
    hidden_sizes: List[int] = [128],
    weight_decay: float = 1e-2,
    dropout: float = 0.5,
    batch_norm: bool = True,
    lr: float = 1e-3,
    max_epochs: int = 500,
    balance_loss: bool = True,
    stochastic_loss: bool = True,
    batch_size: int = 20000
)

🔗 Source on GitHub

---

📋 Parameters

Parameter	Type	Default	Description
random_state	int	None	Seed for reproducible experiments.
hidden_sizes	List[int]	[128]	Sizes of hidden GCN layers for embedding complexity.
weight_decay	float	1e-2	L2 regularization strength to prevent overfitting.
dropout	float	0.5	Dropout rate in GCN layers for robustness.
batch_norm	bool	True	Enable batch normalization for stable learning.
lr	float	1e-3	Learning rate for the Adam optimizer.
max_epochs	int	500	Maximum training epochs (early stopping by default).
balance_loss	bool	True	Balance contributions of edges and non-edges in the loss.
stochastic_loss	bool	True	Use mini-batch (stochastic) or full-batch training.
batch_size	int	20000	Sample size per batch in stochastic training.

---

🚀 Usage Examples

from soft_clustering import NOCD
import numpy as np
from scipy.sparse import csr_matrix

# Create sample graph    
n = 10
p = 0.2 
upper = np.triu((np.random.rand(n, n) < p).astype(int), k=1)
A = upper + upper.T        
adjacency_matrix = csr_matrix(A)

feat = np.random.rand(n, n) * 0.1             
feat[:5, :5] += 1.0                            
feat[5:, 5:] += 1.0                            
feature_matrix = csr_matrix(feat)

K = 2  # number of communities

# Initialize and fit the model
model = NOCD(random_state=42, max_epochs=10)

memberships = model.fit_predict(adjacency_matrix, feature_matrix, K)
print("Membership matrix:\n", memberships)

---

🛠️ Methods

fit_predict(adjacency_matrix, feature_matrix, K)

Train the NOCD model on provided graph data and return the predicted membership matrix.

Parameters:

• adjacency_matrix (scipy.sparse, shape (n_nodes, n_nodes)): Sparse graph adjacency.

• feature_matrix (scipy.sparse, shape (n_nodes, n_features)): Node attribute matrix.

• K (int): Number of communities.

Returns:

• memberships (np.ndarray, shape (n_nodes, K)): Community membership degrees.

🔗 Source definition

---

📝 Implementation Notes

• Undirected Graphs: Assumes symmetry in adjacency during normalization.

• Windows Caveat: Wrap NOCD.fit_predict() calls in if __name__ == "__main__" to avoid multi-processing issues.

---

📚 Reference

1. Shchur, O., & Günnemann, S. (2019). Overlapping Community Detection with Graph Neural Networks. arXiv preprint 1909.12201.