scico.random¶
Random number generation.
This module provides convenient wrappers around several jax.random routines to
handle the generation and splitting of PRNG keys, as well as the
generation of random BlockArray
:
# Calls to scico.random functions always return a PRNG key
# If no key is passed to the function, a new key is generated
x, key = scico.random.randn((2,))
print(x) # [ 0.19307713 -0.52678305]
# scico.random functions automatically split the PRNGkey and return
# an updated key
y, key = scico.random.randn((2,), key=key)
print(y) # [ 0.00870693 -0.04888531]
The user is responsible for passing the PRNG key to scico.random
functions. If no key is passed, repeated calls to scico.random
functions will return the same random numbers:
x, key = scico.random.randn((2,))
print(x) # [ 0.19307713 -0.52678305]
# No key passed, will return the same random numbers!
y, key = scico.random.randn((2,))
print(y) # [ 0.19307713 -0.52678305]
If the desired shape is a tuple containing tuples, a BlockArray
is returned:
x, key = scico.random.randn( ((1, 1), (2,)), key=key)
print(x) # scico.numpy.BlockArray:
# Array([ 1.1378784 , -1.220955 , -0.59153646], dtype=float32)
Functions
|
Sample uniformly from the unit Lp ball. |
|
Sample Bernoulli random values with given shape and mean. |
|
Sample Beta random values with given shape and float dtype. |
|
Sample Binomial random values with given shape and float dtype. |
|
Sample uniform bits in the form of unsigned integers. |
|
Sample random values from categorical distributions. |
|
Sample Cauchy random values with given shape and float dtype. |
|
Sample Chisquare random values with given shape and float dtype. |
|
Generates a random sample from a given array. |
|
Sample Dirichlet random values with given shape and float dtype. |
|
Sample from a double sided Maxwell distribution. |
|
Sample Exponential random values with given shape and float dtype. |
|
Sample F-distribution random values with given shape and float dtype. |
|
Sample Gamma random values with given shape and float dtype. |
|
Sample from the generalized normal distribution. |
|
Sample Geometric random values with given shape and float dtype. |
|
Sample Gumbel random values with given shape and float dtype. |
|
Sample Laplace random values with given shape and float dtype. |
|
Sample log-gamma random values with given shape and float dtype. |
|
Sample logistic random values with given shape and float dtype. |
|
Sample lognormal random values with given shape and float dtype. |
|
Sample from a one sided Maxwell distribution. |
|
Sample multivariate normal random values with given mean and covariance. |
|
Sample standard normal random values with given shape and float dtype. |
|
Sample uniformly from the orthogonal group O(n). |
|
Sample Pareto random values with given shape and float dtype. |
|
Sample Poisson random values with given shape and integer dtype. |
|
Sample from a Rademacher distribution. |
|
Sample uniform random values in [minval, maxval) with given shape/dtype. |
|
Return an array drawn from the standard normal distribution. |
|
Sample Rayleigh random values with given shape and float dtype. |
|
Sample Student's t random values with given shape and float dtype. |
|
Sample Triangular random values with given shape and float dtype. |
|
Sample truncated standard normal random values with given shape and dtype. |
|
Sample uniform random values in [minval, maxval) with given shape/dtype. |
|
Sample Wald random values with given shape and float dtype. |
|
Sample from a Weibull distribution. |
- scico.random.randn(shape, dtype=<class 'numpy.float32'>, key=None, seed=None)[source]¶
Return an array drawn from the standard normal distribution.
Alias for
scico.random.normal
.- Parameters:
shape (
Union
[Tuple
[int
,...
],Tuple
[Tuple
[int
,...
],...
]]) – Shape of output array. If shape is a tuple, ajax.Array
is returned. If shape is a tuple of tuples, aBlockArray
is returned.key (
Optional
[Array
]) – JAX PRNGKey. Defaults toNone
, in which case a new key is created using the seed arg.dtype (
DType
) – dtype for returned value. Defaults tofloat32
. If a complex dtype such ascomplex64
, generates an array sampled from complex normal distribution.
- Return type:
Tuple
[Union
[Array
,BlockArray
],Array
]- Returns:
tuple –
A tuple (x, key) containing:
x : (
jax.Array
): Generated random array.key : Updated random PRNGKey.
- scico.random.ball(*args, key=None, seed=None, **kwargs)¶
Sample uniformly from the unit Lp ball.
Wrapped version of jax.random.ball. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
Reference: https://arxiv.org/abs/math/0503650.
- Parameters:
key – a PRNG key used as the random key.
d – a nonnegative int representing the dimensionality of the ball.
p – a float representing the p parameter of the Lp norm.
shape – optional, the batch dimensions of the result. Default ().
dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array of shape (*shape, d) and specified dtype.
- scico.random.bernoulli(*args, key=None, seed=None, **kwargs)¶
Sample Bernoulli random values with given shape and mean.
Wrapped version of jax.random.bernoulli. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability mass function:
\[f(k; p) = p^k(1 - p)^{1 - k}\]where \(k \in \{0, 1\}\) and \(0 \le p \le 1\).
- Parameters:
key – a PRNG key used as the random key.
p – optional, a float or array of floats for the mean of the random variables. Must be broadcast-compatible with
shape
. Default 0.5.shape – optional, a tuple of nonnegative integers representing the result shape. Must be broadcast-compatible with
p.shape
. The default (None) produces a result shape equal top.shape
.
- Returns:
A random array with boolean dtype and shape given by
shape
ifshape
is not None, or elsep.shape
.
- scico.random.beta(*args, key=None, seed=None, **kwargs)¶
Sample Beta random values with given shape and float dtype.
Wrapped version of jax.random.beta. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x;a,b) \propto x^{a - 1}(1 - x)^{b - 1}\]on the domain \(0 \le x \le 1\).
- Parameters:
key – a PRNG key used as the random key.
a – a float or array of floats broadcast-compatible with
shape
representing the first parameter “alpha”.b – a float or array of floats broadcast-compatible with
shape
representing the second parameter “beta”.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
a
andb
. The default (None) produces a result shape by broadcastinga
andb
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and shape given by
shape
ifshape
is not None, or else by broadcastinga
andb
.
- scico.random.binomial(*args, key=None, seed=None, **kwargs)¶
Sample Binomial random values with given shape and float dtype.
Wrapped version of jax.random.binomial. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are returned according to the probability mass function:
\[f(k;n,p) = \binom{n}{k}p^k(1-p)^{n-k}\]on the domain \(0 < p < 1\), and where \(n\) is a nonnegative integer representing the number of trials and \(p\) is a float representing the probability of success of an individual trial.
- Parameters:
key – a PRNG key used as the random key.
n – a float or array of floats broadcast-compatible with
shape
representing the number of trials.p – a float or array of floats broadcast-compatible with
shape
representing the probability of success of an individual trial.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
n
andp
. The default (None) produces a result shape equal tonp.broadcast(n, p).shape
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and with shape given by
np.broadcast(n, p).shape
.
- scico.random.bits(*args, key=None, seed=None, **kwargs)¶
Sample uniform bits in the form of unsigned integers.
Wrapped version of jax.random.bits. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
- Parameters:
key – a PRNG key used as the random key.
shape – optional, a tuple of nonnegative integers representing the result shape. Default
()
.dtype – optional, an unsigned integer dtype for the returned values (default
uint64
ifjax_enable_x64
is true, otherwiseuint32
).
- Returns:
A random array with the specified shape and dtype.
- scico.random.categorical(*args, key=None, seed=None, **kwargs)¶
Sample random values from categorical distributions.
Wrapped version of jax.random.categorical. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
- Parameters:
key – a PRNG key used as the random key.
logits – Unnormalized log probabilities of the categorical distribution(s) to sample from, so that softmax(logits, axis) gives the corresponding probabilities.
axis – Axis along which logits belong to the same categorical distribution.
shape – Optional, a tuple of nonnegative integers representing the result shape. Must be broadcast-compatible with
np.delete(logits.shape, axis)
. The default (None) produces a result shape equal tonp.delete(logits.shape, axis)
.
- Returns:
A random array with int dtype and shape given by
shape
ifshape
is not None, or elsenp.delete(logits.shape, axis)
.
- scico.random.cauchy(*args, key=None, seed=None, **kwargs)¶
Sample Cauchy random values with given shape and float dtype.
Wrapped version of jax.random.cauchy. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x) \propto \frac{1}{x^2 + 1}\]on the domain \(-\infty < x < \infty\)
- Parameters:
key – a PRNG key used as the random key.
shape – optional, a tuple of nonnegative integers representing the result shape. Default ().
dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified shape and dtype.
- scico.random.chisquare(*args, key=None, seed=None, **kwargs)¶
Sample Chisquare random values with given shape and float dtype.
Wrapped version of jax.random.chisquare. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x; \nu) \propto x^{k/2 - 1}e^{-x/2}\]on the domain \(0 < x < \infty\), where \(\nu > 0\) represents the degrees of freedom, given by the parameter
df
.- Parameters:
key – a PRNG key used as the random key.
df – a float or array of floats broadcast-compatible with
shape
representing the parameter of the distribution.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
df
. The default (None) produces a result shape equal todf.shape
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and with shape given by
shape
ifshape
is not None, or else bydf.shape
.
- scico.random.choice(*args, key=None, seed=None, **kwargs)¶
Generates a random sample from a given array.
Wrapped version of jax.random.choice. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
Warning
If
p
has fewer non-zero elements than the requested number of samples, as specified inshape
, andreplace=False
, the output of this function is ill-defined. Please make sure to use appropriate inputs.- Parameters:
key – a PRNG key used as the random key.
a – array or int. If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if a were arange(a).
shape – tuple of ints, optional. Output shape. If the given shape is, e.g.,
(m, n)
, thenm * n
samples are drawn. Default is (), in which case a single value is returned.replace – boolean. Whether the sample is with or without replacement. default is True.
p – 1-D array-like, The probabilities associated with each entry in a. If not given the sample assumes a uniform distribution over all entries in a.
axis – int, optional. The axis along which the selection is performed. The default, 0, selects by row.
- Returns:
An array of shape shape containing samples from a.
- scico.random.dirichlet(*args, key=None, seed=None, **kwargs)¶
Sample Dirichlet random values with given shape and float dtype.
Wrapped version of jax.random.dirichlet. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(\{x_i\}; \{\alpha_i\}) = \propto \prod_{i=1}^k x_i^{\alpha_i - 1}\]Where \(k\) is the dimension, and \(\{x_i\}\) satisfies
\[\sum_{i=1}^k x_i = 1\]and \(0 \le x_i \le 1\) for all \(x_i\).
- Parameters:
key – a PRNG key used as the random key.
alpha – an array of shape
(..., n)
used as the concentration parameter of the random variables.shape – optional, a tuple of nonnegative integers specifying the result batch shape; that is, the prefix of the result shape excluding the last element of value
n
. Must be broadcast-compatible withalpha.shape[:-1]
. The default (None) produces a result shape equal toalpha.shape
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and shape given by
shape + (alpha.shape[-1],)
ifshape
is not None, or elsealpha.shape
.
- scico.random.double_sided_maxwell(*args, key=None, seed=None, **kwargs)¶
Sample from a double sided Maxwell distribution.
Wrapped version of jax.random.double_sided_maxwell. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x;\mu,\sigma) \propto z^2 e^{-z^2 / 2}\]where \(z = (x - \mu) / \sigma\), with the center \(\mu\) specified by
loc
and the scale \(\sigma\) specified byscale
.- Parameters:
key – a PRNG key.
loc – The location parameter of the distribution.
scale – The scale parameter of the distribution.
shape – The shape added to the parameters loc and scale broadcastable shape.
dtype – The type used for samples.
- Returns:
A jnp.array of samples.
- scico.random.exponential(*args, key=None, seed=None, **kwargs)¶
Sample Exponential random values with given shape and float dtype.
Wrapped version of jax.random.exponential. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x) = e^{-x}\]on the domain \(0 \le x < \infty\).
- Parameters:
key – a PRNG key used as the random key.
shape – optional, a tuple of nonnegative integers representing the result shape. Default ().
dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified shape and dtype.
- scico.random.f(*args, key=None, seed=None, **kwargs)¶
Sample F-distribution random values with given shape and float dtype.
Wrapped version of jax.random.f. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x; \nu) \propto x^{\nu_1/2 - 1}\left(1 + \frac{\nu_1}{\nu_2}x\right)^{ -(\nu_1 + \nu_2) / 2}\]on the domain \(0 < x < \infty\). Here \(\nu_1\) is the degrees of freedom of the numerator (
dfnum
), and \(\nu_2\) is the degrees of freedom of the denominator (dfden
).- Parameters:
key – a PRNG key used as the random key.
dfnum – a float or array of floats broadcast-compatible with
shape
representing the numerator’sdf
of the distribution.dfden – a float or array of floats broadcast-compatible with
shape
representing the denominator’sdf
of the distribution.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
dfnum
anddfden
. The default (None) produces a result shape equal todfnum.shape
, anddfden.shape
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and with shape given by
shape
ifshape
is not None, or else bydf.shape
.
- scico.random.gamma(*args, key=None, seed=None, **kwargs)¶
Sample Gamma random values with given shape and float dtype.
Wrapped version of jax.random.gamma. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x;a) \propto x^{a - 1} e^{-x}\]on the domain \(0 \le x < \infty\), with \(a > 0\).
This is the standard gamma density, with a unit scale/rate parameter. Dividing the sample output by the rate is equivalent to sampling from gamma(a, rate), and multiplying the sample output by the scale is equivalent to sampling from gamma(a, scale).
- Parameters:
key – a PRNG key used as the random key.
a – a float or array of floats broadcast-compatible with
shape
representing the parameter of the distribution.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
a
. The default (None) produces a result shape equal toa.shape
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and with shape given by
shape
ifshape
is not None, or else bya.shape
.
See also
- loggammasample gamma values in log-space, which can provide improved
accuracy for small values of
a
.
- scico.random.generalized_normal(*args, key=None, seed=None, **kwargs)¶
Sample from the generalized normal distribution.
Wrapped version of jax.random.generalized_normal. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are returned according to the probability density function:
\[f(x;p) \propto e^{-|x|^p}\]on the domain \(-\infty < x < \infty\), where \(p > 0\) is the shape parameter.
- Parameters:
key – a PRNG key used as the random key.
p – a float representing the shape parameter.
shape – optional, the batch dimensions of the result. Default ().
dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified shape and dtype.
- scico.random.geometric(*args, key=None, seed=None, **kwargs)¶
Sample Geometric random values with given shape and float dtype.
Wrapped version of jax.random.geometric. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are returned according to the probability mass function:
\[f(k;p) = p(1-p)^{k-1}\]on the domain \(0 < p < 1\).
- Parameters:
key – a PRNG key used as the random key.
p – a float or array of floats broadcast-compatible with
shape
representing the probability of success of an individual trial.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
p
. The default (None) produces a result shape equal tonp.shape(p)
.dtype – optional, a int dtype for the returned values (default int64 if jax_enable_x64 is true, otherwise int32).
- Returns:
A random array with the specified dtype and with shape given by
shape
ifshape
is not None, or else byp.shape
.
- scico.random.gumbel(*args, key=None, seed=None, **kwargs)¶
Sample Gumbel random values with given shape and float dtype.
Wrapped version of jax.random.gumbel. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x) = e^{-(x + e^{-x})}\]- Parameters:
key – a PRNG key used as the random key.
shape – optional, a tuple of nonnegative integers representing the result shape. Default ().
dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified shape and dtype.
- scico.random.laplace(*args, key=None, seed=None, **kwargs)¶
Sample Laplace random values with given shape and float dtype.
Wrapped version of jax.random.laplace. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x) = \frac{1}{2}e^{-|x|}\]- Parameters:
key – a PRNG key used as the random key.
shape – optional, a tuple of nonnegative integers representing the result shape. Default ().
dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified shape and dtype.
- scico.random.loggamma(*args, key=None, seed=None, **kwargs)¶
Sample log-gamma random values with given shape and float dtype.
Wrapped version of jax.random.loggamma. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
This function is implemented such that the following will hold for a dtype-appropriate tolerance:
np.testing.assert_allclose(jnp.exp(loggamma(*args)), gamma(*args), rtol=rtol)
The benefit of log-gamma is that for samples very close to zero (which occur frequently when a << 1) sampling in log space provides better precision.
- Parameters:
key – a PRNG key used as the random key.
a – a float or array of floats broadcast-compatible with
shape
representing the parameter of the distribution.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
a
. The default (None) produces a result shape equal toa.shape
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and with shape given by
shape
ifshape
is not None, or else bya.shape
.
See also
gamma : standard gamma sampler.
- scico.random.logistic(*args, key=None, seed=None, **kwargs)¶
Sample logistic random values with given shape and float dtype.
Wrapped version of jax.random.logistic. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x) = \frac{e^{-x}}{(1 + e^{-x})^2}\]- Parameters:
key – a PRNG key used as the random key.
shape – optional, a tuple of nonnegative integers representing the result shape. Default ().
dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified shape and dtype.
- scico.random.lognormal(*args, key=None, seed=None, **kwargs)¶
Sample lognormal random values with given shape and float dtype.
Wrapped version of jax.random.lognormal. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x) = \frac{1}{x\sqrt{2\pi\sigma^2}}\exp\left(-\frac{(\log x)^2}{2\sigma^2}\right)\]on the domain \(x > 0\).
- Parameters:
key – a PRNG key used as the random key.
sigma – a float or array of floats broadcast-compatible with
shape
representing the standard deviation of the underlying normal distribution. Default 1.shape – optional, a tuple of nonnegative integers specifying the result shape. The default (None) produces a result shape equal to
()
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and with shape given by
shape
.
- scico.random.maxwell(*args, key=None, seed=None, **kwargs)¶
Sample from a one sided Maxwell distribution.
Wrapped version of jax.random.maxwell. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x) \propto x^2 e^{-x^2 / 2}\]on the domain \(0 \le x < \infty\).
- Parameters:
key – a PRNG key.
shape – The shape of the returned samples.
dtype – The type used for samples.
- Returns:
A jnp.array of samples, of shape shape.
- scico.random.multivariate_normal(*args, key=None, seed=None, **kwargs)¶
Sample multivariate normal random values with given mean and covariance.
Wrapped version of jax.random.multivariate_normal. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are returned according to the probability density function:
\[f(x;\mu, \Sigma) = (2\pi)^{-k/2} \det(\Sigma)^{-1}e^{-\frac{1}{2}(x - \mu)^T \Sigma^{-1} (x - \mu)}\]where \(k\) is the dimension, \(\mu\) is the mean (given by
mean
) and \(\Sigma\) is the covariance matrix (given bycov
).- Parameters:
key – a PRNG key used as the random key.
mean – a mean vector of shape
(..., n)
.cov – a positive definite covariance matrix of shape
(..., n, n)
. The batch shape...
must be broadcast-compatible with that ofmean
.shape – optional, a tuple of nonnegative integers specifying the result batch shape; that is, the prefix of the result shape excluding the last axis. Must be broadcast-compatible with
mean.shape[:-1]
andcov.shape[:-2]
. The default (None) produces a result batch shape by broadcasting together the batch shapes ofmean
andcov
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
method – optional, a method to compute the factor of
cov
. Must be one of ‘svd’, ‘eigh’, and ‘cholesky’. Default ‘cholesky’. For singular covariance matrices, use ‘svd’ or ‘eigh’.
- Returns:
A random array with the specified dtype and shape given by
shape + mean.shape[-1:]
ifshape
is not None, or elsebroadcast_shapes(mean.shape[:-1], cov.shape[:-2]) + mean.shape[-1:]
.
- scico.random.normal(*args, key=None, seed=None, **kwargs)¶
Sample standard normal random values with given shape and float dtype.
Wrapped version of jax.random.normal. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are returned according to the probability density function:
\[f(x) = \frac{1}{\sqrt{2\pi}}e^{-x^2/2}\]on the domain \(-\infty < x < \infty\)
- Parameters:
key – a PRNG key used as the random key.
shape – optional, a tuple of nonnegative integers representing the result shape. Default ().
dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified shape and dtype.
- scico.random.orthogonal(*args, key=None, seed=None, **kwargs)¶
Sample uniformly from the orthogonal group O(n).
Wrapped version of jax.random.orthogonal. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
If the dtype is complex, sample uniformly from the unitary group U(n).
- Parameters:
key – a PRNG key used as the random key.
n – an integer indicating the resulting dimension.
shape – optional, the batch dimensions of the result. Default ().
dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array of shape (*shape, n, n) and specified dtype.
- scico.random.pareto(*args, key=None, seed=None, **kwargs)¶
Sample Pareto random values with given shape and float dtype.
Wrapped version of jax.random.pareto. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x; b) = b / x^{b + 1}\]on the domain \(1 \le x < \infty\) with \(b > 0\)
- Parameters:
key – a PRNG key used as the random key.
b – a float or array of floats broadcast-compatible with
shape
representing the parameter of the distribution.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
b
. The default (None) produces a result shape equal tob.shape
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and with shape given by
shape
ifshape
is not None, or else byb.shape
.
- scico.random.poisson(*args, key=None, seed=None, **kwargs)¶
Sample Poisson random values with given shape and integer dtype.
Wrapped version of jax.random.poisson. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability mass function:
\[f(k; \lambda) = \frac{\lambda^k e^{-\lambda}}{k!}\]Where k is a non-negative integer and \(\lambda > 0\).
- Parameters:
key – a PRNG key used as the random key.
lam – rate parameter (mean of the distribution), must be >= 0. Must be broadcast-compatible with
shape
shape – optional, a tuple of nonnegative integers representing the result shape. Default (None) produces a result shape equal to
lam.shape
.dtype – optional, a integer dtype for the returned values (default int64 if jax_enable_x64 is true, otherwise int32).
- Returns:
A random array with the specified dtype and with shape given by
shape
ifshape is not None, or else by ``lam.shape
.
- scico.random.rademacher(*args, key=None, seed=None, **kwargs)¶
Sample from a Rademacher distribution.
Wrapped version of jax.random.rademacher. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability mass function:
\[f(k) = \frac{1}{2}(\delta(k - 1) + \delta(k + 1))\]on the domain \(k \in \{-1, 1}\), where delta(x) is the dirac delta function.
- Parameters:
key – a PRNG key.
shape – The shape of the returned samples.
dtype – The type used for samples.
- Returns:
A jnp.array of samples, of shape shape. Each element in the output has a 50% change of being 1 or -1.
- scico.random.randint(*args, key=None, seed=None, **kwargs)¶
Sample uniform random values in [minval, maxval) with given shape/dtype.
Wrapped version of jax.random.randint. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
- Parameters:
key – a PRNG key used as the random key.
shape – a tuple of nonnegative integers representing the shape.
minval – int or array of ints broadcast-compatible with
shape
, a minimum (inclusive) value for the range.maxval – int or array of ints broadcast-compatible with
shape
, a maximum (exclusive) value for the range.dtype – optional, an int dtype for the returned values (default int64 if jax_enable_x64 is true, otherwise int32).
- Returns:
A random array with the specified shape and dtype.
- scico.random.rayleigh(*args, key=None, seed=None, **kwargs)¶
Sample Rayleigh random values with given shape and float dtype.
Wrapped version of jax.random.rayleigh. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are returned according to the probability density function:
\[f(x;\sigma) \propto xe^{-x^2/(2\sigma^2)}\]on the domain \(-\infty < x < \infty\), and where sigma > 0 is the scale parameter of the distribution.
- Parameters:
key – a PRNG key used as the random key.
scale – a float or array of floats broadcast-compatible with
shape
representing the parameter of the distribution.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
scale
. The default (None) produces a result shape equal toscale.shape
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and with shape given by
shape
ifshape
is not None, or else byscale.shape
.
- scico.random.t(*args, key=None, seed=None, **kwargs)¶
Sample Student’s t random values with given shape and float dtype.
Wrapped version of jax.random.t. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(t; \nu) \propto \left(1 + \frac{t^2}{\nu}\right)^{-(\nu + 1)/2}\]Where \(\nu > 0\) is the degrees of freedom, given by the parameter
df
.- Parameters:
key – a PRNG key used as the random key.
df – a float or array of floats broadcast-compatible with
shape
representing the degrees of freedom parameter of the distribution.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
df
. The default (None) produces a result shape equal todf.shape
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and with shape given by
shape
ifshape
is not None, or else bydf.shape
.
- scico.random.triangular(*args, key=None, seed=None, **kwargs)¶
Sample Triangular random values with given shape and float dtype.
Wrapped version of jax.random.triangular. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are returned according to the probability density function:
\[\begin{split}f(x; a, b, c) = \frac{2}{c-a} \left\{ \begin{array}{ll} \frac{x-a}{b-a} & a \leq x \leq b \\ \frac{c-x}{c-b} & b \leq x \leq c \end{array} \right.\end{split}\]on the domain \(a \leq x \leq c\).
- Parameters:
key – a PRNG key used as the random key.
left – a float or array of floats broadcast-compatible with
shape
representing the lower limit parameter of the distribution.mode – a float or array of floats broadcast-compatible with
shape
representing the peak value parameter of the distribution, value must fulfill the conditionleft <= mode <= right
.right – a float or array of floats broadcast-compatible with
shape
representing the upper limit parameter of the distribution, must be larger thanleft
.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
left
,``mode`` andright
. The default (None) produces a result shape equal toleft.shape
,mode.shape
andright.shape
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and with shape given by
shape
ifshape
is not None, or else byleft.shape
,mode.shape
andright.shape
.
- scico.random.truncated_normal(*args, key=None, seed=None, **kwargs)¶
Sample truncated standard normal random values with given shape and dtype.
Wrapped version of jax.random.truncated_normal. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are returned according to the probability density function:
\[f(x) \propto e^{-x^2/2}\]on the domain \(\rm{lower} < x < \rm{upper}\).
- Parameters:
key – a PRNG key used as the random key.
lower – a float or array of floats representing the lower bound for truncation. Must be broadcast-compatible with
upper
.upper – a float or array of floats representing the upper bound for truncation. Must be broadcast-compatible with
lower
.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
lower
andupper
. The default (None) produces a result shape by broadcastinglower
andupper
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and shape given by
shape
ifshape
is not None, or else by broadcastinglower
andupper
. Returns values in the open interval(lower, upper)
.
- scico.random.uniform(*args, key=None, seed=None, **kwargs)¶
Sample uniform random values in [minval, maxval) with given shape/dtype.
Wrapped version of jax.random.uniform. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
- Parameters:
key – a PRNG key used as the random key.
shape – optional, a tuple of nonnegative integers representing the result shape. Default ().
dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
minval – optional, a minimum (inclusive) value broadcast-compatible with shape for the range (default 0).
maxval – optional, a maximum (exclusive) value broadcast-compatible with shape for the range (default 1).
- Returns:
A random array with the specified shape and dtype.
- scico.random.wald(*args, key=None, seed=None, **kwargs)¶
Sample Wald random values with given shape and float dtype.
Wrapped version of jax.random.wald. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are returned according to the probability density function:
\[f(x;\mu) = \frac{1}{\sqrt{2\pi x^3}} \exp\left(-\frac{(x - \mu)^2}{2\mu^2 x}\right)\]on the domain \(-\infty < x < \infty\), and where \(\mu > 0\) is the location parameter of the distribution.
- Parameters:
key – a PRNG key used as the random key.
mean – a float or array of floats broadcast-compatible with
shape
representing the mean parameter of the distribution.shape – optional, a tuple of nonnegative integers specifying the result shape. Must be broadcast-compatible with
mean
. The default (None) produces a result shape equal tonp.shape(mean)
.dtype – optional, a float dtype for the returned values (default float64 if jax_enable_x64 is true, otherwise float32).
- Returns:
A random array with the specified dtype and with shape given by
shape
ifshape
is not None, or else bymean.shape
.
- scico.random.weibull_min(*args, key=None, seed=None, **kwargs)¶
Sample from a Weibull distribution.
Wrapped version of jax.random.weibull_min. The SCICO version of this function moves the key argument to the end of the argument list, adds an additional seed argument after that, and allows the shape argument to accept a nested list, in which case a BlockArray is returned. Always returns a (result, key) tuple. Original docstring below.
The values are distributed according to the probability density function:
\[f(x;\sigma,c) \propto x^{c - 1} \exp(-(x / \sigma)^c)\]on the domain \(0 < x < \infty\), where \(c > 0\) is the concentration parameter, and \(\sigma > 0\) is the scale parameter.
- Parameters:
key – a PRNG key.
scale – The scale parameter of the distribution.
concentration – The concentration parameter of the distribution.
shape – The shape added to the parameters loc and scale broadcastable shape.
dtype – The type used for samples.
- Returns:
A jnp.array of samples.