Statistics
| Branch: | Revision:

iof-tools / networkxMiCe / networkx-master / doc / reference / randomness.rst @ 5cef0f13

History | View | Annotate | Download (4.04 KB)

1
.. _randomness:
2

    
3
Randomness
4
==========
5
.. currentmodule:: networkx
6

    
7
Random Number Generators (RNGs) are often used when generating, drawing
8
and computing properties or manipulating networks. NetworkX provides
9
functions which use one of two standard RNGs: NumPy's package `numpy.random`
10
or Python's built-in package `random`. They each provide the same 
11
algorithm for generating numbers (Mersenne Twister). Their interfaces
12
are similar (dangerously similar) and yet distinct. 
13
They each provide a global default instance of their generator that
14
is shared by all programs in a single session.
15
For the most part you can use the RNGs as NetworkX has them set up and
16
you'll get reasonable pseudorandom results (results that are statistically
17
random, but created in a deterministic manner). 
18

    
19
Sometimes you want more control over how the numbers are generated.
20
In particular, you need to set the `seed` of the generator to make
21
your results reproducible -- either for scientific publication or 
22
for debugging. Both RNG packages have easy functions to set the seed
23
to any integer, thus determining the subsequent generated values.
24
Since this package (and many others) use both RNGs you may need to
25
set the `seed` of both RNGs.  Even if we strictly only used one of the
26
RNGs, you may find yourself using another package that uses the other.
27
Setting the state of the two global RNGs is as simple setting the
28
seed of each RNG to an arbitrary integer:
29

    
30
.. nbplot::
31

    
32
   >>> import random
33
   >>> random.seed(246)        # or any integer
34
   >>> import numpy
35
   >>> numpy.random.seed(4812)
36

    
37
Many users will be satisfied with this level of control.
38

    
39
For people who want even more control, we include an optional argument
40
to functions that use an RNG.  This argument is called `seed`, but
41
determines more than the seed of the RNG. It tells the function which
42
RNG package to use, and whether to use a global or local RNG.
43

    
44
.. nbplot::
45

    
46
    >>> from networkx import path_graph, random_layout
47
    >>> G = path_graph(9)
48
    >>> pos = random_layout(G, seed=None)  # use (either) global default RNG
49
    >>> pos = random_layout(G, seed=42)  # local RNG just for this call
50
    >>> pos = random_layout(G, seed=numpy.random)  # use numpy global RNG
51
    >>> random_state = numpy.random.RandomState(42) 
52
    >>> pos = random_layout(G, seed=random_state)  # use/reuse your own RNG
53

    
54
Each NetworkX function that uses an RNG was written with one RNG package
55
in mind. It either uses `random` or `numpy.random` by default.
56
But some users want to only use a single RNG for all their code.
57
This `seed` argument provides a mechanism so that any function
58
can use a `numpy.random` RNG even if the function is written for `random`.
59
It works as follows.
60

    
61
The default behavior (when `seed=None`) is to use the global RNG
62
for the function's preferred package. 
63
If seed is set to an integer value,
64
a local RNG is created with the indicated seed value and
65
is used for the duration of that function (including any
66
calls to other functions) and then discarded.
67
Alternatively, you can specify `seed=numpy.random` to ensure that
68
the global numpy RNG is used whether the function expects it or not.
69
Finally, you can provide a numpy RNG to be used by the function.
70
The RNG is then available to use in other functions or even other
71
package like sklearn.
72
In this way you can use a single RNG for all random numbers 
73
in your project.
74

    
75
While it is possible to assign `seed` a `random`-style RNG for
76
NetworkX functions written for the `random` package API,
77
the numpy RNG interface has too 
78
many nice features for us to ensure a `random`-style RNG will work in
79
all functions. In practice, you can do most things using only `random`
80
RNGs (useful if numpy is not available). But your experience will be
81
richer if numpy is available.
82

    
83
To summarize, you can easily ignore the `seed` argument and use the global
84
RNGs. You can specify to use only the numpy global RNG with 
85
`seed=numpy.random`. You can use a local RNG by providing an integer
86
seed value. And you can provide your own numpy RNG, reusing it for all
87
functions. It is easier to use numpy RNGs if you want a single RNG for 
88
your computations.