# Likelihood Models¶

The likelihood models contain all the logic needed to train and use Darts’ neural network models in a probabilistic way. This essentially means computing an appropriate training loss and sample from the distribution, given the parameters of the distribution.

By default, all versions will be trained using their negative log likelihood as a loss function (hence performing maximum likelihood estimation when training the model). However, most likelihoods also optionally support specifying time-independent “prior” beliefs about the distribution parameters. In such cases, the a KL-divergence term is added to the loss in order to regularise it in the direction of the specified prior distribution. (Note that this is technically not purely a Bayesian approach as the priors are actual parameters values, and not distributions). The parameter prior_strength controls the strength of the “prior” regularisation on the loss.

Some distributions (such as GaussianLikelihood, and PoissonLikelihood) are univariate, in which case they are applied to model each component of multivariate series independently. Some other distributions (such as DirichletLikelihood) are multivariate, in which case they will model all components of multivariate time series jointly.

Univariate likelihoods accept either scalar or array-like values for the optional prior parameters. If a scalar is provided, it is used as a prior for all components of the series. If an array-like is provided, the i-th value will be used as a prior for the i-th component of the series. Multivariate likelihoods require array-like objects when specifying priors.

The target series used for training must always lie within the distribution’s support, otherwise errors will be raised during training. You can refer to the individual likelihoods’ documentation to see what is the support. Similarly, the prior parameters also have to lie in some pre-defined domains.

class darts.utils.likelihood_models.BernoulliLikelihood(prior_p=None, prior_strength=1.0)[source]

Bernoulli distribution.

https://en.wikipedia.org/wiki/Bernoulli_distribution

• Univariate discrete distribution.

• Support: $$\{0, 1\}$$.

• Parameter: probability $$p \in (0, 1)$$.

Parameters
• prior_p – probability $$p$$ of the prior Bernoulli distribution (default: None)

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.BetaLikelihood(prior_alpha=None, prior_beta=None, prior_strength=1.0)[source]

Beta distribution.

https://en.wikipedia.org/wiki/Beta_distribution

• Univariate continuous distribution.

• Support: open interval $$(0,1)$$

• Parameters: shape parameters $$\alpha > 0$$ and $$\beta > 0$$.

Parameters
• prior_alpha – shape parameter $$\alpha$$ of the Beta distribution, strictly positive (default: None)

• prior_beta – shape parameter $$\beta$$ distribution, strictly positive (default: None)

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.CauchyLikelihood(prior_xzero=None, prior_gamma=None, prior_strength=1.0)[source]

Cauchy Distribution.

https://en.wikipedia.org/wiki/Cauchy_distribution

• Univariate continuous distribution.

• Support: $$\mathbb{R}$$.

• Parameters: location $$x_0 \in \mathbb{R}$$, scale $$\gamma > 0$$.

Due to its fat tails, this distribution is typically harder to estimate, and your mileage may vary. Also be aware that it typically requires a large value for num_samples for sampling predictions.

Parameters
• prior_xzero – location parameter $$x_0$$ of the Cauchy distribution (default: None)

• prior_gamma – scale parameter $$\gamma$$ of the Cauchy distribution, strictly positive (default: None)

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.ContinuousBernoulliLikelihood(prior_lambda=None, prior_strength=1.0)[source]

Continuous Bernoulli distribution.

https://en.wikipedia.org/wiki/Continuous_Bernoulli_distribution

• Univariate continuous distribution.

• Support: open interval $$(0, 1)$$.

• Parameter: shape $$\lambda \in (0,1)$$

Parameters
• prior_lambda – shape $$\lambda$$ of the prior Continuous Bernoulli distribution (default: None)

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.DirichletLikelihood(prior_alphas=None, prior_strength=1.0)[source]

Dirichlet distribution.

https://en.wikipedia.org/wiki/Dirichlet_distribution

• Multivariate continuous distribution, modeling all components of a time series jointly.

