:py:mod:`maxent_disaggregation.maxent_direchlet`
================================================

.. py:module:: maxent_disaggregation.maxent_direchlet

.. autoapi-nested-parse::

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

.. autoapisummary::

   maxent_disaggregation.maxent_direchlet.dirichlet_entropy_derivative
   maxent_disaggregation.maxent_direchlet.dirichlet_entropy
   maxent_disaggregation.maxent_direchlet.find_gamma_maxent



.. py:function:: dirichlet_entropy_derivative(gamma_par, shares)

   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.



.. py:function:: dirichlet_entropy(gamma_par, shares)

   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`.
   :type gamma_par: float
   :param shares: A vector of proportions that, when scaled by `gamma_par`,
                  define the concentration parameters `alpha` of
                  the Dirichlet distribution.
   :type shares: array-like

   :returns: The negative entropy of the Dirichlet distribution.
   :rtype: float


.. py:function:: 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

   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_f : callable, optional
       The function to evaluate the entropy of the Dirichlet distribution.
       Defaults to `dirichlet_entropy`.
   x0 : float, optional
       Initial guess for the gamma parameter. Defaults to 1.
   x0_n_tries : int, optional
       Number of attempts to find a valid initial value for `x0` if the
       evaluation function returns non-finite values. Defaults to 100.
   bounds : tuple, optional
       A tuple specifying the lower and upper bounds for the gamma parameter.
       Defaults to (0.001, 172).
   shares_lb : float, optional
       Lower bound for the shares. Shares below this value are excluded.
       Defaults to 0.
   eval_grad_f : callable, optional
       The function to evaluate the gradient of the entropy function.
       Defaults to `dirichlet_entropy_derivative`.
   grad_based : bool, 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)