abcd-graph

A python library for generating ABCD graphs.

Installation

Using pip

pip install abcd-graph

Project available at PyPI.

From source

git clone https://github.com/AleksanderWWW/abcd-graph.git

# or - with ssh - git clone git@github.com:AleksanderWWW/abcd-graph.git
cd abcd-graph
pip install .

If you're using uv then run the following for lightning-fast installation:

uv pip install -r pyproject.toml .

Optional dependencies

The project comes with a set of optional dependencies that can be installed using the following commands:

pip install abcd-graph[dependency-name]

or

uv add abcd-graph --extra dependency-name

where dependency-name is one of the following:

Value	Packages installed
dev	pytest, pre-commit, pytest-cov
matplotlib	matplotlib
networkx	networkx
igraph	igraph
scipy	scipy
all	networkx, igraph, scipy, matplotlib

Usage

from abcd_graph import ABCDGraph, ABCDParams

params = ABCDParams(vcount=1000)
graph = ABCDGraph(params, logger=True).build()

Parameters

• params: An instance of ABCDParams class.
• logger A boolean to enable or disable logging to the console. Default is False - no logs are shown.
• callbacks: A list of instances of Callback class. Default is an empty list.

Returns

The ABCDGraph object with the generated graph.

Graph generation parameters - ABCDParams

The ABCDParams class is used to set the parameters for the graph generation.

Arguments:

Name	Type	Description	Default
vcount	int	Number of vertices in the graph	1000
gamma	float	Power-law parameter for degrees, between 2 and 3	2.5
min_degree	int	Min degree	5
max_degree	float	Parameter for max degree, between 0 and 1	0.5
beta	float	Power-law parameter for community sizes, between 1 and 2	1.5
min_community_size	int	Min community size	20
max_community_size	float	Parameter for max community size, between max_degree and 1	0.8
xi	float	Noise parameter, between 0 and 1	0.25
num_outliers	int	Number of outlier vertices in the resulting graph	0
degree_sequence	Sequence[int]	Custom degree sequence to use during graph building	None
community_size_sequence	Sequence[int]	Custom community size sequence to use during graph building	None

Parameters are validated when the object is created. If any of the parameters are invalid, a ValueError will be raised.

Notes

• You cannot pass both degree_sequence and any of gamma, min_degree or max_degree.
• You cannot pass both community_size_sequence and any of beta, min_community_size or max_community_size.

Communities and edges

The ABCDGraph object has two properties that can be used to access the communities and edges of the graph.

• communities - A list of ABCDCommunity objects.
• edges - A list of tuples representing the edges of the graph.

Example:

from abcd_graph import ABCDGraph, ABCDParams

params = ABCDParams(vcount=1000)

graph = ABCDGraph(params, logger=True).build()

print(graph.communities)
print(graph.edges)

Communities have the following properties:

• vertices - A list of vertices in the community.
• average_degree - The average degree of the community.
• degree_sequence - The degree sequence of the community.
• empirical_xi - The empirical xi of the community.

Exporting

Exporting the graph to different formats is done via the exporter property of the Graph object.

Possible formats are:

Method	Description	Additional packages	Installation command
to_networkx()	Export the graph to a networkx.Graph object.	networkx	pip install abcd-graph[networkx]
to_igraph()	Export the graph to an igraph.Graph object.	igraph	pip install abcd-graph[igraph]
to_adjacency_matrix()	Export the graph to a numpy.ndarray object representing the adjacency matrix.
to_sparse_adjacency_matrix()	Export the graph to a scipy.sparse.csr_matrix object representing the adjacency matrix.	scipy	pip install abcd-graph[scipy]

Example:

from abcd_graph import ABCDGraph, ABCDParams

params = ABCDParams(vcount=1000)
graph = ABCDGraph(params, logger=True).build()
graph_networkx = graph.exporter.to_networkx()

Callbacks

Callbacks are used to handle diagnostics and visualization of the graph generation process. They are instances of the ABCDCallback class.

Out of the box, the library provides three callbacks:

• StatsCollector - Collects statistics about the graph generation process.
• PropertyCollector - Collects properties of the graph.
• Visualizer - Visualizes the graph generation process.

Example:

from abcd_graph import ABCDGraph, ABCDParams

from abcd_graph.callbacks import StatsCollector, Visualizer, PropertyCollector

stats = StatsCollector()
vis = Visualizer()
props = PropertyCollector()
params = ABCDParams(vcount=1000)
g = ABCDGraph(params, logger=True, callbacks=[stats, vis, props]).build()

print(stats.statistics)

print(props.xi_matrix)

vis.draw_community_cdf()

Docker

To build a docker image containing the library, run:

docker build -t abcd-graph .

To run the image, use:

docker run -it abcd-graph

This will give you a python REPL inside a container with the library installed.

Available are also installation commands for the additional packages:

docker build -t abcd-test --build-arg INSTALL_TYPE=igraph .

Possible values for INSTALL_TYPE are dev, matplotlib, networkx, igraph, scipy and all.

Value	Packages installed
dev	pytest, pre-commit, pytest-cov
matplotlib	matplotlib
networkx	networkx
igraph	igraph
scipy	scipy
all	networkx, igraph, scipy, matplotlib

Warning

If you choose an option not included in the table above, the build process will fail.

Examples

The library comes with a set of examples that show how to use the library in different scenarios. You can find them in the examples directory in the format of Jupyter Notebooks.