# tf.contrib.metrics.streaming_covariance

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/tensorflow/blob/v1.15.0/tensorflow/contrib/metrics/python/ops/metric_ops.py#L3136-L3274) |

Computes the unbiased sample covariance between `predictions` and `labels`.

    tf.contrib.metrics.streaming_covariance(
        predictions, labels, weights=None, metrics_collections=None,
        updates_collections=None, name=None
    )

The `streaming_covariance` function creates four local variables,
`comoment`, `mean_prediction`, `mean_label`, and `count`, which are used to
compute the sample covariance between predictions and labels across multiple
batches of data. The covariance is ultimately returned as an idempotent
operation that simply divides `comoment` by `count` - 1. We use `count` - 1
in order to get an unbiased estimate.

The algorithm used for this online computation is described in
<https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance>
Specifically, the formula used to combine two sample comoments is
`C_AB = C_A + C_B + (E[x_A] - E[x_B]) * (E[y_A] - E[y_B]) * n_A * n_B / n_AB`
The comoment for a single batch of data is simply
`sum((x - E[x]) * (y - E[y]))`, optionally weighted.

If `weights` is not None, then it is used to compute weighted comoments,
means, and count. NOTE: these weights are treated as "frequency weights", as
opposed to "reliability weights". See discussion of the difference on
<https://wikipedia.org/wiki/Weighted_arithmetic_mean#Weighted_sample_variance>

To facilitate the computation of covariance across multiple batches of data,
the function creates an `update_op` operation, which updates underlying
variables and returns the updated covariance.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `predictions` | A `Tensor` of arbitrary size. |
| `labels` | A `Tensor` of the same size as `predictions`. |
| `weights` | Optional `Tensor` indicating the frequency with which an example is sampled. Rank must be 0, or the same rank as `labels`, and must be broadcastable to `labels` (i.e., all dimensions must be either `1`, or the same as the corresponding `labels` dimension). |
| `metrics_collections` | An optional list of collections that the metric value variable should be added to. |
| `updates_collections` | An optional list of collections that the metric update ops should be added to. |
| `name` | An optional variable_scope name. |

<br />

<br />

<br />

<br />

| ## Returns ||
|---|---|
| `covariance` | A `Tensor` representing the current unbiased sample covariance, `comoment` / (`count` - 1). |
| `update_op` | An operation that updates the local variables appropriately. |

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `ValueError` | If labels and predictions are of different sizes or if either `metrics_collections` or `updates_collections` are not a list or tuple. |

<br />