Class ScaleTriL
Inherits From: Chain
Defined in tensorflow/contrib/distributions/python/ops/bijectors/scale_tril.py
.
Transforms unconstrained vectors to TriL matrices with positive diagonal.
This is implemented as a simple tfb.Chain
of tfb.FillTriangular
followed by tfb.TransformDiagonal
, and provided mostly as a
convenience. The default setup is somewhat opinionated, using a
Softplus transformation followed by a small shift (1e-5
) which
attempts to avoid numerical issues from zeros on the diagonal.
Examples
import tensorflow_probability as tfp
tfd = tfp.distributions
tfb = tfp.bijectors
b = tfb.ScaleTriL(
diag_bijector=tfb.Exp(),
diag_shift=None)
b.forward(x=[0., 0., 0.])
# Result: [[1., 0.],
# [0., 1.]]
b.inverse(y=[[1., 0],
[.5, 2]])
# Result: [log(2), .5, log(1)]
# Define a distribution over PSD matrices of shape `[3, 3]`,
# with `1 + 2 + 3 = 6` degrees of freedom.
dist = tfd.TransformedDistribution(
tfd.Normal(tf.zeros(6), tf.ones(6)),
tfb.Chain([tfb.CholeskyOuterProduct(), tfb.ScaleTriL()]))
# Using an identity transformation, ScaleTriL is equivalent to
# tfb.FillTriangular.
b = tfb.ScaleTriL(
diag_bijector=tfb.Identity(),
diag_shift=None)
# For greater control over initialization, one can manually encode
# pre- and post- shifts inside of `diag_bijector`.
b = tfb.ScaleTriL(
diag_bijector=tfb.Chain([
tfb.AffineScalar(shift=1e-3),
tfb.Softplus(),
tfb.AffineScalar(shift=0.5413)]), # softplus_inverse(1.)
# = log(expm1(1.)) = 0.5413
diag_shift=None)
__init__
__init__(
diag_bijector=None,
diag_shift=1e-05,
validate_args=False,
name='scale_tril'
)
Instantiates the ScaleTriL
bijector. (deprecated)
Args:
diag_bijector
:Bijector
instance, used to transform the output diagonal to be positive. Default value:None
(i.e.,tfb.Softplus()
).diag_shift
: Float value broadcastable and added to all diagonal entries after applying thediag_bijector
. Setting a positive value forces the output diagonal entries to be positive, but prevents inverting the transformation for matrices with diagonal entries less than this value. Default value:1e-5
(i.e., no shift is applied).validate_args
: Pythonbool
indicating whether arguments should be checked for correctness. Default value:False
(i.e., arguments are not validated).name
: Pythonstr
name given to ops managed by this object. Default value:scale_tril
.
Properties
bijectors
dtype
dtype of Tensor
s transformable by this distribution.
forward_min_event_ndims
Returns the minimal number of dimensions bijector.forward operates on.
graph_parents
Returns this Bijector
's graph_parents as a Python list.
inverse_min_event_ndims
Returns the minimal number of dimensions bijector.inverse operates on.
is_constant_jacobian
Returns true iff the Jacobian matrix is not a function of x.
Returns:
is_constant_jacobian
: Pythonbool
.
name
Returns the string name of this Bijector
.
validate_args
Returns True if Tensor arguments will be validated.
Methods
tf.contrib.distributions.bijectors.ScaleTriL.forward
forward(
x,
name='forward'
)
Returns the forward Bijector
evaluation, i.e., X = g(Y).
Args:
x
:Tensor
. The input to the "forward" evaluation.name
: The name to give this op.
Returns:
Tensor
.
Raises:
TypeError
: ifself.dtype
is specified andx.dtype
is notself.dtype
.NotImplementedError
: if_forward
is not implemented.
tf.contrib.distributions.bijectors.ScaleTriL.forward_event_shape
forward_event_shape(input_shape)
Shape of a single sample from a single batch as a TensorShape
.
Same meaning as forward_event_shape_tensor
. May be only partially defined.
Args:
input_shape
:TensorShape
indicating event-portion shape passed intoforward
function.
Returns:
forward_event_shape_tensor
:TensorShape
indicating event-portion shape after applyingforward
. Possibly unknown.
tf.contrib.distributions.bijectors.ScaleTriL.forward_event_shape_tensor
forward_event_shape_tensor(
input_shape,
name='forward_event_shape_tensor'
)
Shape of a single sample from a single batch as an int32
1D Tensor
.
Args:
input_shape
:Tensor
,int32
vector indicating event-portion shape passed intoforward
function.name
: name to give to the op
Returns:
forward_event_shape_tensor
:Tensor
,int32
vector indicating event-portion shape after applyingforward
.
tf.contrib.distributions.bijectors.ScaleTriL.forward_log_det_jacobian
forward_log_det_jacobian(
x,
event_ndims,
name='forward_log_det_jacobian'
)
Returns both the forward_log_det_jacobian.
Args:
x
:Tensor
. The input to the "forward" Jacobian determinant evaluation.event_ndims
: Number of dimensions in the probabilistic events being transformed. Must be greater than or equal toself.forward_min_event_ndims
. The result is summed over the final dimensions to produce a scalar Jacobian determinant for each event, i.e. it has shapex.shape.ndims - event_ndims
dimensions.name
: The name to give this op.
Returns:
Tensor
, if this bijector is injective.
If not injective this is not implemented.
Raises:
TypeError
: ifself.dtype
is specified andy.dtype
is notself.dtype
.NotImplementedError
: if neither_forward_log_det_jacobian
nor {_inverse
,_inverse_log_det_jacobian
} are implemented, or this is a non-injective bijector.
tf.contrib.distributions.bijectors.ScaleTriL.inverse
inverse(
y,
name='inverse'
)
Returns the inverse Bijector
evaluation, i.e., X = g^{-1}(Y).
Args:
y
:Tensor
. The input to the "inverse" evaluation.name
: The name to give this op.
Returns:
Tensor
, if this bijector is injective.
If not injective, returns the k-tuple containing the unique
k
points (x1, ..., xk)
such that g(xi) = y
.
Raises:
TypeError
: ifself.dtype
is specified andy.dtype
is notself.dtype
.NotImplementedError
: if_inverse
is not implemented.
tf.contrib.distributions.bijectors.ScaleTriL.inverse_event_shape
inverse_event_shape(output_shape)
Shape of a single sample from a single batch as a TensorShape
.
Same meaning as inverse_event_shape_tensor
. May be only partially defined.
Args:
output_shape
:TensorShape
indicating event-portion shape passed intoinverse
function.
Returns:
inverse_event_shape_tensor
:TensorShape
indicating event-portion shape after applyinginverse
. Possibly unknown.
tf.contrib.distributions.bijectors.ScaleTriL.inverse_event_shape_tensor
inverse_event_shape_tensor(
output_shape,
name='inverse_event_shape_tensor'
)
Shape of a single sample from a single batch as an int32
1D Tensor
.
Args:
output_shape
:Tensor
,int32
vector indicating event-portion shape passed intoinverse
function.name
: name to give to the op
Returns:
inverse_event_shape_tensor
:Tensor
,int32
vector indicating event-portion shape after applyinginverse
.
tf.contrib.distributions.bijectors.ScaleTriL.inverse_log_det_jacobian
inverse_log_det_jacobian(
y,
event_ndims,
name='inverse_log_det_jacobian'
)
Returns the (log o det o Jacobian o inverse)(y).
Mathematically, returns: log(det(dX/dY))(Y)
. (Recall that: X=g^{-1}(Y)
.)
Note that forward_log_det_jacobian
is the negative of this function,
evaluated at g^{-1}(y)
.
Args:
y
:Tensor
. The input to the "inverse" Jacobian determinant evaluation.event_ndims
: Number of dimensions in the probabilistic events being transformed. Must be greater than or equal toself.inverse_min_event_ndims
. The result is summed over the final dimensions to produce a scalar Jacobian determinant for each event, i.e. it has shapey.shape.ndims - event_ndims
dimensions.name
: The name to give this op.
Returns:
Tensor
, if this bijector is injective.
If not injective, returns the tuple of local log det
Jacobians, log(det(Dg_i^{-1}(y)))
, where g_i
is the restriction
of g
to the ith
partition Di
.
Raises:
TypeError
: ifself.dtype
is specified andy.dtype
is notself.dtype
.NotImplementedError
: if_inverse_log_det_jacobian
is not implemented.