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