References - netseer

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` | -- TODO | `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
    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: -- TODO

        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 list of graphs are sorted based on their file name in decending order.

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
    57
    def read_graph_list(filenames: list[str]) -> list[ig.Graph]:
        """Reads a list graphs from disk.

        The list of graphs are sorted based on their file name in decending order.

        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
        sorted_names = sorted(filenames)
        print(f"Reading in graph files: {sorted_names}")
        return [ig.read(filename) for filename in filenames]

### `read_pickled_list(filename)`

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

Compared to read_graph_list(), the de-serialised list has it's order maintained.

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`

    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    def read_pickled_list(filename: str) -> list[ig.Graph]:
        """Reads a saved list of graphs from a .pkl file.

        Compared to read_graph_list(), the de-serialised list has it's order maintained.

        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