# oryx.bijectors.Affine

Compute `Y = g(X; shift, scale) = scale @ X + shift`.

Inherits From: `Bijector`

Here `scale = c * I + diag(D1) + tril(L) + V @ diag(D2) @ V.T`.

In TF parlance, the `scale` term is logically equivalent to:

``````scale = (
scale_identity_multiplier * tf.diag(tf.ones(d)) +
tf.diag(scale_diag) +
scale_tril +
scale_perturb_factor @ diag(scale_perturb_diag) @
tf.transpose([scale_perturb_factor])
)
``````

The `scale` term is applied without necessarily materializing constituent matrices, i.e., the matmul is matrix-free when possible.

#### Examples

``````# Y = X
b = Affine()

# Y = X + shift
b = Affine(shift=[1., 2, 3])

# Y = 2 * I @ X.T + shift
b = Affine(shift=[1., 2, 3],
scale_identity_multiplier=2.)

# Y = tf.diag(d1) @ X.T + shift
b = Affine(shift=[1., 2, 3],
scale_diag=[-1., 2, 1])         # Implicitly 3x3.

# Y = (I + v * v.T) @ X.T + shift
b = Affine(shift=[1., 2, 3],
scale_perturb_factor=[[1., 0],
[0, 1],
[1, 1]])

# Y = (diag(d1) + v * diag(d2) * v.T) @ X.T + shift
b = Affine(shift=[1., 2, 3],
scale_diag=[1., 3, 3],          # Implicitly 3x3.
scale_perturb_diag=[2., 1],     # Implicitly 2x2.
scale_perturb_factor=[[1., 0],
[0, 1],
[1, 1]])

``````

`shift` Floating-point `Tensor`. If this is set to `None`, no shift is applied.
`scale_identity_multiplier` floating point rank 0 `Tensor` representing a scaling done to the identity matrix. When `scale_identity_multiplier = scale_diag = scale_tril = None` then `scale += IdentityMatrix`. Otherwise no scaled-identity-matrix is added to `scale`.
`scale_diag` Floating-point `Tensor` representing the diagonal matrix. `scale_diag` has shape `[N1, N2, ... k]`, which represents a k x k diagonal matrix. When `None` no diagonal term is added to `scale`.
`scale_tril` Floating-point `Tensor` representing the lower triangular matrix. `scale_tril` has shape `[N1, N2, ... k, k]`, which represents a k x k lower triangular matrix. When `None` no `scale_tril` term is added to `scale`. The upper triangular elements above the diagonal are ignored.
`scale_perturb_factor` Floating-point `Tensor` representing factor matrix with last two dimensions of shape `(k, r)`. When `None`, no rank-r update is added to `scale`.
`scale_perturb_diag` Floating-point `Tensor` representing the diagonal matrix. `scale_perturb_diag` has shape `[N1, N2, ... r]`, which represents an `r x r` diagonal matrix. When `None` low rank updates will take the form `scale_perturb_factor * scale_perturb_factor.T`.
`adjoint` Python `bool` indicating whether to use the `scale` matrix as specified or its adjoint. Default value: `False`.
`validate_args` Python `bool` indicating whether arguments should be checked for correctness.
`name` Python `str` name given to ops managed by this object.
`dtype` `tf.DType` to prefer when converting args to `Tensor`s. Else, we fall back to a common dtype inferred from the args, finally falling back to float32.

`ValueError` if `perturb_diag` is specified but not `perturb_factor`.
`TypeError` if `shift` has different `dtype` from `scale` arguments.

`adjoint` `bool` indicating `scale` should be used as conjugate transpose.
`dtype`

`forward_min_event_ndims` Returns the minimal number of dimensions bijector.forward operates on.

Multipart bijectors return structured `ndims`, which indicates the expected structure of their inputs. Some multipart bijectors, notably Composites, may return structures of `None`.

`graph_parents` Returns this `Bijector`'s graph_parents as a Python list.
`has_static_min_event_ndims` Returns True if the bijector has statically-known `min_event_ndims`.
`inverse_min_event_ndims` Returns the minimal number of dimensions bijector.inverse operates on.

Multipart bijectors return structured `event_ndims`, which indicates the expected structure of their outputs. Some multipart bijectors, notably Composites, may return structures of `None`.

