Skip to content

P
pytensor
提交 3ff5c1bf authored 作者: Iban Harlouchet's avatar Iban Harlouchet
浏览文件
操作

numpydoc for raw_random.py

上级 b8856a5e
隐藏空白字符变更
内嵌 并排
正在显示 包含 153 行增加 和 108 行删除
theano/tensor/raw_random.py
浏览文件 @ 3ff5c1bf
......@@ -19,7 +19,8 @@ __docformat__ = "restructuredtext en"
class RandomStateType(gof.Type):
"""A Type wrapper for numpy.random.RandomState
"""
A Type wrapper for numpy.random.RandomState.
The reason this exists (and `Generic` doesn't suffice) is that
RandomState objects that would appear to be equal do not compare
......@@ -99,35 +100,36 @@ random_state_type = RandomStateType()
class RandomFunction(gof.Op):
"""Op that draws random numbers from a numpy.random.RandomState object
"""
__props__ = ("fn", "outtype", "inplace", "ndim_added")
Op that draws random numbers from a numpy.random.RandomState object.
def __init__(self, fn, outtype, inplace=False, ndim_added=0):
"""
:param fn: a member function of numpy.random.RandomState
Parameters
----------
fn : string or function reference
A member function of numpy.random.RandomState. A string will
be interpreted as the name of a member function of
numpy.random.RandomState.
Technically, any function with a signature like the ones in
numpy.random.RandomState will do. This function must accept
numpy.random.RandomState will do. This function must accept
the shape (sometimes called size) of the output as the last
positional argument.
outtype
The theano Type of the output.
args
A list of default arguments for the function
kwargs
If the 'inplace' key is there, its value will be used to
determine if the op operates inplace or not.
If the 'ndim_added' key is there, its value indicates how
many more dimensions this op will add to the output, in
addition to the shape's dimensions (used in multinomial and
permutation).
:type fn: string or function reference. A string will
be interpreted as the name of a member function of
numpy.random.RandomState.
:param outtype: the theano Type of the output
"""
:param args: a list of default arguments for the function
__props__ = ("fn", "outtype", "inplace", "ndim_added")
:param kwargs:
If the 'inplace' key is there, its value will be used to
determine if the op operates inplace or not.
If the 'ndim_added' key is there, its value indicates how
many more dimensions this op will add to the output, in
addition to the shape's dimensions (used in multinomial and
permutation).
"""
def __init__(self, fn, outtype, inplace=False, ndim_added=0):
self.__setstate__([fn, outtype, inplace, ndim_added])
def __getstate__(self):
......@@ -151,30 +153,33 @@ class RandomFunction(gof.Op):
def make_node(self, r, shape, *args):
"""
:param r: a numpy.random.RandomState instance, or a Variable of Type
RandomStateType that will contain a RandomState instance.
:param shape: an lvector with a shape defining how many samples
to draw. In the case of scalar distributions, it is the shape
of the tensor output by this Op. In that case, at runtime, the
value associated with this lvector must have a length equal to
the number of dimensions promised by `self.outtype`.
In a more general case, the number of output dimensions,
len(self.outtype), is equal to len(shape)+self.ndim_added.
The special case where len(shape) == 0 means that the smallest
shape compatible with the argument's shape will be used.
:param args: the values associated with these variables will
be passed to the RandomState function during perform as extra
"*args"-style arguments. These should be castable to variables
of Type TensorType.
:rtype: Apply
:return: Apply with two outputs. The first output is a
gof.generic Variable from which to draw further random numbers.
The second output is the outtype() instance holding the random
draw.
Parameters
----------
r
A numpy.random.RandomState instance, or a Variable of Type
RandomStateType that will contain a RandomState instance.
shape
An lvector with a shape defining how many samples
to draw. In the case of scalar distributions, it is the shape
of the tensor output by this Op. In that case, at runtime, the
value associated with this lvector must have a length equal to
the number of dimensions promised by `self.outtype`.
In a more general case, the number of output dimensions,
len(self.outtype), is equal to len(shape)+self.ndim_added.
The special case where len(shape) == 0 means that the smallest
shape compatible with the argument's shape will be used.
args
The values associated with these variables will be passed to the
RandomState function during perform as extra "*args"-style
arguments. These should be castable to variables of Type TensorType.
Returns
-------
Apply
Apply with two outputs. The first output is a gof.generic Variable
from which to draw further random numbers.
The second output is the outtype() instance holding the random
draw.
"""
shape_ = tensor.as_tensor_variable(shape, ndim=1)
......@@ -289,12 +294,15 @@ def _infer_ndim_bcast(ndim, shape, *args):
"""
Infer the number of dimensions from the shape or the other arguments.
:rtype: (int, variable, tuple) triple, where the variable is an integer
vector, and the tuple contains Booleans.
:returns: the first element returned is the inferred number of dimensions.
The second element is the shape inferred (combining symbolic and constant
informations from shape and args).
The third element is a broadcasting pattern corresponding to that shape.
Returns
-------
(int, variable, tuple) triple, where the variable is an integer vector,
and the tuple contains Booleans
The first element returned is the inferred number of dimensions.
The second element is the shape inferred (combining symbolic and
constant informations from shape and args).
The third element is a broadcasting pattern corresponding to that shape.
"""
# Find the minimum value of ndim required by the *args
......@@ -390,7 +398,7 @@ def _infer_ndim_bcast(ndim, shape, *args):
def _generate_broadcasting_indices(out_shape, *shapes):
'''
"""
Return indices over each shape that broadcast them to match out_shape.
The first returned list is equivalent to numpy.ndindex(out_shape),
......@@ -400,7 +408,8 @@ def _generate_broadcasting_indices(out_shape, *shapes):
The shapes should have the same length as out_shape. If they are longer,
the right-most dimensions are ignored.
'''
"""
all_shapes = (out_shape,) + shapes
# Will contain the return value: a list of indices for each argument
ret_indices = [[()] for shape in all_shapes]
......@@ -447,6 +456,7 @@ def uniform(random_state, size=None, low=0.0, high=1.0, ndim=None, dtype=None):
If dtype is not specified, it will be inferred from the dtype of
low and high, but will be at least as precise as floatX.
"""
low = tensor.as_tensor_variable(low)
high = tensor.as_tensor_variable(high)
......@@ -471,6 +481,7 @@ def normal(random_state, size=None, avg=0.0, std=1.0, ndim=None, dtype=None):
If dtype is not specified, it will be inferred from the dtype of
avg and std, but will be at least as precise as floatX.
"""
avg = tensor.as_tensor_variable(avg)
std = tensor.as_tensor_variable(std)
......@@ -493,6 +504,7 @@ def binomial(random_state, size=None, n=1, p=0.5, ndim=None,
If size is None, the output shape will be determined by the shapes
of n and prob.
"""
if prob is not None:
p = prob
......@@ -514,12 +526,13 @@ def binomial(random_state, size=None, n=1, p=0.5, ndim=None,
def random_integers_helper(random_state, low, high, size):
'''
"""
Helper function to draw random integers.
This is a generalization of numpy.random.random_integers to the case where
low and high are tensors.
'''
"""
# Figure out the output shape
if size is not None:
out_ndim = len(size)
......@@ -570,6 +583,7 @@ def random_integers(random_state, size=None, low=0, high=1, ndim=None,
If size is None, the output shape will be determined by the shapes
of low and high.
"""
low = tensor.as_tensor_variable(low)
high = tensor.as_tensor_variable(high)
......@@ -580,11 +594,13 @@ def random_integers(random_state, size=None, low=0, high=1, ndim=None,
def choice_helper(random_state, a, replace, p, size):
"""Helper function to draw random numbers using numpy's choice function.
"""
Helper function to draw random numbers using numpy's choice function.
This is a generalization of numpy.random.choice that coerces
`replace` to a bool and replaces `p` with None when p is a vector
of 0 elements.
"""
if a.ndim > 1:
raise ValueError('a.ndim (%i) must be 0 or 1' % a.ndim)
......@@ -608,6 +624,7 @@ def choice(random_state, size=None, a=2, replace=True, p=None, ndim=None,
may be a plain integer to supplement the missing information.
If size is None, a scalar will be returned.
"""
# numpy.random.choice is only available for numpy versions >= 1.7
major, minor, _ = numpy.version.short_version.split('.')
......@@ -631,17 +648,21 @@ def poisson(random_state, size=None, lam=1.0, ndim=None, dtype='int64'):
"""
Draw samples from a Poisson distribution.
The Poisson distribution is the limit of the Binomial distribution for large N.
The Poisson distribution is the limit of the Binomial distribution for
large N.
:param lam: float or ndarray-like of the same shape as size parameter
Parameters
----------
lam : float or ndarray-like of the same shape as size parameter
Expectation of interval, should be >= 0.
size: int or tuple of ints, optional
Output shape. If the given shape is, e.g., (m, n, k), then m * n * k
samples are drawn.
dtype
The dtype of the return value (which will represent counts).
:param size: int or tuple of ints, optional
Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn.
size or ndim must be given.
:param dtype: the dtype of the return value (which will represent counts)
size or ndim must be given
"""
lam = tensor.as_tensor_variable(lam)
......@@ -653,7 +674,8 @@ def poisson(random_state, size=None, lam=1.0, ndim=None, dtype='int64'):
def permutation_helper(random_state, n, shape):
"""Helper function to generate permutations from integers.
"""
Helper function to generate permutations from integers.
permutation_helper(random_state, n, (1,)) will generate a permutation of
integers 0..n-1.
......@@ -666,6 +688,7 @@ def permutation_helper(random_state, n, shape):
This is a generalization of numpy.random.permutation to tensors.
Otherwise it behaves the same.
"""
# n should be a 0-dimension array
assert n.shape == ()
......@@ -688,17 +711,20 @@ def permutation_helper(random_state, n, shape):
def permutation(random_state, size=None, n=1, ndim=None, dtype='int64'):
"""
Returns permutations of the integers between 0 and n-1, as many times
as required by size. For instance, if size=(p,q), p*q permutations
will be generated, and the output shape will be (p,q,n), because each
permutation is of size n.
Return permutations of the integers between 0 and n-1.
Returns them as many times as required by size. For instance, if size=(p,q),
p*q permutations will be generated, and the output shape will be (p,q,n),
because each permutation is of size n.
Theano tries to infer the number of dimensions from the length of
the size argument and the shape of n, but you may always specify it
with the `ndim` parameter.
:note:
Note that the output will then be of dimension ndim+1.
Notes
-----
Note that the output will then be of dimension ndim+1.
"""
if size is None or size == ():
if not(ndim is None or ndim == 1):
......@@ -718,12 +744,13 @@ def permutation(random_state, size=None, n=1, ndim=None, dtype='int64'):
def multinomial_helper(random_state, n, pvals, size):
'''
"""
Helper function drawing from multinomial distributions.
This is a generalization of numpy.random.multinomial to the case where
n and pvals are tensors.
'''
"""
# Figure out the shape if it's None
# Note: the output ndim will be ndim+1, because the multinomial
# adds a dimension. The length of that dimension is pvals.shape[-1].
......@@ -791,31 +818,39 @@ def multinomial_helper(random_state, n, pvals, size):
def multinomial(random_state, size=None, n=1, pvals=[0.5, 0.5],
ndim=None, dtype='int64'):
"""Sample from one or more multinomial distributions defined by
"""
Sample from one or more multinomial distributions defined by
one-dimensional slices in pvals.
:param pvals: a tensor of shape "nmulti+(L,)" describing each multinomial
Parameters
----------
pvals
A tensor of shape "nmulti+(L,)" describing each multinomial
distribution. This tensor must have the property that
numpy.allclose(pvals.sum(axis=-1), 1) is true.
:param size: a vector of shape information for the output; this can also
size
A vector of shape information for the output; this can also
specify the "nmulti" part of pvals' shape. A -1 in the k'th position
from the right means to borrow the k'th position from the
right in nmulti. (See examples below.)
Default ``None`` means size=nmulti.
:param n: the number of experiments to simulate for each
n
The number of experiments to simulate for each
multinomial. This can be a scalar, or tensor, it will be
broadcasted to have shape "nmulti".
dtype
The dtype of the return value (which will represent counts)
:param dtype: the dtype of the return value (which will represent counts)
:returns: tensor of len(size)+1 dimensions, and shape[-1]==L, with
the specified ``dtype``, with the experiment counts. See
Returns
-------
Tensor of len(size)+1 dimensions, and shape[-1]==L, with
the specified ``dtype``, with the experiment counts. See
examples to understand the shape of the return value, which is
derived from both size and pvals.shape. In return value rval,
derived from both size and pvals.shape. In return value rval,
"numpy.allclose(rval.sum(axis=-1), n)" will be true.
Extended Summary
----------------
For example, to simulate n experiments from each multinomial in a batch of
size B:
......@@ -881,8 +916,8 @@ class RandomStreamsBase(object):
return the number of successes.
If the size argument is ambiguous on the number of dimensions,
ndim may be a plain integer to supplement the missing
information.
ndim may be a plain integer to supplement the missing information.
"""
if prob is not None:
p = prob
......@@ -895,8 +930,8 @@ class RandomStreamsBase(object):
distribution between low and high.
If the size argument is ambiguous on the number of dimensions,
ndim may be a plain integer to supplement the missing
information.
ndim may be a plain integer to supplement the missing information.
"""
return self.gen(uniform, size, low, high, ndim=ndim, dtype=dtype)
......@@ -906,8 +941,8 @@ class RandomStreamsBase(object):
the specified standard deviation (std).
If the size argument is ambiguous on the number of dimensions,
ndim may be a plain integer to supplement the missing
information.
ndim may be a plain integer to supplement the missing information.
"""
return self.gen(normal, size, avg, std, ndim=ndim, dtype=dtype)
......@@ -917,8 +952,8 @@ class RandomStreamsBase(object):
Sample a random integer between low and high, both inclusive.
If the size argument is ambiguous on the number of dimensions,
ndim may be a plain integer to supplement the missing
information.
ndim may be a plain integer to supplement the missing information.
"""
return self.gen(random_integers, size, low, high, ndim=ndim,
dtype=dtype)
......@@ -926,13 +961,14 @@ class RandomStreamsBase(object):
def choice(self, size=None, a=2, replace=True, p=None, ndim=None,
dtype='int64'):
"""
Choose values from `a` with or without replacement. `a` can be a 1-D
array or a positive scalar. If `a` is a scalar, the samples are drawn
from the range 0,...,a-1.
Choose values from `a` with or without replacement.
`a` can be a 1-D array or a positive scalar.
If `a` is a scalar, the samples are drawn from the range 0,...,a-1.
If the size argument is ambiguous on the number of dimensions,
ndim may be a plain integer to supplement the missing
information.
ndim may be a plain integer to supplement the missing information.
"""
return self.gen(choice, size, a, replace, p, ndim=ndim, dtype=dtype)
......@@ -940,27 +976,32 @@ class RandomStreamsBase(object):
"""
Draw samples from a Poisson distribution.
The Poisson distribution is the limit of the Binomial distribution for large N.
The Poisson distribution is the limit of the Binomial distribution for
large N.
If the size argument is ambiguous on the number of dimensions,
ndim may be a plain integer to supplement the missing
information.
ndim may be a plain integer to supplement the missing information.
"""
return self.gen(poisson, size, lam, ndim=ndim, dtype=dtype)
def permutation(self, size=None, n=1, ndim=None, dtype='int64'):
"""
Returns permutations of the integers between 0 and n-1, as many times
as required by size. For instance, if size=(p,q), p*q permutations
will be generated, and the output shape will be (p,q,n), because each
Return permutations of the integers between 0 and n-1.
Returns them as many times as required by size. For instance,
if size=(p,q), p*q permutations will be generated,
and the output shape will be (p,q,n), because each
permutation is of size n.
Theano tries to infer the number of dimensions from the length
of the size argument and the shape of n, but you may always
specify it with the `ndim` parameter.
.. note::
Note that the output will then be of dimension ndim+1.
Notes
-----
Note that the output will then be of dimension ndim+1.
"""
return self.gen(permutation, size, n, ndim=ndim, dtype=dtype)
......@@ -976,16 +1017,20 @@ class RandomStreamsBase(object):
of the size argument and the shapes of n and pvals, but you may
always specify it with the `ndim` parameter.
.. note::
Note that the output will then be of dimension ndim+1.
Notes
-----
Note that the output will then be of dimension ndim+1.
"""
return self.gen(multinomial, size, n, pvals, ndim=ndim, dtype=dtype)
def shuffle_row_elements(self, input):
"""Return a variable with every row (rightmost index) shuffled.
"""
Return a variable with every row (rightmost index) shuffled.
This uses permutation random variable internally, available via
the ``.permutation`` attribute of the return value.
"""
perm = self.permutation(size=input.shape[:-1], n=input.shape[-1],
ndim=input.ndim - 1)
......
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑！
请 注册 或者 后发表评论