This is an automated email from the ASF dual-hosted git repository.
zhasheng pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-mxnet.git
The following commit(s) were added to refs/heads/master by this push:
new e37ff53 Return value docs for nd.random.* and sym.random.* (#13994)
e37ff53 is described below
commit e37ff53f0a3a0cc9276a7a1d4aff0deab91c40df
Author: Zach Boldyga <[email protected]>
AuthorDate: Tue Jan 29 17:54:57 2019 -0800
Return value docs for nd.random.* and sym.random.* (#13994)
* 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
---
CONTRIBUTORS.md | 1 +
python/mxnet/ndarray/random.py | 87 ++++++++++++++++++++++++++++++++++++++++++
python/mxnet/symbol/random.py | 85 +++++++++++++++++++++++++++++++++++++++++
3 files changed, 173 insertions(+)
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index 5b5fdce..6bf44c5 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -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
---------
diff --git a/python/mxnet/ndarray/random.py b/python/mxnet/ndarray/random.py
index 78339a0..f19c1e0 100644
--- a/python/mxnet/ndarray/random.py
+++ b/python/mxnet/ndarray/random.py
@@ -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
--------
@@ -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
--------
@@ -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
--------
@@ -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
--------
@@ -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
--------
@@ -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
--------
@@ -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
--------
@@ -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
--------
@@ -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]
@@ -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]])
@@ -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
--------
diff --git a/python/mxnet/symbol/random.py b/python/mxnet/symbol/random.py
index 34663cd..4bdfe70 100644
--- a/python/mxnet/symbol/random.py
+++ b/python/mxnet/symbol/random.py
@@ -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)
@@ -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)
@@ -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)
@@ -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)
@@ -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)
@@ -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,
@@ -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,
@@ -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)
@@ -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]])
@@ -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)
