Skip to content

entropy module

Entropies and their derivatives.

EntropyHessianComponents = tuple[ThreeArrays, TwoArrays] module-attribute

combines the tuples of the values of the components of the hessians.

EntropyHessianMuMu = Callable[[Matching], ThreeArrays] module-attribute

The type of a function that takes in a Matching and returns the three components of the hessian of the entropy wrt (\mu,\mu).

EntropyHessianMuMuParam = Callable[[Matching, list[Any]], ThreeArrays] module-attribute

The type of a function that takes in a Matching and a list of additional parameters and returns the three components of the hessian of the entropy wrt (\mu,\mu).

EntropyHessianMuR = Callable[[Matching], TwoArrays] module-attribute

The type of a function that takes in a Matching and returns the two components of the hessian of the entropy wrt (\mu,n) and (\mu, m)).

EntropyHessianMuRParam = Callable[[Matching, list[Any]], TwoArrays] module-attribute

The type of a function that takes in a Matching and a list of additional parameters and returns the two components of the hessian of the entropy wrt (\mu,n) and (\mu, m)).

EntropyHessians = tuple[EntropyHessianMuMu, EntropyHessianMuR] module-attribute

combines the hessian functions

EntropyHessiansParam = tuple[EntropyHessianMuMuParam, EntropyHessianMuRParam] module-attribute

combines the hessian functions when additional parameters are used

EntropyFunctions dataclass

Defines the entropy used, via the derivative e_0 + e \cdot \alpha

Attributes:

Name Type Description
e0_fun MatchingFunction | MatchingFunctionParam

required

parameter_dependent bool

if True, the entropy depends on parameters. Defaults to False

e_fun Optional[MatchingFunction | MatchingFunctionParam]

only in entropies that depend on parameters. Defaults to None

hessian Optional[str]

defaults to "numeric" * if "provided", we provide the hessian of the entropy. * if "numerical", it is computed by central differences.

e0_derivative Optional[EntropyHessians | EntropyHessiansParam]

the derivative of e0_fun, if available. Defaults to None

e_derivative Optional[EntropyHessians | EntropyHessiansParam]

the derivative of e_fun, if available. Defaults to None

additional_parameters Optional[list]

additional parameters that define the distribution of errors. Defaults to None

description Optional[str]

some text describing the model. Defaults to None

Examples:

See entropy_choo_siow in choo_siow.py

Source code in cupid_matching/entropy.py
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
@dataclass
class EntropyFunctions:
    """Defines the entropy used, via the derivative $e_0 + e \\cdot \\alpha$

    Attributes:
        e0_fun: required
        parameter_dependent:  if `True`, the entropy depends on parameters.
            Defaults to `False`
        e_fun: only in entropies that depend on parameters.
            Defaults to `None`
        hessian: defaults to `"numeric"`
            * if `"provided"`, we provide the hessian of the entropy.
            * if `"numerical"`, it is computed by central differences.
        e0_derivative: the derivative of `e0_fun`, if available.
            Defaults to `None`
        e_derivative: the derivative of `e_fun`, if available.
            Defaults to `None`
        additional_parameters: additional parameters
            that define the distribution of errors.
            Defaults to `None`
        description: some text describing the model.
            Defaults to `None`

    Examples:
        See `entropy_choo_siow` in `choo_siow.py`
    """

    e0_fun: MatchingFunction | MatchingFunctionParam
    e0_derivative: Optional[EntropyHessians | EntropyHessiansParam] = None
    additional_parameters: Optional[list] = None
    description: Optional[str] = None
    e_fun: Optional[MatchingFunction | MatchingFunctionParam] = None
    e_derivative: Optional[EntropyHessians | EntropyHessiansParam] = None
    hessian: Optional[str] = "numerical"
    parameter_dependent: bool = False

    def __post_init__(self):
        if not self.parameter_dependent:
            if self.hessian == "provided" and self.e0_derivative is None:
                bs_error_abort(
                    "You claim to provide the hessian "
                    + "but you did not provide the e0_derivative."
                )
        else:
            if self.e_fun is None:
                bs_error_abort(
                    "Your entropy is parameter dependent "
                    + " but you did not provide the e_fun."
                )
            if self.hessian == "provided" and self.e_derivative is None:
                bs_error_abort(
                    "Your entropy is parameter dependent, "
                    + "you claim to provide the hessian,\n"
                    + " but I do not see the e_derivative."
                )

entropy_gradient(entropy, muhat, alpha=None, additional_parameters=None)

Computes the derivative of the entropy wrt \mu at (\mu, n, m, \alpha, p)

Parameters:

Name Type Description Default
entropy EntropyFunctions

the EntropyFunctions object

required
muhat Matching

a Matching

required
alpha Optional[np.ndarray]

a vector of parameters of the derivative of the entropy, if any

None
additional_parameters Optional[list]

a list of additional parameters p, if any

None

Returns:

Type Description
np.ndarray

the derivative of the entropy wrt \mu

np.ndarray

at (\mu, n, m, \alpha, p).

Source code in cupid_matching/entropy.py
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
def entropy_gradient(
    entropy: EntropyFunctions,
    muhat: Matching,
    alpha: Optional[np.ndarray] = None,
    additional_parameters: Optional[list] = None,
) -> np.ndarray:
    """Computes the derivative of the entropy wrt $\\mu$
     at $(\\mu, n, m, \\alpha, p)$

    Args:
        entropy: the `EntropyFunctions` object
        muhat: a Matching
        alpha: a vector of parameters of the derivative of the entropy, if any
        additional_parameters: a list of additional parameters `p`, if any

    Returns:
        the derivative of the entropy wrt $\\mu$
        at $(\\mu, n, m, \\alpha, p)$.
    """
    e0_fun = entropy.e0_fun
    if additional_parameters is not None:
        e0_fun = cast(MatchingFunctionParam, e0_fun)
        e0_vals = e0_fun(muhat, additional_parameters)
    else:
        e0_fun = cast(MatchingFunction, e0_fun)
        e0_vals = e0_fun(muhat)
    parameter_dependent = entropy.parameter_dependent
    if parameter_dependent:
        if alpha is None:
            bs_error_abort("alpha should be specified for this model")
        e_fun = entropy.e_fun
        if e_fun is None:
            bs_error_abort("we should have an e_fun in this model")
        else:
            if additional_parameters is not None:
                e_fun = cast(MatchingFunctionParam, e_fun)
                e_vals = e_fun(muhat, additional_parameters)
            else:
                e_fun = cast(MatchingFunction, e_fun)
                e_vals = e_fun(muhat)
        return e0_vals + e_vals @ alpha
    else:
        return e0_vals