View source on GitHub |
PoissonLogNormalQuadratureCompound
distribution.
Inherits From: Distribution
tf.contrib.distributions.PoissonLogNormalQuadratureCompound(
loc, scale, quadrature_size=8,
quadrature_fn=tf.contrib.distributions.quadrature_scheme_lognormal_quantiles,
validate_args=False, allow_nan_stats=True,
name='PoissonLogNormalQuadratureCompound'
)
The PoissonLogNormalQuadratureCompound
is an approximation to a
Poisson-LogNormal compound distribution, i.e.,
p(k|loc, scale)
= int_{R_+} dl LogNormal(l | loc, scale) Poisson(k | l)
approx= sum{ prob[d] Poisson(k | lambda(grid[d])) : d=0, ..., deg-1 }
By default, the grid
is chosen as quantiles of the LogNormal
distribution
parameterized by loc
, scale
and the prob
vector is
[1. / quadrature_size]*quadrature_size
.
In the non-approximation case, a draw from the LogNormal prior represents the
Poisson rate parameter. Unfortunately, the non-approximate distribution lacks
an analytical probability density function (pdf). Therefore the
PoissonLogNormalQuadratureCompound
class implements an approximation based
on quadrature.
Mathematical Details
The PoissonLogNormalQuadratureCompound
approximates a Poisson-LogNormal
compound distribution. Using
variable-substitution and numerical quadrature (default:
based on LogNormal
quantiles) we can redefine the distribution to be a
parameter-less convex combination of deg
different Poisson samples.
That is, defined over positive integers, this distribution is parameterized
by a (batch of) loc
and scale
scalars.
The probability density function (pdf) is,
pdf(k | loc, scale, deg)
= sum{ prob[d] Poisson(k | lambda=exp(grid[d]))
: d=0, ..., deg-1 }
Examples
import tensorflow_probability as tfp
tfd = tfp.distributions
# Create two batches of PoissonLogNormalQuadratureCompounds, one with
# prior `loc = 0.` and another with `loc = 1.` In both cases `scale = 1.`
pln = tfd.PoissonLogNormalQuadratureCompound(
loc=[0., -0.5],
scale=1.,
quadrature_size=10,
validate_args=True)
<!-- Tabular view -->
<table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2"><h2 class="add-link">Args</h2></th></tr>
<tr>
<td>
`loc`
</td>
<td>
`float`-like (batch of) scalar `Tensor`; the location parameter of
the LogNormal prior.
</td>
</tr><tr>
<td>
`scale`
</td>
<td>
`float`-like (batch of) scalar `Tensor`; the scale parameter of
the LogNormal prior.
</td>
</tr><tr>
<td>
`quadrature_size`
</td>
<td>
Python `int` scalar representing the number of quadrature
points.
</td>
</tr><tr>
<td>
`quadrature_fn`
</td>
<td>
Python callable taking `loc`, `scale`,
`quadrature_size`, `validate_args` and returning `tuple(grid, probs)`
representing the LogNormal grid and corresponding normalized weight.
normalized) weight.
Default value: `quadrature_scheme_lognormal_quantiles`.
</td>
</tr><tr>
<td>
`validate_args`
</td>
<td>
Python `bool`, default `False`. When `True` distribution
parameters are checked for validity despite possibly degrading runtime
performance. When `False` invalid inputs may silently render incorrect
outputs.
</td>
</tr><tr>
<td>
`allow_nan_stats`
</td>
<td>
Python `bool`, default `True`. When `True`,
statistics (e.g., mean, mode, variance) use the value "`NaN`" to
indicate the result is undefined. When `False`, an exception is raised
if one or more of the statistic's batch members are undefined.
</td>
</tr><tr>
<td>
`name`
</td>
<td>
Python `str` name prefixed to Ops created by this class.
</td>
</tr>
</table>
<!-- Tabular view -->
<table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2"><h2 class="add-link">Raises</h2></th></tr>
<tr>
<td>
`TypeError`
</td>
<td>
if `quadrature_grid` and `quadrature_probs` have different base
`dtype`.
</td>
</tr>
</table>
<!-- Tabular view -->
<table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2"><h2 class="add-link">Attributes</h2></th></tr>
<tr>
<td>
`allow_nan_stats`
</td>
<td>
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.
</td>
</tr><tr>
<td>
`batch_shape`
</td>
<td>
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.
</td>
</tr><tr>
<td>
`distribution`
</td>
<td>
Base Poisson parameterized by a quadrature grid.
</td>
</tr><tr>
<td>
`dtype`
</td>
<td>
The `DType` of `Tensor`s handled by this `Distribution`.
</td>
</tr><tr>
<td>
`event_shape`
</td>
<td>
Shape of a single sample from a single batch as a `TensorShape`.
May be partially defined or unknown.
</td>
</tr><tr>
<td>
`loc`
</td>
<td>
Location parameter of the LogNormal prior.
</td>
</tr><tr>
<td>
`mixture_distribution`
</td>
<td>
Distribution which randomly selects a Poisson with quadrature param.
</td>
</tr><tr>
<td>
`name`
</td>
<td>
Name prepended to all ops created by this `Distribution`.
</td>
</tr><tr>
<td>
`parameters`
</td>
<td>
Dictionary of parameters used to instantiate this `Distribution`.
</td>
</tr><tr>
<td>
`quadrature_size`
</td>
<td>
</td>
</tr><tr>
<td>
`reparameterization_type`
</td>
<td>
Describes how samples from the distribution are reparameterized.
Currently this is one of the static instances
`distributions.FULLY_REPARAMETERIZED`
or `distributions.NOT_REPARAMETERIZED`.
</td>
</tr><tr>
<td>
`scale`
</td>
<td>
Scale parameter of the LogNormal prior.
</td>
</tr><tr>
<td>
`validate_args`
</td>
<td>
Python `bool` indicating possibly expensive checks are enabled.
</td>
</tr>
</table>
## Methods
<h3 id="batch_shape_tensor"><code>batch_shape_tensor</code></h3>
<a target="_blank" href="https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/distributions/distribution.py#L637-L654">View source</a>
<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>batch_shape_tensor(
name='batch_shape_tensor'
)
</code></pre>
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.
<!-- Tabular view -->
<table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Args</th></tr>
<tr>
<td>
`name`
</td>
<td>
name to give to the op
</td>
</tr>
</table>
<!-- Tabular view -->
<table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr>
<td>
`batch_shape`
</td>
<td>
`Tensor`.
</td>
</tr>
</table>
<h3 id="cdf"><code>cdf</code></h3>
<a target="_blank" href="https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/python/ops/distributions/distribution.py#L881-L898">View source</a>
<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>cdf(
value, name='cdf'
)
</code></pre>
Cumulative distribution function.
Given random variable `X`, the cumulative distribution function `cdf` is:
```none
cdf(x) := P[X <= x]
Args | |
---|---|
value
|
float or double Tensor .
|
name
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
cdf
|
a Tensor of shape sample_shape(x) + self.batch_shape with
values of type self.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 of type(self) initialized from the union
of self.parameters and override_parameters_kwargs, i.e.,
dict(self.parameters, **override_parameters_kwargs) .
|
covariance
covariance(
name='covariance'
)
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
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
covariance
|
Floating-point Tensor with shape [B1, ..., Bn, k', k']
where the first n dimensions are batch coordinates and
k' = 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)
, (Shanon)
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
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
cross_entropy
|
self.dtype Tensor with shape [B1, ..., Bn]
representing n different calculations of (Shanon) cross entropy.
|
entropy
entropy(
name='entropy'
)
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
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
is_scalar_batch
|
bool scalar Tensor .
|
is_scalar_event
is_scalar_event(
name='is_scalar_event'
)
Indicates that event_shape == []
.
Args | |
---|---|
name
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
is_scalar_event
|
bool scalar Tensor .
|
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 (Shanon) cross entropy, and H[.]
denotes (Shanon) entropy.
Args | |
---|---|
other
|
tfp.distributions.Distribution instance.
|
name
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
kl_divergence
|
self.dtype Tensor with shape [B1, ..., Bn]
representing n different calculations of the Kullback-Leibler
divergence.
|
log_cdf
log_cdf(
value, name='log_cdf'
)
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 or double Tensor .
|
name
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
logcdf
|
a Tensor of shape sample_shape(x) + self.batch_shape with
values of type self.dtype .
|
log_prob
log_prob(
value, name='log_prob'
)
Log probability density/mass function.
Args | |
---|---|
value
|
float or double Tensor .
|
name
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
log_prob
|
a Tensor of shape sample_shape(x) + self.batch_shape with
values of type self.dtype .
|
log_survival_function
log_survival_function(
value, name='log_survival_function'
)
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 or double Tensor .
|
name
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
Tensor of shape sample_shape(x) + self.batch_shape with values of type
self.dtype .
|
mean
mean(
name='mean'
)
Mean.
mode
mode(
name='mode'
)
Mode.
param_shapes
@classmethod
param_shapes( 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 to
sample() .
|
name
|
name to prepend ops with. |
Returns | |
---|---|
dict of parameter name to Tensor shapes.
|
param_static_shapes
@classmethod
param_static_shapes( 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
to sample() .
|
Returns | |
---|---|
dict of parameter name to TensorShape .
|
Raises | |
---|---|
ValueError
|
if sample_shape is a TensorShape and is not fully defined.
|
prob
prob(
value, name='prob'
)
Probability density/mass function.
Args | |
---|---|
value
|
float or double Tensor .
|
name
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
prob
|
a Tensor of shape sample_shape(x) + self.batch_shape with
values of type self.dtype .
|
quantile
quantile(
value, name='quantile'
)
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 or double Tensor .
|
name
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
quantile
|
a Tensor of shape sample_shape(x) + self.batch_shape with
values of type self.dtype .
|
sample
sample(
sample_shape=(), seed=None, name='sample'
)
Generate samples of the specified shape.
Note that a call to sample()
without arguments will generate a single
sample.
Args | |
---|---|
sample_shape
|
0D or 1D int32 Tensor . Shape of the generated samples.
|
seed
|
Python integer seed for RNG |
name
|
name to give to the op. |
Returns | |
---|---|
samples
|
a Tensor with prepended dimensions sample_shape .
|
stddev
stddev(
name='stddev'
)
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
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
stddev
|
Floating-point Tensor with shape identical to
batch_shape + event_shape , i.e., the same shape as self.mean() .
|
survival_function
survival_function(
value, name='survival_function'
)
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 or double Tensor .
|
name
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
Tensor of shape sample_shape(x) + self.batch_shape with values of type
self.dtype .
|
variance
variance(
name='variance'
)
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
.
Args | |
---|---|
name
|
Python str prepended to names of ops created by this function.
|
Returns | |
---|---|
variance
|
Floating-point Tensor with shape identical to
batch_shape + event_shape , i.e., the same shape as self.mean() .
|