`is_constant_jacobian` Returns true iff the Jacobian matrix is not a function of x.

`name` Returns the string name of this `Bijector`.
`parameters` Dictionary of parameters used to instantiate this `Bijector`.
`scale` The `scale` `LinearOperator` in `Y = scale @ X + shift`.
`shift` The `shift` `Tensor` in `Y = scale @ X + shift`.
`trainable_variables`

`validate_args` Returns True if Tensor arguments will be validated.
`variables`

## Methods

### `copy`

Creates a copy of the bijector.

Args
`**override_parameters_kwargs` String/value dictionary of initialization arguments to override with new values.

Returns
`bijector` 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)`.

### `experimental_batch_shape`

Returns the batch shape of this bijector for inputs of the given rank.

The batch shape of a bijector decribes the set of distinct transformations it represents on events of a given size. For example: the bijector `tfb.Scale([1., 2.])` has batch shape `[2]` for scalar events (`event_ndims = 0`), because applying it to a scalar event produces two scalar outputs, the result of two different scaling transformations. The same bijector has batch shape `[]` for vector events, because applying it to a vector produces (via elementwise multiplication) a single vector output.

Bijectors that operate independently on multiple state parts, such as `tfb.JointMap`, must broadcast to a coherent batch shape. Some events may not be valid: for example, the bijector `tfd.JointMap([tfb.Scale([1., 2.]), tfb.Scale([1., 2., 3.])])` does not produce a valid batch shape when `event_ndims = [0, 0]`, since the batch shapes of the two parts are inconsistent. The same bijector does define valid batch shapes of `[]`, `[2]`, and `[3]` if `event_ndims` is `[1, 1]`, `[0, 1]`, or `[1, 0]`, respectively.

Since transforming a single event produces a scalar log-det-Jacobian, the batch shape of a bijector with non-constant Jacobian is expected to equal the shape of `forward_log_det_jacobian(x, event_ndims=x_event_ndims)` or `inverse_log_det_jacobian(y, event_ndims=y_event_ndims)`, for `x` or `y` of the specified `ndims`.

Args
`x_event_ndims` Optional Python `int` (structure) number of dimensions in a probabilistic event passed to `forward`; this must be greater than or equal to `self.forward_min_event_ndims`. If `None`, defaults to `self.forward_min_event_ndims`. Mutually exclusive with `y_event_ndims`. Default value: `None`.
`y_event_ndims` Optional Python `int` (structure) number of dimensions in a probabilistic event passed to `inverse`; this must be greater than or equal to `self.inverse_min_event_ndims`. Mutually exclusive with `x_event_ndims`. Default value: `None`.

Returns
`batch_shape` `TensorShape` batch shape of this bijector for a value with the given event rank. May be unknown or partially defined.

### `experimental_batch_shape_tensor`

Returns the batch shape of this bijector for inputs of the given rank.

The batch shape of a bijector decribes the set of distinct transformations it represents on events of a given size. For example: the bijector `tfb.Scale([1., 2.])` has batch shape `[2]` for scalar events (`event_ndims = 0`), because applying it to a scalar event produces two scalar outputs, the result of two different scaling transformations. The same bijector has batch shape `[]` for vector events, because applying it to a vector produces (via elementwise multiplication) a single vector output.

Bijectors that operate independently on multiple state parts, such as `tfb.JointMap`, must broadcast to a coherent batch shape. Some events may not be valid: for example, the bijector `tfd.JointMap([tfb.Scale([1., 2.]), tfb.Scale([1., 2., 3.])])` does not produce a valid batch shape when `event_ndims = [0, 0]`, since the batch shapes of the two parts are inconsistent. The same bijector does define valid batch shapes of `[]`, `[2]`, and `[3]` if `event_ndims` is `[1, 1]`, `[0, 1]`, or `[1, 0]`, respectively.

Since transforming a single event produces a scalar log-det-Jacobian, the batch shape of a bijector with non-constant Jacobian is expected to equal the shape of `forward_log_det_jacobian(x, event_ndims=x_event_ndims)` or `inverse_log_det_jacobian(y, event_ndims=y_event_ndims)`, for `x` or `y` of the specified `ndims`.

Args
`x_event_ndims` Optional Python `int` (structure) number of dimensions in a probabilistic event passed to `forward`; this must be greater than or equal to `self.forward_min_event_ndims`. If `None`, defaults to `self.forward_min_event_ndims`. Mutually exclusive with `y_event_ndims`. Default value: `None`.
`y_event_ndims` Optional Python `int` (structure) number of dimensions in a probabilistic event passed to `inverse`; this must be greater than or equal to `self.inverse_min_event_ndims`. Mutually exclusive with `x_event_ndims`. Default value: `None`.

Returns
`batch_shape_tensor` integer `Tensor` batch shape of this bijector for a value with the given event rank.

### `forward`

Returns the forward `Bijector` evaluation, i.e., X = g(Y).

Args
`x` `Tensor` (structure). The input to the 'forward' evaluation.
`name` The name to give this op.
`**kwargs` Named arguments forwarded to subclass implementation.

Returns
`Tensor` (structure).

Raises
`TypeError` if `self.dtype` is specified and `x.dtype` is not `self.dtype`.
`NotImplementedError` if `_forward` is not implemented.

### `forward_dtype`

Returns the dtype returned by `forward` for the provided input.

### `forward_event_ndims`

Returns the number of event dimensions produced by `forward`.

### `forward_event_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` (structure) indicating event-portion shape passed into `forward` function.

Returns
`forward_event_shape_tensor` `TensorShape` (structure) indicating event-portion shape after applying `forward`. Possibly unknown.

### `forward_event_shape_tensor`

Shape of a single sample from a single batch as an `int32` 1D `Tensor`.

Args
`input_shape` `Tensor`, `int32` vector (structure) indicating event-portion shape passed into `forward` function.
`name` name to give to the op

Returns
`forward_event_shape_tensor` `Tensor`, `int32` vector (structure) indicating event-portion shape after applying `forward`.

### `forward_log_det_jacobian`

Returns both the forward_log_det_jacobian.

Args
`x` `Tensor` (structure). The input to the 'forward' Jacobian determinant evaluation.
`event_ndims` Optional number of dimensions in the probabilistic events being transformed; this must be greater than or equal to `self.forward_min_event_ndims`. If `event_ndims` is specified, the log Jacobian determinant is summed to produce a scalar log-determinant for each event. Otherwise (if `event_ndims` is `None`), no reduction is performed. Multipart bijectors require structured event_ndims, such that the batch rank `rank(y[i]) - event_ndims[i]` is the same for all elements `i` of the structured input. In most cases (with the exception of `tfb.JointMap`) they further require that `event_ndims[i] - self.inverse_min_event_ndims[i]` is the same for all elements `i` of the structured input. Default value: `None` (equivalent to `self.forward_min_event_ndims`).
`name` The name to give this op.
`**kwargs` Named arguments forwarded to subclass implementation.

Returns
`Tensor` (structure), if this bijector is injective. If not injective this is not implemented.

Raises
`TypeError` if `y`'s dtype is incompatible with the expected output dtype.
`NotImplementedError` if neither `_forward_log_det_jacobian` nor {`_inverse`, `_inverse_log_det_jacobian`} are implemented, or this is a non-injective bijector.
`ValueError` if the value of `event_ndims` is not valid for this bijector.

### `inverse`

Returns the inverse `Bijector` evaluation, i.e., X = g^{-1}(Y).

Args
`y` `Tensor` (structure). The input to the 'inverse' evaluation.
`name` The name to give this op.
`**kwargs` Named arguments forwarded to subclass implementation.

Returns
`Tensor` (structure), 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` if `y`'s structured dtype is incompatible with the expected output dtype.
`NotImplementedError` if `_inverse` is not implemented.

