random_k_out_graph#

random_k_out_graph(n, k, alpha, self_loops=True, seed=None)[source]#

Returns a random k-out graph with preferential attachment.

Changed in version 3.5: Different implementations will be used based on whether NumPy is available. See Notes for details.

A random k-out graph with preferential attachment is a multidigraph generated by the following algorithm.

  1. Begin with an empty digraph, and initially set each node to have weight alpha.

  2. Choose a node u with out-degree less than k uniformly at random.

  3. Choose a node v from with probability proportional to its weight.

  4. Add a directed edge from u to v, and increase the weight of v by one.

  5. If each node has out-degree k, halt, otherwise repeat from step 2.

For more information on this model of random graph, see [1].

Parameters:
nint

The number of nodes in the returned graph.

kint

The out-degree of each node in the returned graph.

alphafloat

A positive float representing the initial weight of each vertex. A higher number means that in step 3 above, nodes will be chosen more like a true uniformly random sample, and a lower number means that nodes are more likely to be chosen as their in-degree increases. If this parameter is not positive, a ValueError is raised.

self_loopsbool

If True, self-loops are allowed when generating the graph.

seedinteger, random_state, or None (default)

Indicator of random number generation state. See Randomness.

Returns:
MultiDiGraph

A k-out-regular multidigraph generated according to the above algorithm.

Raises:
ValueError

If alpha is not positive.

Notes

The returned multidigraph may not be strongly connected, or even weakly connected.

random_k_out_graph has two implementations: an array-based formulation that uses numpy (_random_k_out_graph_numpy), and a pure-Python implementation (_random_k_out_graph_python). The NumPy implementation is more performant, especially for large n, and is therefore used by default. If NumPy is not installed in the environment, then the pure Python implementation is executed. However, you can explicitly control which implementation is executed by directly calling the corresponding function:

# Use numpy if available, else Python
nx.random_k_out_graph(1000, 5, alpha=1)

# Use the numpy-based implementation (raises ImportError if numpy not installed)
nx.generators.directed._random_k_out_graph_numpy(1000, 5, alpha=1)

# Use the Python-based implementation
nx.generators.directed._random_k_out_graph_python(1000, 5, alpha=1)

References

[1]

Peterson, Nicholas R., and Boris Pittel. “Distance between two random k-out digraphs, with and without preferential attachment.” arXiv preprint arXiv:1311.5961 (2013) <https://arxiv.org/abs/1311.5961>.