Skip to content

References

Introduction

User Facing Modules:

  • generate_graph: Contains functions for creating new graphs e.g. A randomly growing list of graphs.
  • prediction: Contains functions for predicting the next graph in a time-series list of graphs.
  • utils: Contains helper functions, such as loading graphs from disk.

Internally used Modules:

  • forecasting: Internal functions that assist in predictions.
  • netseer: Used for running via CLI for testing

Prediction Module

Prediction Module:

Typical Usage Example 
from netseer import utils, generate_graph, prediction
from pathlib import Path

# Get the directory/folder with all the graphs.
directory_path = Path.cwd() / Path("path/to/data")
# Use glob to get a list of absolute paths for .gml files.
graph_files = directory_path.glob("*.gml"))

# Load the graphs into igraph using the list of gml files.
graph_list = utils.read_graph_list(graph_files)
# Predict the next graph.
predict = prediction.predict_graph(graph_list, h=1)

predict_graph(graph_list, h=5, conf_nodes=None, conf_degree=90, weights_option=4)

From a list of graphs, predicts a new graph

Parameters:

Name Type Description Default
graph_list Iterable[Graph]

A list of graphs to be predicted on: See generate_graph_list()

 required
h int

How many steps into the future the prediction should be.

 5
conf_nodes

-- TODO

 None
conf_degree int

-- TODO

 90
weights_option int

Int between 1-7 determines the weight of newly created edges. 1-3: Weight 0 for all edges. 4: Weight 1 for all edges. 5: Linear scaling weights for new edges (x+1). E.g. 1, 2, 3 6: Proportional Weights. 7: Weight 0 for all edges, except for last edge which is 1.

 4

Returns:

Type Description
Graph

Predicted Graph.
Source code in src/netseer/prediction.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def predict_graph(
    graph_list: Iterable[ig.Graph],
    h: int = 5,
    conf_nodes=None,
    conf_degree: int = 90,
    weights_option: int = 4,
) -> ig.Graph:
    """From a list of graphs, predicts a new graph

    Args:
        graph_list: A list of graphs to be predicted on: See generate_graph_list()
        h: How many steps into the future the prediction should be.
        conf_nodes: -- TODO
        conf_degree: -- TODO
        weights_option: Int between 1-7 determines the weight of newly created edges.
            1-3: Weight 0 for all edges.
            4: Weight 1 for all edges.
            5: Linear scaling weights for new edges (x+1). E.g. 1, 2, 3
            6: Proportional Weights.
            7: Weight 0 for all edges, except for last edge which is 1.

    Returns:
        Predicted Graph.
    """

    print("Forecasting properties of the new graph")
    # predict the number of nodes for the predicted graph
    new_nodes, new_nodes_lower, new_nodes_upper = forecasting.predict_num_nodes(
        graph_list, h=h, conf_level=conf_nodes
    )
    # predict the degrees for the new nodes
    new_nodes_degrees = forecasting.predict_new_nodes_degrees(graph_list)

    # predict the degrees of the existing nodes
    existing_nodes_degrees = forecasting.predict_existing_nodes_degrees(
        graph_list, h=h, conf_level=conf_degree
    )

    total_edges = forecasting.predict_total_edges_counts(
        graph_list, h=h, conf_level=conf_degree
    )

    EDGES_CONF_LEVEL = "conf_high"  # "mean"
    print("Using forecasts to predict the new graph")
    mean_graph = predict_graph_from_forecasts(
        graph_list,
        new_nodes,
        existing_nodes_degrees[EDGES_CONF_LEVEL],
        new_nodes_degrees,
        total_edges[EDGES_CONF_LEVEL],
        conf_nodes,
        conf_degree,
        weights_option,
    )

    print("done")
    return mean_graph

Utils Module

Utility functions that help with dataloading

Typical functions 
from netseer import utils, prediction
from pathlib import Path

# Get the directory/folder with all the graphs.
directory_path = Path.cwd() / Path("path/to/data")
# Use glob to get a list of absolute paths for .gml files.
graph_files = directory_path.glob("*.gml"))

# Load the graphs into igraph using the list of gml files.
graph_list = utils.read_graph_list(graph_files)