### `inverse_dtype`

Returns the dtype returned by `inverse` for the provided input.

### `inverse_event_ndims`

Returns the number of event dimensions produced by `inverse`.

### `inverse_event_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` (structure) indicating event-portion shape passed into `inverse` function.

Returns
`inverse_event_shape_tensor` `TensorShape` (structure) indicating event-portion shape after applying `inverse`. Possibly unknown.

### `inverse_event_shape_tensor`

Shape of a single sample from a single batch as an `int32` 1D `Tensor`.

Args
`output_shape` `Tensor`, `int32` vector (structure) indicating event-portion shape passed into `inverse` function.
`name` name to give to the op

Returns
`inverse_event_shape_tensor` `Tensor`, `int32` vector (structure) indicating event-portion shape after applying `inverse`.

### `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` (structure). The input to the 'inverse' Jacobian determinant evaluation.
`event_ndims` Optional number of dimensions in the probabilistic events being transformed; this must be greater than or equal to `self.inverse_min_event_ndims`. If `event_ndims` is specified, the log Jacobian determinant is summed to produce a scalar log-determinant for each event. Otherwise (if `event_ndims` is `None`), no reduction is performed. Multipart bijectors require structured event_ndims, such that the batch rank `rank(y[i]) - event_ndims[i]` is the same for all elements `i` of the structured input. In most cases (with the exception of `tfb.JointMap`) they further require that `event_ndims[i] - self.inverse_min_event_ndims[i]` is the same for all elements `i` of the structured input. Default value: `None` (equivalent to `self.inverse_min_event_ndims`).
`name` The name to give this op.
`**kwargs` Named arguments forwarded to subclass implementation.