• Support: The $$K$$-dimensional simplex for series of dimension $$K$$, i.e., $$x_1, ..., x_K \text{ with } x_i \in (0,1),\; \sum_i^K{x_i}=1$$.

• Parameter: concentrations $$\alpha_1, ..., \alpha_K$$ with $$\alpha_i > 0$$.

Parameters
• prior_alphas – concentrations parameters $$\alpha$$ of the prior Dirichlet distribution.

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.ExponentialLikelihood(prior_lambda=None, prior_strength=1.0)[source]

Exponential distribution.

https://en.wikipedia.org/wiki/Exponential_distribution

• Univariate continuous distribution.

• Support: $$\mathbb{R}_{>0}$$.

• Parameter: rate $$\lambda > 0$$.

Parameters
• prior_lambda – rate $$\lambda$$ of the prior exponential distribution (default: None).

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.GammaLikelihood(prior_alpha=None, prior_beta=None, prior_strength=1.0)[source]

Gamma distribution.

https://en.wikipedia.org/wiki/Gamma_distribution

• Univariate continuous distribution

• Support: $$\mathbb{R}_{>0}$$.

• Parameters: shape $$\alpha > 0$$ and rate $$\beta > 0$$.

Parameters
• prior_alpha – shape $$\alpha$$ of the prior gamma distribution (default: None).

• prior_beta – rate $$\beta$$ of the prior gamma distribution (default: None).

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.GaussianLikelihood(prior_mu=None, prior_sigma=None, prior_strength=1.0)[source]

Univariate Gaussian distribution.

https://en.wikipedia.org/wiki/Normal_distribution

• Univariate continuous distribution.

• Support: $$\mathbb{R}$$.

• Parameters: mean $$\mu \in \mathbb{R}$$, standard deviation $$\sigma > 0$$.

Parameters
• prior_mu – mean of the prior Gaussian distribution (default: None).

• prior_sigma – standard deviation (or scale) of the prior Gaussian distribution (default: None)

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.GeometricLikelihood(prior_p=None, prior_strength=1.0)[source]

Geometric distribution.

https://en.wikipedia.org/wiki/Geometric_distribution

• Univariate discrete distribution

• Support: $$\mathbb{N}_0$$ (natural numbers including 0).

• Parameter: success probability $$p \in (0, 1)$$.

Parameters
• prior_p – success probability $$p$$ of the prior geometric distribution (default: None)

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

class darts.utils.likelihood_models.GumbelLikelihood(prior_mu=None, prior_beta=None, prior_strength=1.0)[source]

Gumbel distribution.

https://en.wikipedia.org/wiki/Gumbel_distribution

• Univariate continuous distribution

• Support: $$\mathbb{R}$$.

• Parameters: location $$\mu \in \mathbb{R}$$ and scale $$\beta > 0$$.

Parameters
• prior_mu – location $$\mu$$ of the prior Gumbel distribution (default: None).

• prior_beta – scale $$\beta$$ of the prior Gumbel distribution (default: None).

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

class darts.utils.likelihood_models.HalfNormalLikelihood(prior_sigma=None, prior_strength=1.0)[source]

Half-normal distribution.

https://en.wikipedia.org/wiki/Half-normal_distribution

• Univariate continuous distribution.

• Support: $$\mathbb{R}_{>0}$$.

• Parameter: rate $$\sigma > 0$$.

Parameters
• prior_sigma – standard deviation $$\sigma$$ of the prior half-normal distribution (default: None).

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.LaplaceLikelihood(prior_mu=None, prior_b=None, prior_strength=1.0)[source]

Laplace distribution.

https://en.wikipedia.org/wiki/Laplace_distribution

• Univariate continuous distribution

• Support: $$\mathbb{R}$$.

• Parameters: location $$\mu \in \mathbb{R}$$ and scale $$b > 0$$.

Parameters
• prior_mu – location $$\mu$$ of the prior Laplace distribution (default: None).

