`maxent_disaggregation.maxent_direchlet`#

This module provides functions for working with the entropy of the Dirichlet distribution, including computing the entropy, its derivative with respect to a scaling parameter, and finding the gamma parameter that maximizes the entropy given a set of shares. Functions: ———- - dirichlet_entropy_derivative(gamma_par, shares):

Computes the derivative of the entropy of the Dirichlet distribution with respect to the scaling parameter gamma_par, assuming the concentration parameters alpha are proportional to the shares.

dirichlet_entropy(gamma_par, shares):
Computes the negative entropy of a Dirichlet distribution with concentration parameters defined as gamma_par * shares.
find_gamma_maxent(

eval_f: Callable = dirichlet_entropy,

given a set of shares, using the NLopt library for optimization.
The module assumes that the shares provided sum to 1.
The optimization in find_gamma_maxent can be performed with or without gradients.
The module relies on numpy, scipy, and nlopt libraries.

Module Contents#

Functions#

`dirichlet_entropy_derivative`(gamma_par, shares)	Computes the derivative of the entropy of the Dirichlet distribution
`dirichlet_entropy`(gamma_par, shares)	Computes the entropy of a Dirichlet distribution.
`find_gamma_maxent`(, shares_lb, eval_grad_f, ...)	Finds the gamma parameter that maximizes the entropy of a Dirichlet distribution

maxent_disaggregation.maxent_direchlet.dirichlet_entropy_derivative(gamma_par, shares)[source]#

Computes the derivative of the entropy of the Dirichlet distribution with respect to scaling parameter x, assuming alpha = x * shares.

Parameters: - gamma_par [float]: concentration paramter for Dirichlet distribution - shares: list or numpy array of shares (proportions) that sum to 1

Returns: - derivative of entropy with respect to gamma_par

Notes: - NOT TESTED yet.

maxent_disaggregation.maxent_direchlet.dirichlet_entropy(gamma_par, shares)[source]#

Computes the entropy of a Dirichlet distribution. The entropy is calculated based on the given parameters x and shares, which are used to derive the concentration parameters alpha of the Dirichlet distribution. :param gamma_par: The gamma scaling factor applied to the shares to compute the

concentration parameters alpha.

Parameters:: shares (array-like) – A vector of proportions that, when scaled by gamma_par, define the concentration parameters alpha of the Dirichlet distribution.
Returns:: The negative entropy of the Dirichlet distribution.
Return type:: float

maxent_disaggregation.maxent_direchlet.find_gamma_maxent(shares: numpy.ndarray | list = None, eval_f: collections.abc.Callable = dirichlet_entropy, x0: float = 1, x0_n_tries: int = 100, bounds: tuple = (0.001, 172), shares_lb: float = 0, eval_grad_f: collections.abc.Callable = dirichlet_entropy_derivative, grad_based: bool = False, **kwargs) → float[source]#

Finds the gamma parameter that maximizes the entropy of a Dirichlet distribution given a set of shares. This function uses the NLopt library for optimization. Parameters: ———– shares : array-like

A list or array of shares that must sum to 1. Shares below shares_lb are excluded from the computation.

eval_fcallable, optional: The function to evaluate the entropy of the Dirichlet distribution. Defaults to dirichlet_entropy.
x0float, optional: Initial guess for the gamma parameter. Defaults to 1.
x0_n_triesint, optional: Number of attempts to find a valid initial value for x0 if the evaluation function returns non-finite values. Defaults to 100.
boundstuple, optional: A tuple specifying the lower and upper bounds for the gamma parameter. Defaults to (0.001, 172).
shares_lbfloat, optional: Lower bound for the shares. Shares below this value are excluded. Defaults to 0.
eval_grad_fcallable, optional: The function to evaluate the gradient of the entropy function. Defaults to dirichlet_entropy_derivative.
grad_basedbool, optional: If True, uses gradient-based optimization. Defaults to False.

Returns:#

float: The optimized gamma parameter that maximizes the entropy.

Raises:#

ValueError: If the shares do not sum to 1 or if a valid initial value for x0 cannot be found after x0_n_tries attempts.

Notes:#

If the optimization fails to find a valid initial value for x0, the function provides suggestions to adjust parameters such as shares_lb, x0_n_tries, or bounds.
The optimization process can be made gradient-based by setting grad_based=True.

Example:#

>>> shares = np.array([0.2, 0.3, 0.5])
>>> gamma = find_gamma_maxent(shares)
>>> print(gamma)

maxent_disaggregation.maxent_direchlet#