Skip to main content
`Ctrl`+`K`

# scipy.stats.uniform_direction

scipy.stats.uniform_direction = <scipy.stats._multivariate.uniform_direction_gen object>

  A vector-valued uniform direction.

  Return a random direction (unit vector). The dim keyword specifies the dimensionality of the space.

  Parameters:
    dim scalar

      Dimension of directions.

    seed{None, int, `numpy.random.Generator`,

      > `numpy.random.RandomState`}, optional

      Used for drawing random variates. If seed is None, the RandomState singleton is used. If seed is an int, a new `RandomState` instance is used, seeded with seed. If seed is already a `RandomState` or `Generator` instance, then that object is used. Default is None.

  Notes

  This distribution generates unit vectors uniformly distributed on the surface of a hypersphere. These can be interpreted as random directions. For example, if dim is 3, 3D vectors from the surface of \(S^2\) will be sampled.

  References

  [1]

  Marsaglia, G. (1972). “Choosing a Point from the Surface of a Sphere”. Annals of Mathematical Statistics. 43 (2): 645-646.

  Examples

      >>> import numpy as np
      >>> from scipy.stats import uniform_direction
      >>> x = uniform_direction.rvs(3)
      >>> np.linalg.norm(x)
      1.

  This generates one random direction, a vector on the surface of \(S^2\).

  Alternatively, the object may be called (as a function) to return a frozen distribution with fixed dim parameter. Here, we create a `uniform_direction` with `dim=3` and draw 5 observations. The samples are then arranged in an array of shape 5x3.

      >>> rng = np.random.default_rng()
      >>> uniform_sphere_dist = uniform_direction(3)
      >>> unit_vectors = uniform_sphere_dist.rvs(5, random_state=rng)
      >>> unit_vectors
      array([[ 0.56688642, -0.1332634 , -0.81294566],
             [-0.427126  , -0.74779278,  0.50830044],
             [ 0.3793989 ,  0.92346629,  0.05715323],
             [ 0.36428383, -0.92449076, -0.11231259],
             [-0.27733285,  0.94410968, -0.17816678]])

  Methods

  rvs(dim=None, size=1, random_state=None) | Draw random directions.