![]() |
Class GammaGamma
Gamma-Gamma distribution.
Inherits From: Distribution
Gamma-Gamma is a compound
distribution
defined over positive real numbers using parameters concentration
,
mixing_concentration
and mixing_rate
.
This distribution is also referred to as the beta of the second kind (B2), and can be useful for transaction value modeling, as [(Fader and Hardi, 2013)][1].
Mathematical Details
It is derived from the following Gamma-Gamma hierarchical model by integrating
out the random variable beta
.
beta ~ Gamma(alpha0, beta0)
X | beta ~ Gamma(alpha, beta)
where
* concentration = alpha
* mixing_concentration = alpha0
* mixing_rate = beta0
The probability density function (pdf) is
x**(alpha - 1)
pdf(x; alpha, alpha0, beta0) = ---------------------------------
Z * (x + beta0)**(alpha + alpha0)
where the normalizing constant Z = Beta(alpha, alpha0) * beta0**(-alpha0)
.
Samples of this distribution are reparameterized as samples of the Gamma distribution are reparameterized using the technique described in [(Figurnov et al., 2018)][2].
References
[1]: Peter S. Fader, Bruce G. S. Hardi. The Gamma-Gamma Model of Monetary Value. Technical Report, 2013. http://www.brucehardie.com/notes/025/gamma_gamma.pdf
[2]: Michael Figurnov, Shakir Mohamed, Andriy Mnih. Implicit Reparameterization Gradients. arXiv preprint arXiv:1805.08498, 2018. https://arxiv.org/abs/1805.08498
__init__
__init__(
concentration,
mixing_concentration,
mixing_rate,
validate_args=False,
allow_nan_stats=True,
name='GammaGamma'
)
Initializes a batch of Gamma-Gamma distributions.
The parameters concentration
and rate
must be shaped in a way that
supports broadcasting (e.g.
concentration + mixing_concentration + mixing_rate
is a valid operation).
Args:
concentration
: Floating point tensor, the concentration params of the distribution(s). Must contain only positive values.mixing_concentration
: Floating point tensor, the concentration params of the mixing Gamma distribution(s). Must contain only positive values.mixing_rate
: Floating point tensor, the rate params of the mixing Gamma distribution(s). Must contain only positive values.validate_args
: Pythonbool
, defaultFalse
. WhenTrue
distribution parameters are checked for validity despite possibly degrading runtime performance. WhenFalse
invalid inputs may silently render incorrect outputs.allow_nan_stats
: Pythonbool
, defaultTrue
. WhenTrue
, statistics (e.g., mean, mode, variance) use the value "NaN
" to indicate the result is undefined. WhenFalse
, an exception is raised if one or more of the statistic's batch members are undefined.name
: Pythonstr
name prefixed to Ops created by this class.
Raises:
TypeError
: ifconcentration
andrate
are different dtypes.
Properties
allow_nan_stats
Python bool
describing behavior when a stat is undefined.
Stats return +/- infinity when it makes sense. E.g., the variance of a Cauchy distribution is infinity. However, sometimes the statistic is undefined, e.g., if a distribution's pdf does not achieve a maximum within the support of the distribution, the mode is undefined. If the mean is undefined, then by definition the variance is undefined. E.g. the mean for Student's T for df = 1 is undefined (no clear way to say it is either + or - infinity), so the variance = E[(X - mean)**2] is also undefined.
Returns:
allow_nan_stats
: Pythonbool
.
batch_shape
Shape of a single sample from a single event index as a TensorShape
.
May be partially defined or unknown.
The batch dimensions are indexes into independent, non-identical parameterizations of this distribution.
Returns:
batch_shape
:TensorShape
, possibly unknown.
concentration
Concentration parameter.
dtype
The DType
of Tensor
s handled by this Distribution
.
event_shape
Shape of a single sample from a single batch as a TensorShape
.
May be partially defined or unknown.
Returns:
event_shape
:TensorShape
, possibly unknown.
mixing_concentration
Concentration parameter for the mixing Gamma distribution.
mixing_rate
Rate parameter for the mixing Gamma distribution.
name
Name prepended to all ops created by this Distribution
.
name_scope
Returns a tf.name_scope
instance for this class.
parameters
Dictionary of parameters used to instantiate this Distribution
.
reparameterization_type
Describes how samples from the distribution are reparameterized.
Currently this is one of the static instances
tfd.FULLY_REPARAMETERIZED
or tfd.NOT_REPARAMETERIZED
.
Returns:
An instance of ReparameterizationType
.
submodules
Sequence of all sub-modules.
Submodules are modules which are properties of this module, or found as properties of modules which are properties of this module (and so on).
a = tf.Module()
b = tf.Module()
c = tf.Module()
a.b = b
b.c = c
assert list(a.submodules) == [b, c]
assert list(b.submodules) == [c]
assert list(c.submodules) == []
Returns:
A sequence of all submodules.
trainable_variables
Sequence of variables owned by this module and it's submodules.
Returns:
A sequence of variables for the current module (sorted by attribute name) followed by variables from all submodules recursively (breadth first).
validate_args
Python bool
indicating possibly expensive checks are enabled.
variables
Sequence of variables owned by this module and it's submodules.
Returns:
A sequence of variables for the current module (sorted by attribute name) followed by variables from all submodules recursively (breadth first).
Methods
__getitem__
__getitem__(slices)
Slices the batch axes of this distribution, returning a new instance.
b = tfd.Bernoulli(logits=tf.zeros([3, 5, 7, 9]))
b.batch_shape # => [3, 5, 7, 9]
b2 = b[:, tf.newaxis, ..., -2:, 1::2]
b2.batch_shape # => [3, 1, 5, 2, 4]
x = tf.random.normal([5, 3, 2, 2])
cov = tf.matmul(x, x, transpose_b=True)
chol = tf.cholesky(cov)
loc = tf.random.normal([4, 1, 3, 1])
mvn = tfd.MultivariateNormalTriL(loc, chol)
mvn.batch_shape # => [4, 5, 3]
mvn.event_shape # => [2]
mvn2 = mvn[:, 3:, ..., ::-1, tf.newaxis]
mvn2.batch_shape # => [4, 2, 3, 1]
mvn2.event_shape # => [2]
Args:
slices
: slices from the [] operator
Returns:
dist
: A newtfd.Distribution
instance with sliced parameters.
__iter__
__iter__()
batch_shape_tensor
batch_shape_tensor(name='batch_shape_tensor')
Shape of a single sample from a single event index as a 1-D Tensor
.
The batch dimensions are indexes into independent, non-identical parameterizations of this distribution.
Args:
name
: name to give to the op
Returns:
batch_shape
:Tensor
.
cdf
cdf(
value,
name='cdf',
**kwargs
)
Cumulative distribution function.
Given random variable X
, the cumulative distribution function cdf
is:
cdf(x) := P[X <= x]
Args:
value
:float
ordouble
Tensor
.name
: Pythonstr
prepended to names of ops created by this function.**kwargs
: Named arguments forwarded to subclass implementation.
Returns:
cdf
: aTensor
of shapesample_shape(x) + self.batch_shape
with values of typeself.dtype
.
copy
copy(**override_parameters_kwargs)
Creates a deep copy of the distribution.
Args:
**override_parameters_kwargs
: String/value dictionary of initialization arguments to override with new values.
Returns:
distribution
: A new instance oftype(self)
initialized from the union of self.parameters and override_parameters_kwargs, i.e.,dict(self.parameters, **override_parameters_kwargs)
.
covariance
covariance(
name='covariance',
**kwargs
)
Covariance.
Covariance is (possibly) defined only for non-scalar-event distributions.
For example, for a length-k
, vector-valued distribution, it is calculated
as,
Cov[i, j] = Covariance(X_i, X_j) = E[(X_i - E[X_i]) (X_j - E[X_j])]
where Cov
is a (batch of) k x k
matrix, 0 <= (i, j) < k
, and E
denotes expectation.
Alternatively, for non-vector, multivariate distributions (e.g.,
matrix-valued, Wishart), Covariance
shall return a (batch of) matrices
under some vectorization of the events, i.e.,
Cov[i, j] = Covariance(Vec(X)_i, Vec(X)_j) = [as above]
where Cov
is a (batch of) k' x k'
matrices,
0 <= (i, j) < k' = reduce_prod(event_shape)
, and Vec
is some function
mapping indices of this distribution's event dimensions to indices of a
length-k'
vector.
Args:
name
: Pythonstr
prepended to names of ops created by this function.**kwargs
: Named arguments forwarded to subclass implementation.
Returns:
covariance
: Floating-pointTensor
with shape[B1, ..., Bn, k', k']
where the firstn
dimensions are batch coordinates andk' = reduce_prod(self.event_shape)
.
cross_entropy
cross_entropy(
other,
name='cross_entropy'
)
Computes the (Shannon) cross entropy.
Denote this distribution (self
) by P
and the other
distribution by
Q
. Assuming P, Q
are absolutely continuous with respect to
one another and permit densities p(x) dr(x)
and q(x) dr(x)
, (Shannon)
cross entropy is defined as:
H[P, Q] = E_p[-log q(X)] = -int_F p(x) log q(x) dr(x)
where F
denotes the support of the random variable X ~ P
.
Args:
other
:tfp.distributions.Distribution
instance.name
: Pythonstr
prepended to names of ops created by this function.
Returns:
cross_entropy
:self.dtype
Tensor
with shape[B1, ..., Bn]
representingn
different calculations of (Shannon) cross entropy.
entropy
entropy(
name='entropy',
**kwargs
)
Shannon entropy in nats.
event_shape_tensor
event_shape_tensor(name='event_shape_tensor')
Shape of a single sample from a single batch as a 1-D int32 Tensor
.
Args:
name
: name to give to the op
Returns:
event_shape
:Tensor
.
is_scalar_batch
is_scalar_batch(name='is_scalar_batch')
Indicates that batch_shape == []
.
Args:
name
: Pythonstr
prepended to names of ops created by this function.
Returns:
is_scalar_batch
:bool
scalarTensor
.
is_scalar_event
is_scalar_event(name='is_scalar_event')
Indicates that event_shape == []
.
Args:
name
: Pythonstr
prepended to names of ops created by this function.
Returns:
is_scalar_event
:bool
scalarTensor
.
kl_divergence
kl_divergence(
other,
name='kl_divergence'
)
Computes the Kullback--Leibler divergence.
Denote this distribution (self
) by p
and the other
distribution by
q
. Assuming p, q
are absolutely continuous with respect to reference
measure r
, the KL divergence is defined as:
KL[p, q] = E_p[log(p(X)/q(X))]
= -int_F p(x) log q(x) dr(x) + int_F p(x) log p(x) dr(x)
= H[p, q] - H[p]
where F
denotes the support of the random variable X ~ p
, H[., .]
denotes (Shannon) cross entropy, and H[.]
denotes (Shannon) entropy.
Args:
other
:tfp.distributions.Distribution
instance.name
: Pythonstr
prepended to names of ops created by this function.
Returns:
kl_divergence
:self.dtype
Tensor
with shape[B1, ..., Bn]
representingn
different calculations of the Kullback-Leibler divergence.
log_cdf
log_cdf(
value,
name='log_cdf',
**kwargs
)
Log cumulative distribution function.
Given random variable X
, the cumulative distribution function cdf
is:
log_cdf(x) := Log[ P[X <= x] ]
Often, a numerical approximation can be used for log_cdf(x)
that yields
a more accurate answer than simply taking the logarithm of the cdf
when
x << -1
.
Args:
value
:float
ordouble
Tensor
.name
: Pythonstr
prepended to names of ops created by this function.**kwargs
: Named arguments forwarded to subclass implementation.
Returns:
logcdf
: aTensor
of shapesample_shape(x) + self.batch_shape
with values of typeself.dtype
.
log_prob
log_prob(
value,
name='log_prob',
**kwargs
)
Log probability density/mass function.
Args:
value
:float
ordouble
Tensor
.name
: Pythonstr
prepended to names of ops created by this function.**kwargs
: Named arguments forwarded to subclass implementation.
Returns:
log_prob
: aTensor
of shapesample_shape(x) + self.batch_shape
with values of typeself.dtype
.
log_survival_function
log_survival_function(
value,
name='log_survival_function',
**kwargs
)
Log survival function.
Given random variable X
, the survival function is defined:
log_survival_function(x) = Log[ P[X > x] ]
= Log[ 1 - P[X <= x] ]
= Log[ 1 - cdf(x) ]
Typically, different numerical approximations can be used for the log
survival function, which are more accurate than 1 - cdf(x)
when x >> 1
.
Args:
value
:float
ordouble
Tensor
.name
: Pythonstr
prepended to names of ops created by this function.**kwargs
: Named arguments forwarded to subclass implementation.
Returns:
Tensor
of shape sample_shape(x) + self.batch_shape
with values of type
self.dtype
.
mean
mean(
name='mean',
**kwargs
)
Mean.
Additional documentation from GammaGamma
:
The mean of a Gamma-Gamma distribution is
concentration * mixing_rate / (mixing_concentration - 1)
, when
mixing_concentration > 1
, and NaN
otherwise. If self.allow_nan_stats
is False
, an exception will be raised rather than returning NaN
mode
mode(
name='mode',
**kwargs
)
Mode.
param_shapes
param_shapes(
cls,
sample_shape,
name='DistributionParamShapes'
)
Shapes of parameters given the desired shape of a call to sample()
.
This is a class method that describes what key/value arguments are required
to instantiate the given Distribution
so that a particular shape is
returned for that instance's call to sample()
.
Subclasses should override class method _param_shapes
.
Args:
sample_shape
:Tensor
or python list/tuple. Desired shape of a call tosample()
.name
: name to prepend ops with.
Returns:
dict
of parameter name to Tensor
shapes.
param_static_shapes
param_static_shapes(
cls,
sample_shape
)
param_shapes with static (i.e. TensorShape
) shapes.
This is a class method that describes what key/value arguments are required
to instantiate the given Distribution
so that a particular shape is
returned for that instance's call to sample()
. Assumes that the sample's
shape is known statically.
Subclasses should override class method _param_shapes
to return
constant-valued tensors when constant values are fed.
Args:
sample_shape
:TensorShape
or python list/tuple. Desired shape of a call tosample()
.
Returns:
dict
of parameter name to TensorShape
.
Raises:
ValueError
: ifsample_shape
is aTensorShape
and is not fully defined.
prob
prob(
value,
name='prob',
**kwargs
)
Probability density/mass function.
Args:
value
:float
ordouble
Tensor
.name
: Pythonstr
prepended to names of ops created by this function.**kwargs
: Named arguments forwarded to subclass implementation.
Returns:
prob
: aTensor
of shapesample_shape(x) + self.batch_shape
with values of typeself.dtype
.
quantile
quantile(
value,
name='quantile',
**kwargs
)
Quantile function. Aka 'inverse cdf' or 'percent point function'.
Given random variable X
and p in [0, 1]
, the quantile
is:
quantile(p) := x such that P[X <= x] == p
Args:
value
:float
ordouble
Tensor
.name
: Pythonstr
prepended to names of ops created by this function.**kwargs
: Named arguments forwarded to subclass implementation.
Returns:
quantile
: aTensor
of shapesample_shape(x) + self.batch_shape
with values of typeself.dtype
.
sample
sample(
sample_shape=(),
seed=None,
name='sample',
**kwargs
)
Generate samples of the specified shape.
Note that a call to sample()
without arguments will generate a single
sample.
Args:
sample_shape
: 0D or 1Dint32
Tensor
. Shape of the generated samples.seed
: Python integer seed for RNGname
: name to give to the op.**kwargs
: Named arguments forwarded to subclass implementation.
Returns:
samples
: aTensor
with prepended dimensionssample_shape
.
stddev
stddev(
name='stddev',
**kwargs
)
Standard deviation.
Standard deviation is defined as,
stddev = E[(X - E[X])**2]**0.5
where X
is the random variable associated with this distribution, E
denotes expectation, and stddev.shape = batch_shape + event_shape
.
Args:
name
: Pythonstr
prepended to names of ops created by this function.**kwargs
: Named arguments forwarded to subclass implementation.
Returns:
stddev
: Floating-pointTensor
with shape identical tobatch_shape + event_shape
, i.e., the same shape asself.mean()
.
survival_function
survival_function(
value,
name='survival_function',
**kwargs
)
Survival function.
Given random variable X
, the survival function is defined:
survival_function(x) = P[X > x]
= 1 - P[X <= x]
= 1 - cdf(x).
Args:
value
:float
ordouble
Tensor
.name
: Pythonstr
prepended to names of ops created by this function.**kwargs
: Named arguments forwarded to subclass implementation.
Returns:
Tensor
of shape sample_shape(x) + self.batch_shape
with values of type
self.dtype
.
variance
variance(
name='variance',
**kwargs
)
Variance.
Variance is defined as,
Var = E[(X - E[X])**2]
where X
is the random variable associated with this distribution, E
denotes expectation, and Var.shape = batch_shape + event_shape
.
Additional documentation from GammaGamma
:
The variance of a Gamma-Gamma distribution is
concentration**2 * mixing_rate**2 / ((mixing_concentration - 1)**2 *
(mixing_concentration - 2))
, when mixing_concentration > 2
, and NaN
otherwise. If self.allow_nan_stats
is False
, an exception will be
raised rather than returning NaN
Args:
name
: Pythonstr
prepended to names of ops created by this function.**kwargs
: Named arguments forwarded to subclass implementation.
Returns:
variance
: Floating-pointTensor
with shape identical tobatch_shape + event_shape
, i.e., the same shape asself.mean()
.
with_name_scope
with_name_scope(
cls,
method
)
Decorator to automatically enter the module name scope.
class MyModule(tf.Module):
@tf.Module.with_name_scope
def __call__(self, x):
if not hasattr(self, 'w'):
self.w = tf.Variable(tf.random.normal([x.shape[1], 64]))
return tf.matmul(x, self.w)
Using the above module would produce tf.Variable
s and tf.Tensor
s whose
names included the module name:
mod = MyModule()
mod(tf.ones([8, 32]))
# ==> <tf.Tensor: ...>
mod.w
# ==> <tf.Variable ...'my_module/w:0'>
Args:
method
: The method to wrap.
Returns:
The original method wrapped such that it enters the module's name scope.