graspologic Documentation

graspologic is a Python package designed for the analysis of graphs and networks. It provides specialized graph statistical algorithms and utilities that account for the spatial arrangement of nodes within a network, moving beyond traditional statistical techniques that neglect network structure.

Key features include:

• Utilities and algorithms for graph processing.
• Specialized graph statistical algorithms.
• Integration with the Python ecosystem for numerical linear algebra and plotting.

The graspologic.simulations module provides functions to generate synthetic graphs based on various statistical models. These models can be used to create datasets for testing graph algorithms or for statistical inference tasks.

Available simulation models include:

• Erdős-Rényi (ER) models: er_np (fixed number of edges) and er_nm (fixed edge probability).
• Stochastic Block Models (SBM): sbm (standard SBM) and mmsbm (Multi-level Mixed Stochastic Block Model).
• Random Degree Profile Graphs (RDPG): rdpg (standard RDPG).
• Correlated models: er_corr, sbm_corr, and rdpg_corr for generating graphs with specific correlation structures.

The graspologic.inference module provides functions for conducting hypothesis tests between two graphs. These tests are used to determine if two observed graphs are realizations of the same underlying statistical model or if they differ significantly in specific structural properties.

Available tests include:

• density_test: Tests for differences in edge density.
• group_connection_test: Tests for differences in how groups of nodes connect.
• latent_position_test: Tests for differences in the latent positions of nodes.
• latent_distribution_test: Tests for differences in the distribution of latent variables.

You can install the current release of graspologic using pip. It is recommended to use a Python virtual environment to manage your dependencies. Ensure you have the latest version of pip installed before proceeding.

# Install the current release
$ pip install graspologic

# Upgrade to a newer release
$ pip install --upgrade graspologic

# Install into your user directory if you lack system-wide permissions
$ pip install --user graspologic

If you prefer to install manually, you can download the package from PyPI. Navigate to your download folder in the terminal and run pip install on the downloaded .tar.gz file.

$ pip install graspologic-VERSION.tar.gz

To install the latest development version from the GitHub repository, clone the repo, create a virtual environment, and install the local package using pip.

git clone https://github.com/graspologic-org/graspologic
cd graspologic
python3 -m venv venv
source venv/bin/activate
pip install .

To install the graspologic package directly from PyPI, use the standard pip installation command.

pip install graspologic

A Stochastic Block Model (SBM) is a statistical model used to represent networks where the probability of an edge occurring between two nodes is a function of the groups (or communities) those nodes belong to.

An SBM is defined by:

1. Node-to-group assignments ($\tau$): A vector indicating which group each node belongs to.
2. Group-to-group connection probabilities ($B$): A matrix where $B_{kl}$ represents the probability of an edge existing between a node in group $k$ and a node in group $l$.

In graspologic, the sbm function in graspologic.simulations can be used to generate networks following this model.

Signal-subgraph estimators identify a subset of edges that distinguish between different graph classes. The distinction between 'Incoherent' and 'Coherent' depends on the structural constraints applied to the resulting subgraph:

1. Incoherent Signal-Subgraph: The estimator selects $s$ edges based on their significance, but these edges are not required to follow any specific structural pattern or vertex connectivity. Any edge in the graph can be part of the signal.

2. Coherent Signal-Subgraph: The estimator selects $s$ edges with the additional constraint that they must be incident to exactly $m$ vertices. This forces the identified signal to form a specific structural pattern (e.g., a star graph if $m=1$).

Both estimators use the parameter $s$ to determine the size of the resulting subgraph.

A Random Dot Product Graph (RDPG) models the probability of an edge existing between nodes $i$ and $j$ based on their latent positions.

If $X imes ext{R}^{n imes d}$ represents the latent positions of the nodes, the probability of an edge existing is determined by the dot product of the positions: $P = XX^T$.

Adjacency Spectral Embedding (ASE) is a common method used to estimate these latent positions $\hat{X}$ from an adjacency matrix $A$. In an SBM (Stochastic Block Model) graph, ASE recovers the fact that nodes within the same community have similar latent positions, effectively clustering them in the embedded space.