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]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.BetaLikelihood(prior_alpha=None, prior_beta=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.CauchyLikelihood(prior_xzero=None, prior_gamma=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.ContinuousBernoulliLikelihood(prior_lambda=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.DirichletLikelihood(prior_alphas=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.ExponentialLikelihood(prior_lambda=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.GammaLikelihood(prior_alpha=None, prior_beta=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.GaussianLikelihood(prior_mu=None, prior_sigma=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.GeometricLikelihood(prior_p=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.GumbelLikelihood(prior_mu=None, prior_beta=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.HalfNormalLikelihood(prior_sigma=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.LaplaceLikelihood(prior_mu=None, prior_b=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.Likelihood(prior_strength=1.0)[source]¶
Bases:
abc.ABC
Abstract class for a likelihood model.
Attributes
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
- class darts.utils.likelihood_models.LogNormalLikelihood(prior_mu=None, prior_sigma=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.NegativeBinomialLikelihood[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.PoissonLikelihood(prior_lambda=None, prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.QuantileRegression(quantiles=None)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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
- class darts.utils.likelihood_models.WeibullLikelihood(prior_strength=1.0)[source]¶
Bases:
darts.utils.likelihood_models.Likelihood
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
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