NetworkGenerator: Generate instances from a class of random networks

New in version 1.0.0: Generators remove the need for sub-classing the dynamics classes in order to build instances of particular types of network, and also improve experiment reproducibility.

class epydemic.NetworkGenerator(params=None, limit=None)

Bases: object

An object that generates instances of networks on demand.

In stantsitical physics, an ensemble is a family of structures generated by a stochastic process with some specified parameters [Ken21]. In network science we often deal with ensembles of networks, for example the ensemble of all networks constructed by independently removing edges with some fixed probability (the ER networks), and are looking to find the “ensemble average” of some property, the value it takes on a “representative” network.

In epydemic, a network generator represents an ensemble of networks that can be sampled to acquire random instances needed for experiments. the parameters of the ensemble are taken from the experimental parameters. Sub-classes override the _generate() method to create new instances from the ensemble.

A generator is driven by experimental parameters passed to the experiment represented by the NetworkExperiment class. These can be set at construction and/or re-set using the set() method at any time.

The maximum number of instances the generator can generate can also be limited, which essentially creates a set of networks of the given class that are generated on demand. The limit can’t be changed and applies to the total number of networks generated, both singly (using generate()) and by iteration (using __iter__()).

Parameters:

• params (Optional[Dict[str, Any]]) – (optional) experimental parameters

• limit (Optional[int]) – (optional) maximum number of network instances to generate (defaults to unbounded)

Defining the class of network

The class of network generated by the generator is defined by sub-classing and overriding the _generate() method. This will make use of the experimental parameters governing the experiment in which the network is used.

NetworkGenerator.set(params)

Set the parameters for the family of networks generated by this generator.

Parameters:

params (Dict[str, Any]) – the parameters

Return type:

NetworkGenerator

Returns:

the generator

NetworkGenerator._generate(params)

Generate an instance of a network. This method isn’t called directly, but can be accessed through either the generate() method or through the iterator interface, Sub-classes should override this method to provide the code needed to create instances of the network family described by the generator, according to the experimental paramaters.

Parameters:

params (Dict[str, Any]) – the experimental parameters

Return type:

Graph

Returns:

a network instance

See Standard network generators for the built-in generators that create the most common kinds of network. See Building a network generator for an example of how to define a new generator.

Single instance generation

NetworkGenerator.generate()

Generate a new instance of a network. The method returns None if the total number of allowed instances have already been generated.

Return type:

Optional[Graph]

Returns:

a network instance or None

Multiple instance generation (iteration)

NetworkGenerator exports an iterator interface to allow the class of networks to be sampled repeatedly.

NetworkGenerator.__iter__()

Return iterator over the family of networks this generator generates.

Return type:

Iterator[Graph]

Returns:

the generator itself

NetworkGenerator.__next__()

Generate an instance of the network as long as the maximum number of instances (if any) have not already been generated.

Return type:

Graph

Returns:

a network