class_docstr: `Reducer` that computes a running covariance.
  
  By default, `CovarianceReducer` computes covariance directly over the
  latent state, ignoring kernel results; however, it can also compute
  a running covariance on samples evaluated on some arbitrary structure of
  `transform_fn`s. A `trasform_fn` is defined as any function that accepts
  the chain state and kernel results, and ouptuts a `Tensor` or nested
  structure of `Tensor`s to compute the covariance over. To be explicit,
  if we denote a `transform_fn` as f(x, y), then `CovarianceReducer` will
  compute Cov(f(x, y)). If some structure of `transform_fn`s are given,
  the final statistic (as returned by the `finalize` method) will mimic
  the results of that structure.
  
  As with all reducers, CovarianceReducer does not hold state information;
  rather, it stores supplied metadata. Intermediate calculations are held in
  a state object, which is returned via `initialize` and `one_step` method
  calls.
  
  `CovarianceReducer` is meant to fit into the larger Streaming MCMC
  framework. `RunningCovariance` in `tfp.experimental.stats` is better suited
  for more generic streaming covariance needs.
  
  There are two ways to stream over MCMC samples. The first is to manually
  wrap `CovarianceReducer` in a `tfp.experimental.mcmc.WithReductions`
  `TransitionKernel`. Doing so enables a wide variety of possible compositions.
  For example, to perform covariance calculation on samples that survive
  thinning and burn-in, `WithReductions` should wrap around an appropriate
  `SampleDiscardingKernel`.
  
  If the sole objective is to estimate covariance, it may be more convenient to
  use a pre-defined driver like `tfp.experimental.mcmc.sample_fold`.
  `sample_fold` will automatically create the Transition Kernel onion, apply
  `kernel` samples to update reducer states, and `finalize` calculations.
  
  ```
  python
  
  kernel = ...
  reducer = tfp.experimental.mcmc.CovarianceReducer()
  covariance_estimate, _, _ = tfp.experimental.mcmc.sample_fold(
      num_steps=...,
      current_state=...,
      previous_kernel_results=...,
      kernel=kernel,
      reducers=reducer,
  )
  covariance_estimate  # estimate of covariance (not `CovarianceReducerState`)
  ```
docstr: Instantiates this object.
  
  The running covariance computation supports batching. The `event_ndims`
  parameter indicates the number of trailing dimensions to treat as part of
  the event, and to compute covariance across. The leading dimensions, if
  any, are treated as batch shape, and no cross terms are computed.
  
  For example, if the incoming samples have shape `[5, 7]`, the `event_ndims`
  selects among three different covariance computations:
  - `event_ndims=0` treats the samples as a `[5, 7]` batch of scalar random
    variables, and computes their variances in batch.  The shape of the result
    is `[5, 7]`.
  - `event_ndims=1` treats the samples as a `[5]` batch of vector random
    variables of shape `[7]`, and computes their covariances in batch.  The
    shape of the result is `[5, 7, 7]`.
  - `event_ndims=2` treats the samples as a single random variable of
    shape `[5, 7]` and computes its covariance.  The shape of the result
    is `[5, 7, 5, 7]`.
  
  For nested latent samples, both `event_ndims` and `ddof` must be either
  a single value or of identical structure to the chain state. For example,
  if the chain state is the tuple of dictionaries ({pairA, pairB}, {pairC}),
  one could use scalar values for `event_ndims` (integer or `None`) and
  `ddof` (integer) that apply to all states in the latent. If not,
  `event_ndims` and `ddof` must be structures that exactly mimic
  ({keyA: argA, keyB: argB}, {keyC: argC}) in composition.
  
  Args:
    event_ndims: A (possibly nested) structure of integers, or `None`. Defines
      the number of inner-most dimensions that represent the event shape.
      Specifying `None` returns all cross product terms (no batching)
      and is the default.
    transform_fn: A (possibly nested) structure of functions to evaluate the
      incoming chain states on before covariance calculation. The default is
      a single function that returns the chain state.
    ddof: A (possibly nested) structure of integers that represent the
      requested dynamic degrees of freedom. For example, use `ddof=0`
      for population covariance and `ddof=1` for sample covariance. Defaults
      to the population covariance.
    name: Python `str` name prefixed to Ops created by this function.
      Default value: `None` (i.e., 'covariance_reducer').
