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: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: Likelihood

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 parameters that define the probability distribution for one single target value.

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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, 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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

abstract likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

abstract property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

abstract simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`predict_likelihood_parameters`(model_output)	Overwrite the parent since the parameters are extracted in two steps.
`sample`(model_output)	Samples a prediction from the probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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.

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

Attributes

num_parameters

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

Methods

`compute_loss`(model_output, target, sample_weight)	We are re-defining a custom loss (which is not a likelihood loss) compared to Likelihood
`likelihood_components_names`(input_series)	Each component have their own quantiles
`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.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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)

likelihood_components_names(input_series)[source]¶

Each component have their own quantiles

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

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

Bases: 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

num_parameters

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

Methods

`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.
`likelihood_components_names`(input_series)	Generates names for the parameters of the Likelihood.
`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 probability distributions defined by the specific likelihood model and the parameters given in model_output.
`simplified_name`()	Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

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.

likelihood_components_names(input_series)[source]¶

Generates names for the parameters of the Likelihood.

Return type: List[str]

property num_parameters: int¶

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

Return type: int

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 probability distributions defined by the specific likelihood model and the parameters given in model_output.

Return type: Tensor

simplified_name()[source]¶

Returns a simplified name, used to compare Likelihood and LikelihoodMixin_ instances

Return type: str

PyTorch Loss Functions