class_docstr: Marginal distribution of a Student's T process at finitely many points.
  
  A Student's T process (TP) is an indexed collection of random variables, any
  finite collection of which are jointly Multivariate Student's T. While this
  definition applies to finite index sets, it is typically implicit that the
  index set is infinite; in applications, it is often some finite dimensional
  real or complex vector space. In such cases, the TP may be thought of as a
  distribution over (real- or complex-valued) functions defined over the index
  set.
  
  Just as Student's T distributions are fully specified by their degrees of
  freedom, location and scale, a Student's T process can be completely specified
  by a degrees of freedom parameter, mean function and covariance function.
  Let `S` denote the index set and `K` the space in
  which each indexed random variable takes its values (again, often R or C).
  The mean function is then a map `m: S -> K`, and the covariance function,
  or kernel, is a positive-definite function `k: (S x S) -> K`. The properties
  of functions drawn from a TP are entirely dictated (up to translation) by
  the form of the kernel function.
  
  This `Distribution` represents the marginal joint distribution over function
  values at a given finite collection of points `[x[1], ..., x[N]]` from the
  index set `S`. By definition, this marginal distribution is just a
  multivariate Student's T distribution, whose mean is given by the vector
  `[ m(x[1]), ..., m(x[N]) ]` and whose covariance matrix is constructed from
  pairwise applications of the kernel function to the given inputs:
  
  ```none
      | k(x[1], x[1])    k(x[1], x[2])  ...  k(x[1], x[N]) |
      | k(x[2], x[1])    k(x[2], x[2])  ...  k(x[2], x[N]) |
      |      ...              ...                 ...      |
      | k(x[N], x[1])    k(x[N], x[2])  ...  k(x[N], x[N]) |
  ```
  
  For this to be a valid covariance matrix, it must be symmetric and positive
  definite; hence the requirement that `k` be a positive definite function
  (which, by definition, says that the above procedure will yield PD matrices).
  
  Note also we use a parameterization as suggested in [1], which requires `df`
  to be greater than 2. This allows for the covariance for any finite
  dimensional marginal of the TP (a multivariate Student's T distribution) to
  just be the PD matrix generated by the kernel.
  
  
  #### Mathematical Details
  
  The probability density function (pdf) is a multivariate Student's T whose
  parameters are derived from the TP's properties:
  
  ```none
  pdf(x; df, index_points, mean_fn, kernel) = MultivariateStudentT(df, loc, K)
  K = (df - 2) / df  * (kernel.matrix(index_points, index_points) +
       observation_noise_variance * eye(N))
  loc = (x - mean_fn(index_points))^T @ K @ (x - mean_fn(index_points))
  ```
  
  where:
  
  * `df` is the degrees of freedom parameter for the TP.
  * `index_points` are points in the index set over which the TP is defined,
  * `mean_fn` is a callable mapping the index set to the TP's mean values,
  * `kernel` is `PositiveSemidefiniteKernel`-like and represents the covariance
    function of the TP,
  * `observation_noise_variance` is a term added to the diagonal of the kernel
    matrix. In the limit of `df` to `inf`, this represents the observation noise
    of a gaussian likelihood.
  * `eye(N)` is an N-by-N identity matrix.
  
  #### Examples
  
  ##### Draw joint samples from a TP prior
  
  ```python
  import numpy as np
  import tensorflow.compat.v2 as tf
  import tensorflow_probability as tfp
  
  tfd = tfp.distributions
  psd_kernels = tfp.math.psd_kernels
  
  num_points = 100
  # Index points should be a collection (100, here) of feature vectors. In this
  # example, we're using 1-d vectors, so we just need to reshape the output from
  # np.linspace, to give a shape of (100, 1).
  index_points = np.expand_dims(np.linspace(-1., 1., num_points), -1)
  
  # Define a kernel with default parameters.
  kernel = psd_kernels.ExponentiatedQuadratic()
  
  tp = tfd.StudentTProcess(3., kernel, index_points)
  
  samples = tp.sample(10)
  # ==> 10 independently drawn, joint samples at `index_points`
  
  noisy_tp = tfd.StudentTProcess(
      df=3.,
      kernel=kernel,
      index_points=index_points)
  noisy_samples = noisy_tp.sample(10)
  # ==> 10 independently drawn, noisy joint samples at `index_points`
  ```
  
  ##### Optimize kernel parameters via maximum marginal likelihood.
  
  ```python
  # Suppose we have some data from a known function. Note the index points in
  # general have shape `[b1, ..., bB, f1, ..., fF]` (here we assume `F == 1`),
  # so we need to explicitly consume the feature dimensions (just the last one
  # here).
  f = lambda x: np.sin(10*x[..., 0]) * np.exp(-x[..., 0]**2)
  observed_index_points = np.expand_dims(np.random.uniform(-1., 1., 50), -1)
  # Squeeze to take the shape from [50, 1] to [50].
  observed_values = f(observed_index_points)
  
  amplitude = tfp.util.TransformedVariable(
      1., tfp.bijectors.Softplus(), dtype=np.float64, name='amplitude')
  length_scale = tfp.util.TransformedVariable(
      1., tfp.bijectors.Softplus(), dtype=np.float64, name='length_scale')
  
  # Define a kernel with trainable parameters.
  kernel = psd_kernels.ExponentiatedQuadratic(
      amplitude=amplitude,
      length_scale=length_scale)
  
  tp = tfd.StudentTProcess(3., kernel, observed_index_points)
  
  optimizer = tf_keras.optimizers.Adam()
  
  @tf.function
  def optimize():
    with tf.GradientTape() as tape:
      loss = -tp.log_prob(observed_values)
    grads = tape.gradient(loss, tp.trainable_variables)
    optimizer.apply_gradients(zip(grads, tp.trainable_variables))
    return loss
  
  for i in range(1000):
    nll = optimize()
    if i % 100 == 0:
      print("Step {}: NLL = {}".format(i, nll))
  print("Final NLL = {}".format(nll))
  ```
  
  #### References
  
  [1]: Amar Shah, Andrew Gordon Wilson, and Zoubin Ghahramani. Student-t
       Processes as Alternatives to Gaussian Processes. In _Artificial
       Intelligence and Statistics_, 2014.
       https://www.cs.cmu.edu/~andrewgw/tprocess.pdf
class_docstr_tok: ["Marginal","distribution","of","a","Student","'s","T","process","at","finitely","many","points",".","A","Student","'s","T","process","(","TP",")","is","an","indexed","collection","of","random","variables",",","any","finite","collection","of","which","are","jointly","Multivariate","Student","'s","T.","While","this","definition","applies","to","finite","index","sets",",","it","is","typically","implicit","that","the","index","set","is","infinite",";","in","applications",",","it","is","often","some","finite","dimensional","real","or","complex","vector","space",".","In","such","cases",",","the","TP","may","be","thought","of","as","a","distribution","over","(","real-","or","complex-valued",")","functions","defined","over","the","index","set",".","Just","as","Student","'s","T","distributions","are","fully","specified","by","their","degrees","of","freedom",",","location","and","scale",",","a","Student","'s","T","process","can","be","completely","specified","by","a","degrees","of","freedom","parameter",",","mean","function","and","covariance","function",".","Let","`","S","`","denote","the","index","set","and","`","K","`","the","space","in","which","each","indexed","random","variable","takes","its","values","(","again",",","often","R","or","C",")",".","The","mean","function","is","then","a","map","`","m",":","S","-",">","K","`",",","and","the","covariance","function",",","or","kernel",",","is","a","positive-definite","function","`","k",":","(","S","x","S",")","-",">","K","`",".","The","properties","of","functions","drawn","from","a","TP","are","entirely","dictated","(","up","to","translation",")","by","the","form","of","the","kernel","function",".","This","`","Distribution","`","represents","the","marginal","joint","distribution","over","function","values","at","a","given","finite","collection","of","points","`","[","x","[","1","]",",","...",",","x","[","N","]","]","`","from","the","index","set","`","S","`",".","By","definition",",","this","marginal","distribution","is","just","a","multivariate","Student","'s","T","distribution",",","whose","mean","is","given","by","the","vector","`","[","m","(","x","[","1","]",")",",","...",",","m","(","x","[","N","]",")","]","`","and","whose","covariance","matrix","is","constructed","from","pairwise","applications","of","the","kernel","function","to","the","given","inputs",":","``","`","none","|","k","(","x","[","1","]",",","x","[","1","]",")","k","(","x","[","1","]",",","x","[","2","]",")","...","k","(","x","[","1","]",",","x","[","N","]",")","|","|","k","(","x","[","2","]",",","x","[","1","]",")","k","(","x","[","2","]",",","x","[","2","]",")","...","k","(","x","[","2","]",",","x","[","N","]",")","|","|","...","...","...","|","|","k","(","x","[","N","]",",","x","[","1","]",")","k","(","x","[","N","]",",","x","[","2","]",")","...","k","(","x","[","N","]",",","x","[","N","]",")","|","``","`","For","this","to","be","a","valid","covariance","matrix",",","it","must","be","symmetric","and","positive","definite",";","hence","the","requirement","that","`","k","`","be","a","positive","definite","function","(","which",",","by","definition",",","says","that","the","above","procedure","will","yield","PD","matrices",")",".","Note","also","we","use","a","parameterization","as","suggested","in","[","1","]",",","which","requires","`","df","`","to","be","greater","than","2",".","This","allows","for","the","covariance","for","any","finite","dimensional","marginal","of","the","TP","(","a","multivariate","Student","'s","T","distribution",")","to","just","be","the","PD","matrix","generated","by","the","kernel",".","#","#","#","#","Mathematical","Details","The","probability","density","function","(","pdf",")","is","a","multivariate","Student","'s","T","whose","parameters","are","derived","from","the","TP","'s","properties",":","``","`","none","pdf","(","x",";","df",",","index_points",",","mean_fn",",","kernel",")","=","MultivariateStudentT","(","df",",","loc",",","K",")","K","=","(","df","-","2",")","\/","df","*","(","kernel.matrix","(","index_points",",","index_points",")","+","observation_noise_variance","*","eye","(","N",")",")","loc","=","(","x","-","mean_fn","(","index_points",")",")","^T","@","K","@","(","x","-","mean_fn","(","index_points",")",")","``","`","where",":","*","`","df","`","is","the","degrees","of","freedom","parameter","for","the","TP",".","*","`","index_points","`","are","points","in","the","index","set","over","which","the","TP","is","defined",",","*","`","mean_fn","`","is","a","callable","mapping","the","index","set","to","the","TP","'s","mean","values",",","*","`","kernel","`","is","`","PositiveSemidefiniteKernel","`","-like","and","represents","the","covariance","function","of","the","TP",",","*","`","observation_noise_variance","`","is","a","term","added","to","the","diagonal","of","the","kernel","matrix",".","In","the","limit","of","`","df","`","to","`","inf","`",",","this","represents","the","observation","noise","of","a","gaussian","likelihood",".","*","`","eye","(","N",")","`","is","an","N-by-N","identity","matrix",".","#","#","#","#","Examples","#","#","#","#","#","Draw","joint","samples","from","a","TP","prior","``","`","python","import","numpy","as","np","import","tensorflow.compat.v2","as","tf","import","tensorflow_probability","as","tfp","tfd","=","tfp.distributions","psd_kernels","=","tfp.math.psd_kernels","num_points","=","100","#","Index","points","should","be","a","collection","(","100",",","here",")","of","feature","vectors",".","In","this","#","example",",","we","'re","using","1-d","vectors",",","so","we","just","need","to","reshape","the","output","from","#","np.linspace",",","to","give","a","shape","of","(","100",",","1",")",".","index_points","=","np.expand_dims","(","np.linspace","(","-1.",",","1.",",","num_points",")",",","-1",")","#","Define","a","kernel","with","default","parameters",".","kernel","=","psd_kernels.ExponentiatedQuadratic","(",")","tp","=","tfd.StudentTProcess","(","3.",",","kernel",",","index_points",")","samples","=","tp.sample","(","10",")","#","==",">","10","independently","drawn",",","joint","samples","at","`","index_points","`","noisy_tp","=","tfd.StudentTProcess","(","df=3.",",","kernel=kernel",",","index_points=index_points",")","noisy_samples","=","noisy_tp.sample","(","10",")","#","==",">","10","independently","drawn",",","noisy","joint","samples","at","`","index_points","`","``","`","#","#","#","#","#","Optimize","kernel","parameters","via","maximum","marginal","likelihood",".","``","`","python","#","Suppose","we","have","some","data","from","a","known","function",".","Note","the","index","points","in","#","general","have","shape","`","[","b1",",","...",",","bB",",","f1",",","...",",","fF","]","`","(","here","we","assume","`","F","==","1","`",")",",","#","so","we","need","to","explicitly","consume","the","feature","dimensions","(","just","the","last","one","#","here",")",".","f","=","lambda","x",":","np.sin","(","10","*","x","[","...",",","0","]",")","*","np.exp","(","-x","[","...",",","0","]","*","*","2",")","observed_index_points","=","np.expand_dims","(","np.random.uniform","(","-1.",",","1.",",","50",")",",","-1",")","#","Squeeze","to","take","the","shape","from","[","50",",","1","]","to","[","50","]",".","observed_values","=","f","(","observed_index_points",")","amplitude","=","tfp.util.TransformedVariable","(","1.",",","tfp.bijectors.Softplus","(",")",",","dtype=np.float64",",","name='amplitude","'",")","length_scale","=","tfp.util.TransformedVariable","(","1.",",","tfp.bijectors.Softplus","(",")",",","dtype=np.float64",",","name='length_scale","'",")","#","Define","a","kernel","with","trainable","parameters",".","kernel","=","psd_kernels.ExponentiatedQuadratic","(","amplitude=amplitude",",","length_scale=length_scale",")","tp","=","tfd.StudentTProcess","(","3.",",","kernel",",","observed_index_points",")","optimizer","=","tf_keras.optimizers.Adam","(",")","@","tf.function","def","optimize","(",")",":","with","tf.GradientTape","(",")","as","tape",":","loss","=","-tp.log_prob","(","observed_values",")","grads","=","tape.gradient","(","loss",",","tp.trainable_variables",")","optimizer.apply_gradients","(","zip","(","grads",",","tp.trainable_variables",")",")","return","loss","for","i","in","range","(","1000",")",":","nll","=","optimize","(",")","if","i","%","100","==","0",":","print","(","``","Step","{","}",":","NLL","=","{","}","''",".format","(","i",",","nll",")",")","print","(","``","Final","NLL","=","{","}","''",".format","(","nll",")",")","``","`","#","#","#","#","References","[","1","]",":","Amar","Shah",",","Andrew","Gordon","Wilson",",","and","Zoubin","Ghahramani",".","Student-t","Processes","as","Alternatives","to","Gaussian","Processes",".","In","_Artificial","Intelligence","and","Statistics_",",","2014.","https",":","\/\/www.cs.cmu.edu\/~andrewgw\/tprocess.pdf"]
code: def _stddev(self, index_points=None):
      return tf.sqrt(self._variance(index_points=index_points))
  
imports: import functools
  import warnings
  import numpy
  import tensorflow.compat.v2
  from tensorflow_probability.python.bijectors import identity
  from tensorflow_probability.python.bijectors import softplus
  from tensorflow_probability.python.distributions import cholesky_util
  from tensorflow_probability.python.distributions import distribution
  from tensorflow_probability.python.distributions import multivariate_student_t
  from tensorflow_probability.python.distributions.internal import stochastic_process_util
  from tensorflow_probability.python.internal import assert_util
  from tensorflow_probability.python.internal import batch_shape_lib
  from tensorflow_probability.python.internal import distribution_util
  from tensorflow_probability.python.internal import dtype_util
  from tensorflow_probability.python.internal import nest_util
  from tensorflow_probability.python.internal import parameter_properties
  from tensorflow_probability.python.internal import prefer_static
  from tensorflow_probability.python.internal import reparameterization
  from tensorflow_probability.python.internal import tensor_util
  from tensorflow_probability.python.math import linalg
  from tensorflow_probability.python.math import special
  from tensorflow.python.util import deprecation
  from tensorflow.python.util import nest
label_desc: Use image node_id 25 for calling the StudentTProcess obj's underlying member method code with example usage: obj._stddev(index_points) and returns: tf