Entropy utilities - Cupid Matching

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`

     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
    105
    106
    107
    108
    @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`

    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
    150
    151
    152
    153
    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