• prior_b – scale $$b$$ of the prior Laplace distribution (default: None).

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

class darts.utils.likelihood_models.Likelihood(prior_strength=1.0)[source]

Bases: abc.ABC

Abstract class for a likelihood model.

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)[source]

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

abstract property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

abstract sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.LogNormalLikelihood(prior_mu=None, prior_sigma=None, prior_strength=1.0)[source]

Log-normal distribution.

https://en.wikipedia.org/wiki/Log-normal_distribution

• Univariate continuous distribution.

• Support: $$\mathbb{R}_{>0}$$.

• Parameters: $$\mu \in \mathbb{R}$$ and $$\sigma > 0$$.

Parameters
• prior_mu – parameter $$\mu$$ of the prior log-normal distribution (default: None).

• prior_sigma – parameter $$\sigma$$ of the prior log-normal distribution (default: None)

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.NegativeBinomialLikelihood[source]

Negative Binomial distribution.

https://en.wikipedia.org/wiki/Negative_binomial_distribution

It does not support priors.

• Univariate discrete distribution.

• Support: $$\mathbb{N}_0$$ (natural numbers including 0).

• Parameters: number of failures $$r > 0$$, success probability $$p \in (0, 1)$$.

Behind the scenes the distribution is reparameterized so that the actual outputs of the network are in terms of the mean $$\mu$$ and shape $$\alpha$$.

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

class darts.utils.likelihood_models.PoissonLikelihood(prior_lambda=None, prior_strength=1.0)[source]

Poisson distribution. Can typically be used to model event counts during time intervals, when the events happen independently of the time since the last event.

https://en.wikipedia.org/wiki/Poisson_distribution

• Univariate discrete distribution

• Support: $$\mathbb{N}_0$$ (natural numbers including 0).

• Parameter: rate $$\lambda > 0$$.

Parameters
• prior_lambda – rate $$\lambda$$ of the prior Poisson distribution (default: None)

• prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type

Tensor

class darts.utils.likelihood_models.QuantileRegression(quantiles=None)[source]

The “likelihood” corresponding to quantile regression. It uses the Quantile Loss Metric for custom quantiles centered around q=0.5.

This class can be used as any other Likelihood objects even though it is not representing the likelihood of a well defined distribution.

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) We are re-defining a custom loss (which is not a likelihood loss) compared to Likelihood sample(model_output) Sample uniformly between [0, 1] (for each batch example) and return the linear interpolation between the fitted quantiles closest to the sampled value.
compute_loss(model_output, target)[source]

We are re-defining a custom loss (which is not a likelihood loss) compared to Likelihood

Parameters
• model_output (Tensor) – must be of shape (batch_size, n_timesteps, n_target_variables, n_quantiles)

• target (Tensor) – must be of shape (n_samples, n_timesteps, n_target_variables)

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Sample uniformly between [0, 1] (for each batch example) and return the linear interpolation between the fitted quantiles closest to the sampled value.

model_output is of shape (batch_size, n_timesteps, n_components, n_quantiles)

Return type

Tensor

class darts.utils.likelihood_models.WeibullLikelihood(prior_strength=1.0)[source]

Weibull distribution.

https://en.wikipedia.org/wiki/Weibull_distribution

• Univariate continuous distribution

• Support: $$\mathbb{R}_{>0}$$.

• Parameters: scale $$\lambda > 0$$ and concentration $$k > 0$$.

It does not support priors.

Parameters

prior_strength – strength of the loss regularisation induced by the prior

Attributes

 num_parameters Returns the number of parameters that define the probability distribution for one single target value.

Methods

 compute_loss(model_output, target) Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself. sample(model_output) Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
compute_loss(model_output, target)

Computes a loss from a model_output, which represents the parameters of a given probability distribution for every ground truth value in target, and the target itself.

property num_parameters: int

Returns the number of parameters that define the probability distribution for one single target value.

Return type

int

sample(model_output)[source]

Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.