Skip to content

Commit

Permalink
Return value docs for nd.random.* and sym.random.* (apache#13994)
Browse files Browse the repository at this point in the history 
* mx.random.multinomial python documentation updated, return type details added

* multinomial documentation clarified

* added basic case for negative_binomial

* added basic case for generalized_negative_binomial

* basic case added for gamma

* added basic case for exponential

* basic case added for randn

* remaining base cases added.

* randint case added

* cleaned up return types for random.py

* zboldyga added to contributors

* spacing typo correction

* updated symbol.random return types, minor correction to ndarray.random return types

* removed trailing whitespace in docs
  • Loading branch information
@zboldyga @stephenrawls
zboldyga authored and stephenrawls committed Feb 16, 2019
1 parent d84d6cc commit bf77635
Show file tree
Hide file tree
Showing 3 changed files with 173 additions and 0 deletions.
1 change: 1 addition & 0 deletions CONTRIBUTORS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,7 @@ List of Contributors
* [Harsh Patel](https://github.com/harshp8l)
* [Xiao Wang](https://github.com/BeyonderXX)
* [Piyush Ghai](https://github.com/piyushghai)
* [Zach Boldyga](https://github.com/zboldyga)

Label Bot
---------
Expand Down
87 changes: 87 additions & 0 deletions python/mxnet/ndarray/random.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,14 @@ def uniform(low=0, high=1, shape=_Null, dtype=_Null, ctx=None, out=None, **kwarg
out : NDArray, optional
Store output to an existing NDArray.
Returns
-------
NDArray
An NDArray of type `dtype`. If input `shape` has shape, e.g.,
`(m, n)` and `low` and `high` are scalars, output shape will be `(m, n)`.
If `low` and `high` are NDArrays with shape, e.g., `(x, y)`, then the
return NDArray will have shape `(x, y, m, n)`, where `m*n` uniformly distributed
samples are drawn for each `[low, high)` pair.
Examples
--------
Expand Down Expand Up @@ -128,6 +136,13 @@ def normal(loc=0, scale=1, shape=_Null, dtype=_Null, ctx=None, out=None, **kwarg
out : NDArray, optional
Store output to an existing NDArray.
Returns
-------
NDArray
An NDArray of type `dtype`. If input `shape` has shape, e.g., `(m, n)` and
`loc` and `scale` are scalars, output shape will be `(m, n)`. If `loc` and
`scale` are NDArrays with shape, e.g., `(x, y)`, then output will have shape
`(x, y, m, n)`, where `m*n` samples are drawn for each `[loc, scale)` pair.
Examples
--------
Expand Down Expand Up @@ -178,6 +193,13 @@ def randn(*shape, **kwargs):
out : NDArray
Store output to an existing NDArray.
Returns
-------
NDArray
If input `shape` has shape, e.g., `(m, n)` and `loc` and `scale` are scalars, output
shape will be `(m, n)`. If `loc` and `scale` are NDArrays with shape, e.g., `(x, y)`,
then output will have shape `(x, y, m, n)`, where `m*n` samples are drawn for
each `[loc, scale)` pair.
Examples
--------
Expand Down Expand Up @@ -227,6 +249,13 @@ def poisson(lam=1, shape=_Null, dtype=_Null, ctx=None, out=None, **kwargs):
out : NDArray, optional
Store output to an existing NDArray.
Returns
-------
NDArray
If input `shape` has shape, e.g., `(m, n)` and `lam` is
a scalar, output shape will be `(m, n)`. If `lam`
is an NDArray with shape, e.g., `(x, y)`, then output will have shape
`(x, y, m, n)`, where `m*n` samples are drawn for each entry in `lam`.
Examples
--------
Expand Down Expand Up @@ -274,6 +303,12 @@ def exponential(scale=1, shape=_Null, dtype=_Null, ctx=None, out=None, **kwargs)
out : NDArray, optional
Store output to an existing NDArray.
Returns
-------
NDArray
If input `shape` has shape, e.g., `(m, n)` and `scale` is a scalar, output shape will
be `(m, n)`. If `scale` is an NDArray with shape, e.g., `(x, y)`, then `output`
will have shape `(x, y, m, n)`, where `m*n` samples are drawn for each entry in scale.
Examples
--------
Expand Down Expand Up @@ -320,6 +355,13 @@ def gamma(alpha=1, beta=1, shape=_Null, dtype=_Null, ctx=None, out=None, **kwarg
out : NDArray, optional
Store output to an existing NDArray.
Returns
-------
NDArray
If input `shape` has shape, e.g., `(m, n)` and `alpha` and `beta` are scalars, output
shape will be `(m, n)`. If `alpha` and `beta` are NDArrays with shape, e.g.,
`(x, y)`, then output will have shape `(x, y, m, n)`, where `m*n` samples are
drawn for each `[alpha, beta)` pair.
Examples
--------
Expand Down Expand Up @@ -369,6 +411,12 @@ def negative_binomial(k=1, p=1, shape=_Null, dtype=_Null, ctx=None,
out : NDArray, optional
Store output to an existing NDArray.
Returns
-------
NDArray
If input `shape` has shape, e.g., `(m, n)` and `k` and `p` are scalars, output shape
will be `(m, n)`. If `k` and `p` are NDArrays with shape, e.g., `(x, y)`, then
output will have shape `(x, y, m, n)`, where `m*n` samples are drawn for each `[k, p)` pair.
Examples
--------
Expand Down Expand Up @@ -420,6 +468,13 @@ def generalized_negative_binomial(mu=1, alpha=1, shape=_Null, dtype=_Null, ctx=N
out : NDArray, optional
Store output to an existing NDArray.
Returns
-------
NDArray
If input `shape` has shape, e.g., `(m, n)` and `mu` and `alpha` are scalars, output
shape will be `(m, n)`. If `mu` and `alpha` are NDArrays with shape, e.g., `(x, y)`,
then output will have shape `(x, y, m, n)`, where `m*n` samples are drawn for
each `[mu, alpha)` pair.
Examples
--------
Expand Down Expand Up @@ -469,8 +524,27 @@ def multinomial(data, shape=_Null, get_prob=False, out=None, dtype='int32', **kw
Data type of the sample output array. The default is int32.
Note that the data type of the log likelihood array is the same with that of `data`.
Returns
-------
List, or NDArray
For input `data` with `n` dimensions and shape `(d1, d2, ..., dn-1, k)`, and input
`shape` with shape `(s1, s2, ..., sx)`, returns an NDArray with shape
`(d1, d2, ... dn-1, s1, s2, ..., sx)`. The `s1, s2, ... sx` dimensions of the
returned NDArray consist of 0-indexed values sampled from each respective multinomial
distribution provided in the `k` dimension of `data`.
For the case `n`=1, and `x`=1 (one shape dimension), returned NDArray has shape `(s1,)`.
If `get_prob` is set to True, this function returns a list of format:
`[ndarray_output, log_likelihood_output]`, where `log_likelihood_output` is an NDArray of the
same shape as the sampled outputs.
Examples
--------
>>> probs = mx.nd.array([0, 0.1, 0.2, 0.3, 0.4])
>>> mx.nd.random.multinomial(probs)
[3]
<NDArray 1 @cpu(0)>
>>> probs = mx.nd.array([[0, 0.1, 0.2, 0.3, 0.4], [0.4, 0.3, 0.2, 0.1, 0]])
>>> mx.nd.random.multinomial(probs)
[3 1]
Expand Down Expand Up @@ -503,6 +577,13 @@ def shuffle(data, **kwargs):
out : NDArray, optional
Array to store the result.
Returns
-------
NDArray
A new NDArray with the same shape and type as input `data`, but
with items in the first axis of the returned NDArray shuffled randomly.
The original input `data` is not modified.
Examples
--------
>>> data = mx.nd.array([[0, 1, 2], [3, 4, 5], [6, 7, 8]])
Expand Down Expand Up @@ -545,6 +626,12 @@ def randint(low, high, shape=_Null, dtype=_Null, ctx=None, out=None, **kwargs):
out : NDArray, optional
Store output to an existing NDArray.
Returns
-------
NDArray
An NDArray of type `dtype`. If input `shape` has shape, e.g.,
`(m, n)`, the returned NDArray will shape will be `(m, n)`. Contents
of the returned NDArray will be samples from the interval `[low, high)`.
Examples
--------
Expand Down
85 changes: 85 additions & 0 deletions python/mxnet/symbol/random.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,14 @@ def uniform(low=0, high=1, shape=_Null, dtype=_Null, **kwargs):
`(x, y, m, n)`, where `m*n` samples are drawn for each `[low, high)` pair.
dtype : {'float16', 'float32', 'float64'}, optional
Data type of output samples. Default is 'float32'
Returns
-------
Symbol
If input `shape` has dimensions, e.g., `(m, n)`, and `low` and `high` are
scalars, returned Symbol will resolve to shape `(m, n)`. If `low` and `high`
are Symbols with shape, e.g., `(x, y)`, returned Symbol will have shape
`(x, y, m, n)`, where `m*n` samples are drawn for each `[low, high)` pair.
"""
return _random_helper(_internal._random_uniform, _internal._sample_uniform,
[low, high], shape, dtype, kwargs)
Expand All @@ -91,6 +99,15 @@ def normal(loc=0, scale=1, shape=_Null, dtype=_Null, **kwargs):
`(x, y, m, n)`, where `m*n` samples are drawn for each `[loc, scale)` pair.
dtype : {'float16', 'float32', 'float64'}, optional
Data type of output samples. Default is 'float32'
Returns
-------
Symbol
If input `shape` has dimensions, e.g., `(m, n)`, and `loc` and
`scale` are scalars, returned Symbol will resolve to shape `(m, n)`.
If `loc` and `scale` are Symbols with shape, e.g., `(x, y)`, returned
Symbol will resolve to shape `(x, y, m, n)`, where `m*n` samples are drawn
for each `[loc, scale)` pair.
"""
return _random_helper(_internal._random_normal, _internal._sample_normal,
[loc, scale], shape, dtype, kwargs)
Expand All @@ -113,6 +130,14 @@ def poisson(lam=1, shape=_Null, dtype=_Null, **kwargs):
`(x, y, m, n)`, where `m*n` samples are drawn for each entry in `lam`.
dtype : {'float16', 'float32', 'float64'}, optional
Data type of output samples. Default is 'float32'
Returns
-------
Symbol
If input `shape` has dimensions, e.g., `(m, n)`, and `lam` is
a scalar, output shape will be `(m, n)`. If `lam`
is an Symbol with shape, e.g., `(x, y)`, then output will have shape
`(x, y, m, n)`, where `m*n` samples are drawn for each entry in `lam`.
"""
return _random_helper(_internal._random_poisson, _internal._sample_poisson,
[lam], shape, dtype, kwargs)
Expand All @@ -139,6 +164,14 @@ def exponential(scale=1, shape=_Null, dtype=_Null, **kwargs):
`(x, y, m, n)`, where `m*n` samples are drawn for each entry in `scale`.
dtype : {'float16', 'float32', 'float64'}, optional
Data type of output samples. Default is 'float32'
Returns
-------
Symbol
If input `shape` has dimensions, e.g., `(m, n)`, and `scale` is
a scalar, returned Symbol will have shape `(m, n)`. If `scale`
is a Symbol with shape, e.g., `(x, y)`, returned Symbol will resolve to
shape `(x, y, m, n)`, where `m*n` samples are drawn for each entry in `scale`.
"""
return _random_helper(_internal._random_exponential, _internal._sample_exponential,
[1.0/scale], shape, dtype, kwargs)
Expand All @@ -164,6 +197,14 @@ def gamma(alpha=1, beta=1, shape=_Null, dtype=_Null, **kwargs):
`(x, y, m, n)`, where `m*n` samples are drawn for each `[alpha, beta)` pair.
dtype : {'float16', 'float32', 'float64'}, optional
Data type of output samples. Default is 'float32'
Returns
-------
Symbol
If input `shape` has dimensions, e.g., `(m, n)` and `alpha` and
`beta` are scalars, returned Symbol will resolve to shape `(m, n)`. If `alpha`
and `beta` are Symbols with shape, e.g., `(x, y)`, returned Symbol will resolve
to shape `(x, y, m, n)`, where `m*n` samples are drawn for each `[alpha, beta)` pair.
"""
return _random_helper(_internal._random_gamma, _internal._sample_gamma,
[alpha, beta], shape, dtype, kwargs)
Expand All @@ -190,6 +231,14 @@ def negative_binomial(k=1, p=1, shape=_Null, dtype=_Null, **kwargs):
`(x, y, m, n)`, where `m*n` samples are drawn for each `[k, p)` pair.
dtype : {'float16', 'float32', 'float64'}, optional
Data type of output samples. Default is 'float32'
Returns
-------
Symbol
If input `shape` has dimensions, e.g., `(m, n)`, and `k` and
`p` are scalars, returned Symbol will resolve to shape `(m, n)`. If `k`
and `p` are Symbols with shape, e.g., `(x, y)`, returned Symbol will resolve
to shape `(x, y, m, n)`, where `m*n` samples are drawn for each `[k, p)` pair.
"""
return _random_helper(_internal._random_negative_binomial,
_internal._sample_negative_binomial,
Expand Down Expand Up @@ -218,6 +267,14 @@ def generalized_negative_binomial(mu=1, alpha=1, shape=_Null, dtype=_Null, **kwa
`(x, y, m, n)`, where `m*n` samples are drawn for each `[mu, alpha)` pair.
dtype : {'float16', 'float32', 'float64'}, optional
Data type of output samples. Default is 'float32'
Returns
-------
Symbol
If input `shape` has dimensions, e.g., `(m, n)`, and `mu` and
`alpha` are scalars, returned Symbol will resolve to shape `(m, n)`. If `mu`
and `alpha` are Symbols with shape, e.g., `(x, y)`, returned Symbol will resolve
to shape `(x, y, m, n)`, where `m*n` samples are drawn for each `[mu, alpha)` pair.
"""
return _random_helper(_internal._random_generalized_negative_binomial,
_internal._sample_generalized_negative_binomial,
Expand Down Expand Up @@ -248,6 +305,22 @@ def multinomial(data, shape=_Null, get_prob=True, dtype='int32', **kwargs):
dtype : str or numpy.dtype, optional
Data type of the sample output array. The default is int32.
Note that the data type of the log likelihood array is the same with that of `data`.
Returns
-------
Symbol
For input `data` with `n` dimensions and shape `(d1, d2, ..., dn-1, k)`, and input
`shape` with shape `(s1, s2, ..., sx)`, returns a Symbol that resovles to shape
`(d1, d2, ... dn-1, s1, s2, ..., sx)`. The `s1, s2, ... sx` dimensions of the
returned Symbol's resolved value will consist of 0-indexed values sampled from each
respective multinomial distribution provided in the `k` dimension of `data`.
For the case `n`=1, and `x`=1 (one shape dimension), returned Symbol will resolve to
shape `(s1,)`.
If `get_prob` is set to True, this function returns a Symbol that will resolve to a list of
outputs: `[ndarray_output, log_likelihood_output]`, where `log_likelihood_output` will resolve
to the same shape as the sampled outputs in ndarray_output.
"""
return _internal._sample_multinomial(data, shape, get_prob, dtype=dtype, **kwargs)

Expand All @@ -264,6 +337,12 @@ def shuffle(data, **kwargs):
----------
data : NDArray
Input data array.
Returns
-------
Symbol
A new symbol representing the shuffled version of input `data`.
Examples
--------
>>> data = mx.nd.array([[0, 1, 2], [3, 4, 5], [6, 7, 8]])
Expand Down Expand Up @@ -302,6 +381,12 @@ def randint(low, high, shape=_Null, dtype=_Null, **kwargs):
`high` are scalars, output shape will be `(m, n)`.
dtype : {'int32', 'int64'}, optional
Data type of output samples. Default is 'int32'
Returns
-------
Symbol
If input `shape` has dimensions, e.g., `(m, n)`, and `low` and
`high` are scalars, returned Symbol will resolve to shape `(m, n)`.
"""
return _random_helper(_internal._random_randint, None,
[low, high], shape, dtype, kwargs)

0 comments on commit bf77635

Please sign in to comment.