Likelihoods for TorchForecastingModel¶

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 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.torch.BernoulliLikelihood(prior_p=None, prior_strength=1.0)[source]¶

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)[source]¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

Univariate Gaussian distribution.

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

Instead of the pure negative log likelihood (NLL) loss, the loss function used is the \(\beta\)-NLL loss [1], parameterized by beta_nll in (0, 1). For beta_nll=0 it is equivalent to NLL, however larger values of beta_nll can mitigate issues with NLL causing effective under-sampling of poorly fit regions during training. beta_nll=1 provides the same gradient for the mean as the MSE loss.

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
beta_nll – The parameter \(0 \leq \beta \leq 1\) of the \(\beta\)-NLL loss [1]. Default: 0. (equivalent to NLL)

References

1(1,2): Seitzer et al., “On the Pitfalls of Heteroscedastic Uncertainty Estimation with Probabilistic Neural Networks” https://arxiv.org/abs/2203.09168

Attributes

`num_parameters`	Returns the number of distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

class darts.utils.likelihood_models.torch.NegativeBinomialLikelihood[source]¶

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Overwrite the parent since the parameters are extracted in two steps.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)[source]¶

Overwrite the parent since the parameters are extracted in two steps.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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.

Parameters: quantiles (Optional[list[float], None]) – list of quantiles

Attributes

`num_parameters`	Returns the number of distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	We are re-defining a custom loss (which is not a likelihood loss) compared to Likelihood
`predict_likelihood_parameters`(model_output)	Overwrite parent method since QuantileRegression is not a Likelihood per-se and parameters must be extracted differently.
`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.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)[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)
sample_weight (Tensor) – must be of shape (n_samples, n_timesteps, n_target_variables)

property num_parameters: int¶

Returns the number of distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)[source]¶

Overwrite parent method since QuantileRegression is not a Likelihood per-se and parameters must be extracted differently.

Return type: Tensor

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

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

class darts.utils.likelihood_models.torch.TorchLikelihood(likelihood_type, parameter_names, prior_strength=1.0)[source]¶

Bases: Likelihood, ABC

Abstract class for torch likelihood models.

Parameters

likelihood_type (LikelihoodType) – A pre-defined LikelihoodType.
parameter_names (list[str]) – The likelihood (distribution) parameter names.
prior_strength – strength of the loss regularisation induced by the prior

Attributes

`num_parameters`	Returns the number of distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)[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.

property num_parameters: int¶

Returns the number of distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)[source]¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

abstract sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

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

Bases: TorchLikelihood

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 distribution parameters for a single target value.
`parameter_names`	Returns the likelihood parameter names.
`type`	Returns the likelihood type.

Methods

`component_names`(input_series)	Generates names for the parameters of the Likelihood.
`compute_loss`(model_output, target, sample_weight)	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.
`predict_likelihood_parameters`(model_output)	Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.
`sample`(model_output)	Samples a prediction from the likelihood distribution and the predicted parameters.

component_names(input_series)¶

Generates names for the parameters of the Likelihood.

Return type: list[str]

compute_loss(model_output, target, sample_weight)¶: 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 distribution parameters for a single target value.

Return type: int

property parameter_names: list[str]¶

Returns the likelihood parameter names.

Return type: list[str]

predict_likelihood_parameters(model_output)¶

Returns the distribution parameters as a single Tensor, extracted from the raw model outputs.

Return type: Tensor

sample(model_output)[source]¶

Samples a prediction from the likelihood distribution and the predicted parameters.

Return type: Tensor

property type: LikelihoodType¶

Returns the likelihood type.

Return type: LikelihoodType

Likelihoods for StatsForecast Models