docstr_tok: ["Instantiates","this","object",".","The","running","covariance","computation","supports","batching",".","The","`","event_ndims","`","parameter","indicates","the","number","of","trailing","dimensions","to","treat","as","part","of","the","event",",","and","to","compute","covariance","across",".","The","leading","dimensions",",","if","any",",","are","treated","as","batch","shape",",","and","no","cross","terms","are","computed",".","For","example",",","if","the","incoming","samples","have","shape","`","[","5",",","7","]","`",",","the","`","event_ndims","`","selects","among","three","different","covariance","computations",":","-","`","event_ndims=0","`","treats","the","samples","as","a","`","[","5",",","7","]","`","batch","of","scalar","random","variables",",","and","computes","their","variances","in","batch",".","The","shape","of","the","result","is","`","[","5",",","7","]","`",".","-","`","event_ndims=1","`","treats","the","samples","as","a","`","[","5","]","`","batch","of","vector","random","variables","of","shape","`","[","7","]","`",",","and","computes","their","covariances","in","batch",".","The","shape","of","the","result","is","`","[","5",",","7",",","7","]","`",".","-","`","event_ndims=2","`","treats","the","samples","as","a","single","random","variable","of","shape","`","[","5",",","7","]","`","and","computes","its","covariance",".","The","shape","of","the","result","is","`","[","5",",","7",",","5",",","7","]","`",".","For","nested","latent","samples",",","both","`","event_ndims","`","and","`","ddof","`","must","be","either","a","single","value","or","of","identical","structure","to","the","chain","state",".","For","example",",","if","the","chain","state","is","the","tuple","of","dictionaries","(","{","pairA",",","pairB","}",",","{","pairC","}",")",",","one","could","use","scalar","values","for","`","event_ndims","`","(","integer","or","`","None","`",")","and","`","ddof","`","(","integer",")","that","apply","to","all","states","in","the","latent",".","If","not",",","`","event_ndims","`","and","`","ddof","`","must","be","structures","that","exactly","mimic","(","{","keyA",":","argA",",","keyB",":","argB","}",",","{","keyC",":","argC","}",")","in","composition",".","Args",":","event_ndims",":","A","(","possibly","nested",")","structure","of","integers",",","or","`","None","`",".","Defines","the","number","of","inner-most","dimensions","that","represent","the","event","shape",".","Specifying","`","None","`","returns","all","cross","product","terms","(","no","batching",")","and","is","the","default",".","transform_fn",":","A","(","possibly","nested",")","structure","of","functions","to","evaluate","the","incoming","chain","states","on","before","covariance","calculation",".","The","default","is","a","single","function","that","returns","the","chain","state",".","ddof",":","A","(","possibly","nested",")","structure","of","integers","that","represent","the","requested","dynamic","degrees","of","freedom",".","For","example",",","use","`","ddof=0","`","for","population","covariance","and","`","ddof=1","`","for","sample","covariance",".","Defaults","to","the","population","covariance",".","name",":","Python","`","str","`","name","prefixed","to","Ops","created","by","this","function",".","Default","value",":","`","None","`","(","i.e.",",","'covariance_reducer","'",")","."]
code: def __init__(
      self,
      event_ndims=None,
      transform_fn=_get_sample,
      ddof=0,
      name=None,
  ):
      """Instantiates this object.
  
      The running covariance computation supports batching. The `event_ndims`
      parameter indicates the number of trailing dimensions to treat as part of
      the event, and to compute covariance across. The leading dimensions, if
      any, are treated as batch shape, and no cross terms are computed.
  
      For example, if the incoming samples have shape `[5, 7]`, the `event_ndims`
      selects among three different covariance computations:
      - `event_ndims=0` treats the samples as a `[5, 7]` batch of scalar random
        variables, and computes their variances in batch.  The shape of the result
        is `[5, 7]`.
      - `event_ndims=1` treats the samples as a `[5]` batch of vector random
        variables of shape `[7]`, and computes their covariances in batch.  The
        shape of the result is `[5, 7, 7]`.
      - `event_ndims=2` treats the samples as a single random variable of
        shape `[5, 7]` and computes its covariance.  The shape of the result
        is `[5, 7, 5, 7]`.
  
      For nested latent samples, both `event_ndims` and `ddof` must be either
      a single value or of identical structure to the chain state. For example,
      if the chain state is the tuple of dictionaries ({pairA, pairB}, {pairC}),
      one could use scalar values for `event_ndims` (integer or `None`) and
      `ddof` (integer) that apply to all states in the latent. If not,
      `event_ndims` and `ddof` must be structures that exactly mimic
      ({keyA: argA, keyB: argB}, {keyC: argC}) in composition.
  
      Args:
        event_ndims: A (possibly nested) structure of integers, or `None`. Defines
          the number of inner-most dimensions that represent the event shape.
          Specifying `None` returns all cross product terms (no batching)
          and is the default.
        transform_fn: A (possibly nested) structure of functions to evaluate the
          incoming chain states on before covariance calculation. The default is
          a single function that returns the chain state.
        ddof: A (possibly nested) structure of integers that represent the
          requested dynamic degrees of freedom. For example, use `ddof=0`
          for population covariance and `ddof=1` for sample covariance. Defaults
          to the population covariance.
        name: Python `str` name prefixed to Ops created by this function.
          Default value: `None` (i.e., 'covariance_reducer').
      """
      self._parameters = dict(
          event_ndims=event_ndims,
          transform_fn=transform_fn,
          ddof=ddof,
          name=name or "covariance_reducer",
      )
  
imports: import collections
  import tensorflow.compat.v2
  from tensorflow_probability.python.experimental.mcmc import reducer
  from tensorflow_probability.python.experimental.stats import sample_stats
  from tensorflow_probability.python.internal import nest_util
  from tensorflow_probability.python.mcmc.internal import util
  from tensorflow.python.util import nest
label_desc: Use image node_id 1 to create a new CovarianceReducer object from inherited base classes: reducer_base with example: obj = CovarianceReducer(event_ndims, transform_fn, ddof, name)