Returns
`ildj` `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` if `x`'s dtype is incompatible with the expected inverse-dtype.
`NotImplementedError` if `_inverse_log_det_jacobian` is not implemented.
`ValueError` if the value of `event_ndims` is not valid for this bijector.

### `parameter_properties`

Returns a dict mapping constructor arg names to property annotations.

This dict should include an entry for each of the bijector's `Tensor`-valued constructor arguments.

Args
`dtype` Optional float `dtype` to assume for continuous-valued parameters. Some constraining bijectors require advance knowledge of the dtype because certain constants (e.g., `tfb.Softplus.low`) must be instantiated with the same dtype as the values to be transformed.

Returns
`parameter_properties` A `str ->`tfp.python.internal.parameter_properties.ParameterProperties`dict mapping constructor argument names to`ParameterProperties` instances.

### `__call__`

Applies or composes the `Bijector`, depending on input type.

This is a convenience function which applies the `Bijector` instance in three different ways, depending on the input:

1. If the input is a `tfd.Distribution` instance, return `tfd.TransformedDistribution(distribution=input, bijector=self)`.
2. If the input is a `tfb.Bijector` instance, return `tfb.Chain([self, input])`.
3. Otherwise, return `self.forward(input)`

Args
`value` A `tfd.Distribution`, `tfb.Bijector`, or a (structure of) `Tensor`.
`name` Python `str` name given to ops created by this function.
`**kwargs` Additional keyword arguments passed into the created `tfd.TransformedDistribution`, `tfb.Bijector`, or `self.forward`.

Returns
`composition` A `tfd.TransformedDistribution` if the input was a `tfd.Distribution`, a `tfb.Chain` if the input was a `tfb.Bijector`, or a (structure of) `Tensor` computed by `self.forward`.

#### Examples

``````sigmoid = tfb.Reciprocal()(
tfb.Shift(shift=1.)(
tfb.Exp()(
tfb.Scale(scale=-1.))))
# ==> `tfb.Chain([
#         tfb.Reciprocal(),
#         tfb.Shift(shift=1.),
#         tfb.Exp(),
#         tfb.Scale(scale=-1.),
#      ])`  # ie, `tfb.Sigmoid()`

log_normal = tfb.Exp()(tfd.Normal(0, 1))
# ==> `tfd.TransformedDistribution(tfd.Normal(0, 1), tfb.Exp())`

tfb.Exp()([-1., 0., 1.])
# ==> tf.exp([-1., 0., 1.])
``````

### `__eq__`

Return self==value.

[{ "type": "thumb-down", "id": "missingTheInformationINeed", "label":"Missing the information I need" },{ "type": "thumb-down", "id": "tooComplicatedTooManySteps", "label":"Too complicated / too many steps" },{ "type": "thumb-down", "id": "outOfDate", "label":"Out of date" },{ "type": "thumb-down", "id": "samplesCodeIssue", "label":"Samples / code issue" },{ "type": "thumb-down", "id": "otherDown", "label":"Other" }]
[{ "type": "thumb-up", "id": "easyToUnderstand", "label":"Easy to understand" },{ "type": "thumb-up", "id": "solvedMyProblem", "label":"Solved my problem" },{ "type": "thumb-up", "id": "otherUp", "label":"Other" }]