class_docstr: Formal representation of a sparse linear regression.
  
  This model defines a time series given by a sparse linear combination of
  covariate time series provided in a design matrix:
  
  ```python
  observed_time_series = matmul(design_matrix, weights)
  ```
  
  This is identical to `tfp.sts.LinearRegression`, except that
  `SparseLinearRegression` uses a parameterization of a Horseshoe
  prior [1][2] to encode the assumption that many of the `weights` are zero,
  i.e., many of the covariate time series are irrelevant. See the mathematical
  details section below for further discussion. The prior parameterization used
  by `SparseLinearRegression` is more suitable for inference than that
  obtained by simply passing the equivalent `tfd.Horseshoe` prior to
  `LinearRegression`; when sparsity is desired, `SparseLinearRegression` will
  likely yield better results.
  
  This component does not itself include observation noise; it defines a
  deterministic distribution with mass at the point
  `matmul(design_matrix, weights)`. In practice, it should be combined with
  observation noise from another component such as `tfp.sts.Sum`, as
  demonstrated below.
  
  #### Examples
  
  Given `series1`, `series2` as `Tensors` each of shape `[num_timesteps]`
  representing covariate time series, we create a regression model that
  conditions on these covariates:
  
  ```python
  regression = tfp.sts.SparseLinearRegression(
    design_matrix=tf.stack([series1, series2], axis=-1),
    weights_prior_scale=0.1)
  ```
  
  The `weights_prior_scale` determines the level of sparsity; small
  scales encourage the weights to be sparse. In some cases, such as when
  the likelihood is iid Gaussian with known scale, the prior scale can be
  analytically related to the expected number of nonzero weights [2]; however,
  this is not the case in general for STS models.
  
  If the design matrix has batch dimensions, by default the model will create a
  matching batch of weights. For example, if `design_matrix.shape == [
  num_users, num_timesteps, num_features]`, by default the model will fit
  separate weights for each user, i.e., it will internally represent
  `weights.shape == [num_users, num_features]`. To share weights across some or
  all batch dimensions, you can manually specify the batch shape for the
  weights:
  
  ```python
  # design_matrix.shape == [num_users, num_timesteps, num_features]
  regression = tfp.sts.SparseLinearRegression(
    design_matrix=design_matrix,
    weights_batch_shape=[])  # weights.shape -> [num_features]
  ```
  
  #### Mathematical Details
  
  The basic horseshoe prior [1] is defined as a Cauchy-normal scale mixture:
  
  ```
  scales[i] ~ HalfCauchy(loc=0, scale=1)
  weights[i] ~ Normal(loc=0., scale=scales[i] * global_scale)`
  ```
  
  The Cauchy scale parameters puts substantial mass near zero, encouraging
  weights to be sparse, but their heavy tails allow weights far from zero to be
  estimated without excessive shrinkage. The horseshoe can be thought of as a
  continuous relaxation of a traditional 'spike-and-slab' discrete sparsity
  prior, in which the latent Cauchy scale mixes between 'spike'
  (`scales[i] ~= 0`) and 'slab' (`scales[i] >> 0`) regimes.
  
  Following the recommendations in [2], `SparseLinearRegression` implements
  a horseshoe with the following adaptations:
  
  - The Cauchy prior on `scales[i]` is represented as an InverseGamma-Normal
    compound.
  - The `global_scale` parameter is integrated out following a `Cauchy(0.,
    scale=weights_prior_scale)` hyperprior, which is also represented as an
    InverseGamma-Normal compound.
  - All compound distributions are implemented using a non-centered
    parameterization.
  
  The compound, non-centered representation defines the same marginal prior as
  the original horseshoe (up to integrating out the global scale),
  but allows samplers to mix more efficiently through the heavy tails; for
  variational inference, the compound representation implicity expands the
  representational power of the variational model.
  
  Note that we do not yet implement the regularized ('Finnish') horseshoe,
  proposed in [2] for models with weak likelihoods, because the likelihood
  in STS models is typically Gaussian, where it's not clear that additional
  regularization is appropriate. If you need this functionality, please
  email tfprobability@tensorflow.org.
  
  The full prior parameterization implemented in `SparseLinearRegression` is
  as follows:
  
  ```
  # Sample global_scale from Cauchy(0, scale=weights_prior_scale).
  global_scale_variance ~ InverseGamma(alpha=0.5, beta=0.5)
  global_scale_noncentered ~ HalfNormal(loc=0, scale=1)
  global_scale = (global_scale_noncentered *
                  sqrt(global_scale_variance) *
                  weights_prior_scale)
  
  # Sample local_scales from Cauchy(0, 1).
  local_scale_variances[i] ~ InverseGamma(alpha=0.5, beta=0.5)
  local_scales_noncentered[i] ~ HalfNormal(loc=0, scale=1)
  local_scales[i] = local_scales_noncentered[i] * sqrt(local_scale_variances[i])
  
  weights[i] ~ Normal(loc=0., scale=local_scales[i] * global_scale)
  ```
  
  #### References
  
  [1]: Carvalho, C., Polson, N. and Scott, J. Handling Sparsity via the
    Horseshoe. AISTATS (2009).
    http://proceedings.mlr.press/v5/carvalho09a/carvalho09a.pdf
  [2]: Juho Piironen, Aki Vehtari. Sparsity information and regularization in
    the horseshoe and other shrinkage priors (2017).
    https://arxiv.org/abs/1707.01694
class_docstr_tok: ["Formal","representation","of","a","sparse","linear","regression",".","This","model","defines","a","time","series","given","by","a","sparse","linear","combination","of","covariate","time","series","provided","in","a","design","matrix",":","``","`","python","observed_time_series","=","matmul","(","design_matrix",",","weights",")","``","`","This","is","identical","to","`","tfp.sts.LinearRegression","`",",","except","that","`","SparseLinearRegression","`","uses","a","parameterization","of","a","Horseshoe","prior","[","1","]","[","2","]","to","encode","the","assumption","that","many","of","the","`","weights","`","are","zero",",","i.e.",",","many","of","the","covariate","time","series","are","irrelevant",".","See","the","mathematical","details","section","below","for","further","discussion",".","The","prior","parameterization","used","by","`","SparseLinearRegression","`","is","more","suitable","for","inference","than","that","obtained","by","simply","passing","the","equivalent","`","tfd.Horseshoe","`","prior","to","`","LinearRegression","`",";","when","sparsity","is","desired",",","`","SparseLinearRegression","`","will","likely","yield","better","results",".","This","component","does","not","itself","include","observation","noise",";","it","defines","a","deterministic","distribution","with","mass","at","the","point","`","matmul","(","design_matrix",",","weights",")","`",".","In","practice",",","it","should","be","combined","with","observation","noise","from","another","component","such","as","`","tfp.sts.Sum","`",",","as","demonstrated","below",".","#","#","#","#","Examples","Given","`","series1","`",",","`","series2","`","as","`","Tensors","`","each","of","shape","`","[","num_timesteps","]","`","representing","covariate","time","series",",","we","create","a","regression","model","that","conditions","on","these","covariates",":","``","`","python","regression","=","tfp.sts.SparseLinearRegression","(","design_matrix=tf.stack","(","[","series1",",","series2","]",",","axis=-1",")",",","weights_prior_scale=0.1",")","``","`","The","`","weights_prior_scale","`","determines","the","level","of","sparsity",";","small","scales","encourage","the","weights","to","be","sparse",".","In","some","cases",",","such","as","when","the","likelihood","is","iid","Gaussian","with","known","scale",",","the","prior","scale","can","be","analytically","related","to","the","expected","number","of","nonzero","weights","[","2","]",";","however",",","this","is","not","the","case","in","general","for","STS","models",".","If","the","design","matrix","has","batch","dimensions",",","by","default","the","model","will","create","a","matching","batch","of","weights",".","For","example",",","if","`","design_matrix.shape","==","[","num_users",",","num_timesteps",",","num_features","]","`",",","by","default","the","model","will","fit","separate","weights","for","each","user",",","i.e.",",","it","will","internally","represent","`","weights.shape","==","[","num_users",",","num_features","]","`",".","To","share","weights","across","some","or","all","batch","dimensions",",","you","can","manually","specify","the","batch","shape","for","the","weights",":","``","`","python","#","design_matrix.shape","==","[","num_users",",","num_timesteps",",","num_features","]","regression","=","tfp.sts.SparseLinearRegression","(","design_matrix=design_matrix",",","weights_batch_shape=","[","]",")","#","weights.shape","-",">","[","num_features","]","``","`","#","#","#","#","Mathematical","Details","The","basic","horseshoe","prior","[","1","]","is","defined","as","a","Cauchy-normal","scale","mixture",":","``","`","scales","[","i","]","~","HalfCauchy","(","loc=0",",","scale=1",")","weights","[","i","]","~","Normal","(","loc=0.",",","scale=scales","[","i","]","*","global_scale",")","`","``","`","The","Cauchy","scale","parameters","puts","substantial","mass","near","zero",",","encouraging","weights","to","be","sparse",",","but","their","heavy","tails","allow","weights","far","from","zero","to","be","estimated","without","excessive","shrinkage",".","The","horseshoe","can","be","thought","of","as","a","continuous","relaxation","of","a","traditional","'spike-and-slab","'","discrete","sparsity","prior",",","in","which","the","latent","Cauchy","scale","mixes","between","'spike'","(","`","scales","[","i","]","~=","0","`",")","and","'slab","'","(","`","scales","[","i","]",">",">","0","`",")","regimes",".","Following","the","recommendations","in","[","2","]",",","`","SparseLinearRegression","`","implements","a","horseshoe","with","the","following","adaptations",":","-","The","Cauchy","prior","on","`","scales","[","i","]","`","is","represented","as","an","InverseGamma-Normal","compound",".","-","The","`","global_scale","`","parameter","is","integrated","out","following","a","`","Cauchy","(","0.",",","scale=weights_prior_scale",")","`","hyperprior",",","which","is","also","represented","as","an","InverseGamma-Normal","compound",".","-","All","compound","distributions","are","implemented","using","a","non-centered","parameterization",".","The","compound",",","non-centered","representation","defines","the","same","marginal","prior","as","the","original","horseshoe","(","up","to","integrating","out","the","global","scale",")",",","but","allows","samplers","to","mix","more","efficiently","through","the","heavy","tails",";","for","variational","inference",",","the","compound","representation","implicity","expands","the","representational","power","of","the","variational","model",".","Note","that","we","do","not","yet","implement","the","regularized","(","'Finnish","'",")","horseshoe",",","proposed","in","[","2","]","for","models","with","weak","likelihoods",",","because","the","likelihood","in","STS","models","is","typically","Gaussian",",","where","it","'s","not","clear","that","additional","regularization","is","appropriate",".","If","you","need","this","functionality",",","please","email","tfprobability","@","tensorflow.org",".","The","full","prior","parameterization","implemented","in","`","SparseLinearRegression","`","is","as","follows",":","``","`","#","Sample","global_scale","from","Cauchy","(","0",",","scale=weights_prior_scale",")",".","global_scale_variance","~","InverseGamma","(","alpha=0.5",",","beta=0.5",")","global_scale_noncentered","~","HalfNormal","(","loc=0",",","scale=1",")","global_scale","=","(","global_scale_noncentered","*","sqrt","(","global_scale_variance",")","*","weights_prior_scale",")","#","Sample","local_scales","from","Cauchy","(","0",",","1",")",".","local_scale_variances","[","i","]","~","InverseGamma","(","alpha=0.5",",","beta=0.5",")","local_scales_noncentered","[","i","]","~","HalfNormal","(","loc=0",",","scale=1",")","local_scales","[","i","]","=","local_scales_noncentered","[","i","]","*","sqrt","(","local_scale_variances","[","i","]",")","weights","[","i","]","~","Normal","(","loc=0.",",","scale=local_scales","[","i","]","*","global_scale",")","``","`","#","#","#","#","References","[","1","]",":","Carvalho",",","C.",",","Polson",",","N.","and","Scott",",","J",".","Handling","Sparsity","via","the","Horseshoe",".","AISTATS","(","2009",")",".","http",":","\/\/proceedings.mlr.press\/v5\/carvalho09a\/carvalho09a.pdf","[","2","]",":","Juho","Piironen",",","Aki","Vehtari",".","Sparsity","information","and","regularization","in","the","horseshoe","and","other","shrinkage","priors","(","2017",")",".","https",":","\/\/arxiv.org\/abs\/1707.01694"]
docstr: LinearOperator representing the design matrix.
docstr_tok: ["LinearOperator","representing","the","design","matrix","."]
code: def design_matrix(self):
      """LinearOperator representing the design matrix."""
      return self._design_matrix
  
imports: import tensorflow.compat.v2
  from tensorflow_probability.python.bijectors import identity
  from tensorflow_probability.python.bijectors import softplus
  from tensorflow_probability.python.distributions import half_normal
  from tensorflow_probability.python.distributions import independent
  from tensorflow_probability.python.distributions import inverse_gamma
  from tensorflow_probability.python.distributions import linear_gaussian_ssm
  from tensorflow_probability.python.distributions import mvn_diag
  from tensorflow_probability.python.distributions import normal
  from tensorflow_probability.python.distributions import sample
  from tensorflow_probability.python.distributions import student_t
  from tensorflow_probability.python.internal import distribution_util
  from tensorflow_probability.python.internal import dtype_util
  from tensorflow_probability.python.sts.structural_time_series import Parameter
  from tensorflow_probability.python.sts.structural_time_series import StructuralTimeSeries
label_desc: Use image node_id 2 for calling the SparseLinearRegression obj's underlying member method code with example usage: obj.design_matrix() and returns: self