<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/stats/sample_stats.py#L715-L891) |

A running R-hat diagnostic.

Inherits From: [`AutoCompositeTensor`](https://www.tensorflow.org/probability/api_docs/python/tfp/experimental/AutoCompositeTensor)

    tfp.experimental.stats.RunningPotentialScaleReduction(
        chain_variances, independent_chain_ndims
    )

`RunningPotentialScaleReduction` uses Gelman and Rubin (1992)'s potential
scale reduction (also known as R-hat) for chain convergence \[1\].

If multiple independent R-hat computations are desired across a latent
state, one should use a (possibly nested) collection for initialization
parameters `independent_chain_ndims` and `shape`. Subsequent chain states
used to update the streaming R-hat should mimic their identical structure.

`RunningPotentialScaleReduction` also assumes that incoming samples have shape
`[Ci1, Ci2,...,CiD] + A`. Dimensions `0` through `D - 1` index the
`Ci1 x ... x CiD` independent chains to be tested for convergence to the same
target. The remaining dimensions, `A`, represent the event shape and hence,
can have any shape (even empty, which implies scalar samples). The number of
independent chain dimensions is defined by the `independent_chain_ndims`
parameter at initialization.

`RunningPotentialScaleReduction` is meant to serve general streaming R-hat.
For a specialized version that fits streaming over MCMC samples, see
`PotentialScaleReductionReducer` in [`tfp.experimental.mcmc`](https://www.tensorflow.org/probability/api_docs/python/tfp/experimental/mcmc).

#### References

\[1\]: Andrew Gelman and Donald B. Rubin. Inference from Iterative Simulation
Using Multiple Sequences. *Statistical Science*, 7(4):457-472, 1992.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `chain_variances` | A `RunningVariance` or nested structure of `RunningVariance`s, giving the variance estimates for the variables of interest. |
| `independent_chain_ndims` | A Python `int` or structure of Python `ints` parallel to `chain_variances` giving the number of leading dimensions in `chain_variances` that index the independent chains over which the potential scale reduction factor should be computed. Must be at least 1. |

<br />

## Methods

### `from_example`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/stats/sample_stats.py#L803-L823)

    @classmethod
    from_example(
        example, independent_chain_ndims=1
    )

Starts an empty `RunningPotentialScaleReduction` from metadata.

<br />

<br />

<br />

| Args ||
|---|---|
| `example` | A `Tensor`. The `RunningPotentialScaleReduction` will accept samples of the same dtype and broadcast-compatible shape as the example. |
| `independent_chain_ndims` | Integer or Integer type `Tensor` with value `>= 1` giving the number of leading dimensions holding independent chain results to be tested for convergence. Using a collection implies that future samples will mimic that exact structure. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `state` | `RunningPotentialScaleReduction` representing a stream of no inputs. Note that by convention, the supplied example is used only for initialization, but not counted as a sample. |

<br />

### `from_shape`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/stats/sample_stats.py#L768-L801)

    @classmethod
    from_shape(
        shape=(), independent_chain_ndims=1, dtype=tf.float32
    )

Starts an empty `RunningPotentialScaleReduction` from metadata.

<br />

<br />

<br />

| Args ||
|---|---|
| `shape` | Python `Tuple` or `TensorShape` representing the shape of incoming samples. Using a collection implies that future samples will mimic that exact structure. This is useful to supply if the `RunningPotentialScaleReduction` will be carried by a [`tf.while_loop`](https://www.tensorflow.org/api_docs/python/tf/while_loop), so that broadcasting does not change the shape across loop iterations. |
| `independent_chain_ndims` | Integer or Integer type `Tensor` with value `>= 1` giving the number of leading dimensions holding independent chain results to be tested for convergence. Using a collection implies that future samples will mimic that exact structure. |
| `dtype` | Dtype of incoming samples and the resulting statistics. By default, the dtype is [`tf.float32`](https://www.tensorflow.org/api_docs/python/tf#float32). Any integer dtypes will be cast to corresponding floats (i.e. [`tf.int32`](https://www.tensorflow.org/api_docs/python/tf#int32) will be cast to [`tf.float32`](https://www.tensorflow.org/api_docs/python/tf#float32)), as intermediate calculations should be performing floating-point division. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `state` | `RunningPotentialScaleReduction` representing a stream of no inputs. |

<br />

### `potential_scale_reduction`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/stats/sample_stats.py#L849-L885)

    potential_scale_reduction()

Computes the potential scale reduction for samples accumulated so far.

<br />

<br />

<br />

| Returns ||
|---|---|
| `rhat` | An estimate of the R-hat. |

<br />

### `tree_flatten`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/stats/sample_stats.py#L761-L762)

    tree_flatten()

### `tree_unflatten`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/stats/sample_stats.py#L764-L766)

    @classmethod
    tree_unflatten(
        metadata, tensors
    )

### `update`

[View source](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/experimental/stats/sample_stats.py#L825-L847)

    update(
        new_sample
    )

Update the `RunningPotentialScaleReduction` with a new sample.

<br />

<br />

<br />

| Args ||
|---|---|
| `new_sample` | Incoming `Tensor` sample or (possibly nested) collection of `Tensor`s with shape and dtype compatible with those used to form the `RunningPotentialScaleReduction`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| `state` | `RunningPotentialScaleReduction` updated to include the new sample. |

<br />