Probabilistic Methods

Scenario-weighting helpers reside in pyvallocation.probabilities. Utilities cover uniform and exponentially decaying weights, kernel-based probabilities, and effective scenario counts. They are routinely used before feeding data into pyvallocation.moments.estimate_moments() or the entropy pooling solvers.

pyvallocation.probabilities.compute_effective_number_scenarios(probabilities)[source]

Return the effective number of scenarios (entropy-based).

Computes the exponential of the Shannon entropy of the probability vector, following Meucci (2012) and Vorobets (2025, Eq. 5.1.3):

\[\hat{S} = \exp\left\{-\sum_{s=1}^{S} q_s \ln q_s\right\}.\]

Equals S when probabilities are uniform and approaches 1 when all mass is concentrated on a single scenario. Uses the convention \(0 \ln 0 = 0\).

Parameters:

probabilities – Probability vector.

Returns:

float – Effective number of scenarios.

Parameters:

probabilities (numpy.ndarray)

Return type:

float

See also

compute_effective_number_scenarios_hhi() for the Herfindahl-based alternative \(1 / \sum p_s^2\).

References

[Meucci, 2012]

pyvallocation.probabilities.compute_effective_number_scenarios_hhi(probabilities)[source]

Return the Herfindahl-based effective number of scenarios.

Computes \(1 / \sum p_s^2\) (inverse Herfindahl-Hirschman index). This is an alternative concentration measure that differs numerically from the entropy-based definition in compute_effective_number_scenarios().

Parameters:

probabilities – Probability vector.

Returns:

float – Herfindahl-based effective number of scenarios.

Parameters:

probabilities (numpy.ndarray)

Return type:

float

pyvallocation.probabilities.generate_exp_decay_probabilities(num_observations, half_life)[source]

Return exponentially decaying probabilities with the given half_life.

Parameters:

  • num_observations – Number of scenarios.

  • half_life – Half-life (in observations) controlling decay speed.

Returns:

np.ndarray – Exponentially decaying probabilities summing to one.

Parameters:

  • num_observations (int)

  • half_life (int)

Return type:

numpy.ndarray

pyvallocation.probabilities.generate_gaussian_kernel_probabilities(x, v=None, h=None, x_T=None)[source]

Generate kernel-based probabilities for v centred on x_T.

Parameters:

  • x – Reference data used to estimate the bandwidth when h is None.

  • v – Values to score. Defaults to x.

  • h – Kernel bandwidth. Defaults to Silverman’s rule-of-thumb.

  • x_T – Reference point. Defaults to the last element of x.

Returns:

np.ndarray – Kernel-based probabilities summing to one.

Parameters:

  • x (numpy.ndarray)

  • v (numpy.ndarray | None)

  • h (float | None)

  • x_T (float | None)

Return type:

numpy.ndarray

pyvallocation.probabilities.generate_uniform_probabilities(num_observations)[source]

Return equal probabilities for num_observations scenarios.

Parameters:

num_observations – Number of scenarios.

Returns:

np.ndarray – Uniform probability vector summing to one.

Parameters:

num_observations (int)

Return type:

numpy.ndarray

pyvallocation.probabilities.normalize_probability_vector(probabilities, *, strictly_positive=False, name='probabilities')[source]

Validate and normalise a 1-D probability vector.

Parameters:

  • probabilities – Array-like of probabilities. Must be one-dimensional and contain at least one entry.

  • strictly_positive – When True all entries must be strictly greater than zero. When False non-negative weights are accepted. Defaults to False.

  • name – Identifier used in error messages. Defaults to "probabilities".

Returns:

np.ndarray – Normalised probability vector summing to one.

Parameters:

  • probabilities (numpy.ndarray | Sequence[float])

  • strictly_positive (bool)

  • name (str)

Return type:

numpy.ndarray

pyvallocation.probabilities.resolve_probabilities(probabilities, n_observations, *, strictly_positive=False, name='probabilities')[source]

Return a normalised probability vector of length n_observations.

Parameters:

  • probabilities – Optional array-like of probabilities. When None a uniform distribution is generated.

  • n_observations – Expected number of observations (length of scenario set).

  • strictly_positive – Forwarded to normalize_probability_vector(). Defaults to False.

  • name – Identifier used in error messages. Defaults to "probabilities".

Returns:

np.ndarray – Probability vector summing to one with shape (n_observations,).

Parameters:

  • probabilities (numpy.ndarray | Sequence[float] | None)

  • n_observations (int)

  • strictly_positive (bool)

  • name (str)

Return type:

numpy.ndarray

pyvallocation.probabilities.silverman_bandwidth(x)[source]

Return Silverman’s rule-of-thumb bandwidth for x.

Uses the standard Gaussian kernel bandwidth constant of 1.06.

Parameters:

x (numpy.ndarray)

Return type:

float