Skip to main content
`Ctrl`+`K`
scipy.sparse.

# random

scipy.sparse.random(m, n, density=0.01, format='coo', dtype=None, rng=None, data_rvs=None, *, random_state=None)

  Generate a sparse matrix of the given shape and density with randomly distributed values.

  Warning

  This function returns a sparse matrix – not a sparse array. You are encouraged to use `random_array` to take advantage of the sparse array functionality.

  Parameters:
    m, n int

      shape of the matrix

    density real, optional

      density of the generated matrix: density equal to one means a full matrix, density of 0 means a matrix with no non-zero items.

    format str, optional

      sparse matrix format.

    dtype dtype, optional

      type of the returned matrix values.

    rng{None, int, `numpy.random.Generator`}, optional

      If rng is passed by keyword, types other than `numpy.random.Generator` are passed to `numpy.random.default_rng` to instantiate a `Generator`. If rng is already a `Generator` instance, then the provided instance is used. Specify rng for repeatable function behavior.

      If this argument is passed by position or random_state is passed by keyword, legacy behavior for the argument random_state applies:

      - If random_state is None (or `numpy.random`), the `numpy.random.RandomState` singleton is used.

      - If random_state is an int, a new `RandomState` instance is used, seeded with random_state.

      - If random_state is already a `Generator` or `RandomState` instance then that instance is used.

      Changed in version 1.15.0: As part of the SPEC-007 transition from use of `numpy.random.RandomState` to `numpy.random.Generator`, this keyword was changed from random_state to rng. For an interim period, both keywords will continue to work, although only one may be specified at a time. After the interim period, function calls using the random_state keyword will emit warnings. The behavior of both random_state and rng are outlined above, but only the rng keyword should be used in new code.

      This random state will be used for sampling the sparsity structure, but not necessarily for sampling the values of the structurally nonzero entries of the matrix.

    data_rvs callable, optional

      Samples a requested number of random values. This function should take a single argument specifying the length of the ndarray that it will return. The structurally nonzero entries of the sparse random matrix will be taken from the array sampled by this function. By default, uniform [0, 1) random values will be sampled using the same random state as is used for sampling the sparsity structure.

  Returns:
    res sparse matrix

      Random sparse matrix.

  See also

  `random_array`

    constructs sparse arrays instead of sparse matrices

  Examples

  Passing a `np.random.Generator` instance for better performance:

      >>> import scipy as sp
      >>> import numpy as np
      >>> rng = np.random.default_rng()
      >>> S = sp.sparse.random(3, 4, density=0.25, rng=rng)

  Providing a sampler for the values:

      >>> rvs = sp.stats.poisson(25, loc=10).rvs
      >>> S = sp.sparse.random(3, 4, density=0.25, rng=rng, data_rvs=rvs)
      >>> S.toarray()
      array([[ 36.,   0.,  33.,   0.],   # random
             [  0.,   0.,   0.,   0.],
             [  0.,   0.,  36.,   0.]])

  Building a custom distribution. This example builds a squared normal from np.random:

      >>> def np_normal_squared(size=None, rng=rng):
      ...     return rng.standard_normal(size) ** 2
      >>> S = sp.sparse.random(3, 4, density=0.25, rng=rng,
      ...                      data_rvs=np_normal_squared)

  Or we can build it from sp.stats style rvs functions:

      >>> def sp_stats_normal_squared(size=None, rng=rng):
      ...     std_normal = sp.stats.distributions.norm_gen().rvs
      ...     return std_normal(size=size, random_state=rng) ** 2
      >>> S = sp.sparse.random(3, 4, density=0.25, rng=rng,
      ...                      data_rvs=sp_stats_normal_squared)

  Or we can subclass sp.stats rv_continuous or rv_discrete:

      >>> class NormalSquared(sp.stats.rv_continuous):
      ...     def _rvs(self,  size=None, random_state=rng):
      ...         return rng.standard_normal(size) ** 2
      >>> X = NormalSquared()
      >>> Y = X()  # get a frozen version of the distribution
      >>> S = sp.sparse.random(3, 4, density=0.25, rng=rng, data_rvs=Y.rvs)