# Then use the list of graphs for predictions.
predict = prediction.predict_graph(graph_list, h=1)

read_graph_list()

read_graph_list(filenames)

Reads a list graphs from disk.

The graphs are read in index order, therefore the first graph in the time-series is at index 0.

Parameters:

Name Type Description Default
filenames list[str]

A list of absolute paths to ig.read compatible graphs. E.g. *.gml files.

 required

Returns:

Type Description
list[Graph]

A list of read graphs.
Source code in src/netseer/utils.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def read_graph_list(filenames: list[str]) -> list[ig.Graph]:
    """Reads a list graphs from disk.

    The graphs are read in index order, therefore the first graph in the time-series is at index 0.

    Args:
        filenames: A list of absolute paths to ig.read compatible graphs. E.g. *.gml files.

    Returns:
        A list of read graphs.
    """
    # read a list of saved graph files
    print(f"Reading in graph files: {filenames}")
    return [ig.read(filename) for filename in filenames]

read_pickled_list(filename)

Reads a saved list of graphs from a .pkl file.

Parameters:

Name Type Description Default
filename str

Absolute path to the .pkl file.

 required

Returns:

Type Description
list[Graph]

A list of graphs.
Source code in src/netseer/utils.py 
59
60
61
62
63
64
65
66
67
68
69
70
def read_pickled_list(filename: str) -> list[ig.Graph]:
    """Reads a saved list of graphs from a .pkl file.

    Args:
        filename: Absolute path to the .pkl file.

    Returns:
        A list of graphs.
    """
    # read a graph list that is stored in a single pickled file
    print(f"Reading pickled graph list from {filename}")
    return pickle.load(filename)

Generate Graph Module

Contains functions for generating a list of graphs.

Typical usage example 
from netseer import generate_graph, prediction

graph_list = generate_graph.generate_graph_list()
predict = prediction.predict_graph(graph_list, h=1)

generate_graph_list(start_nodes=1000, add_nodes=50, add_edges=200, rem_edges=100, nn_edges=3, num_iters=15, mode='linear')

Randomly generate a list of graphs using supplied parameters.

Parameters:

Name Type Description Default
start_nodes int

Number of nodes the first graph will have.

 1000
add_nodes int

Number of nodes the graph will grow by each step.

 50
add_edges int

Number of edges the graph will grow by each step.

 200
rem_edges int

Number of edges that are removed each step.

 100
num_iters int

How many times should the graph grow.

 15
mode str

Graph growth method. Linear Growth = 'linear', Exponential growth = 'exp'

 'linear'

Returns:

Type Description
list[Graph]

A list of graphs, with index 0 being the first generated graph.
Source code in src/netseer/generate_graph.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def generate_graph_list(
    start_nodes: int = 1000,
    add_nodes: int = 50,
    add_edges: int = 200,
    rem_edges: int = 100,
    nn_edges: int = 3,
    num_iters: int = 15,
    mode: str = "linear",
) -> list[ig.Graph]:
    """Randomly generate a list of graphs using supplied parameters.

    Args:
        start_nodes: Number of nodes the first graph will have.
        add_nodes: Number of nodes the graph will grow by each step.
        add_edges: Number of edges the graph will grow by each step.
        rem_edges: Number of edges that are removed each step.
        num_iters: How many times should the graph grow.
        mode: Graph growth method. Linear Growth = 'linear', Exponential growth = 'exp'

    Returns:
        A list of graphs, with index 0 being the first generated graph.
    """
    graph_list = [None] * num_iters
    initial_graph = ig.Graph.Barabasi(n=start_nodes, directed=False)
    graph_list[0] = initial_graph
    for i in range(1, num_iters):
        graph_list[i] = generate_next_graph(
            graph_list[i - 1], add_nodes, add_edges, rem_edges, nn_edges
        )
    return graph_list

Forecasting Module

Internal: Supplimentary functions for predictions.

Netseer Module

Internal: This Module is only used for running Netseer via the CLI for testing.

Typical usage example 
python netseer.py --random_graph
# As we use uv and it's hard to add in args, instead there is a script in pyproject.toml:
uv run random