From 225aa402c0a040c6ce6c39a1865c0648aaf8a07d Mon Sep 17 00:00:00 2001 From: Zach Boldyga Date: Tue, 29 Jan 2019 17:54:57 -0800 Subject: [PATCH] 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 5b5fdce712f1..6bf44c55de6d 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 78339a020862..f19c1e03202f 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] + >>> 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 34663cddf02c..4bdfe7045625 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)