pyblp.CustomMoment

class pyblp.CustomMoment(value, observations, compute_custom, compute_custom_derivatives=None, market_ids=None, market_weights=None, name='Custom')

Configuration for custom micro moments.

This configuration requires a value \(\mathscr{V}_m\) computed, for example, from survey data. It also requires a function that computes the simulated counterpart of this value,

(1)\[v_{mt} = \sum_{i \in I_t} w_{it} v_{imt},\]

a simulated integral over agent-specific micro values \(v_{imt}\) computed according to a custom function. These are averaged across a set of markets \(T_m\) and compared with \(\mathscr{V}_m\), which gives \(\bar{g}_{M,m}\) in (34).

Parameters
  • value (float) – Value \(\mathscr{V}_m\) of the statistic estimated from micro data.

  • observations (int) – Number of micro data observations \(N_m\) used to estimate \(\mathscr{V}_m\), which is used to properly scale micro moment covariances in (35).

  • compute_custom (callable) –

    Function that computes \(v_{imt}\) in a single market \(t\), which is of the following form:

    compute_custom(t, sigma, pi, rho, products, agents, delta, mu, probabilities) -> custom
    

    where

    • t is the ID of the market in which the \(v_{imt}\) should be computed;

    • sigma is the Cholesky root of the covariance matrix for unobserved taste heterogeneity, \(\Sigma\), which will be empty if there are no such parameters;

    • pi are parameters that measure how agent tastes vary with demographics, \(\Pi\), which will be empty if there are no such parameters;

    • rho is a \(J_t \times 1\) vector with parameters that measure within nesting group correlations for each product, \(\rho_{h(j)}\), which will be empty if there is no nesting structure;

    • products is a Products instance containing product data for the current market;

    • agents is an Agents instance containing agent data for the current market;

    • delta is a \(J_t \times 1\) vector of mean utilities \(\delta_{jt}\);

    • mu is a \(J_t \times I_t\) matrix of agent-specific utilities \(\mu_{ijt}\);

    • probabilities is a \(J_t \times I_t\) matrix of choice probabilities \(s_{ijt}\); and

    • custom is an \(I_t \times 1\) vector of agent-specific micro values \(v_{imt}\).

  • compute_custom_derivatives (callable, optional) –

    Function that computes \(\frac{\partial v_{imt}}{\partial \theta_p}\) in a single market \(t\), which is of the following form:

    compute_custom_derivatives(t, sigma, pi, rho, products, agents, delta, mu, probabilities, p, derivatives) ->
    custom_derivatives
    

    where the first few arguments are the same as above,

    • p is the index \(p \in \{0, \dots, P - 1\}\) of \(\theta_p\) (for the ordering of the \(P\) parameters in \(\theta\), see ProblemResults.theta),

    • derivatives is a \(J_t \times I_t\) matrix of derivatives \(\frac{\partial s_{ijt}}{\partial \theta_p}\), and

    • custom_derivatives is an \(I_t \times 1\) vector of agent-specific micro value derivatives \(\frac{\partial v_{imt}}{\partial \theta_p}\).

    If this function is left unspecified, you must set finite_differences=True in Problem.solve() when using custom moments. This may slow down optimization and slightly reduce the numerical accuracy of standard errors.

    If you specify this function, to check that you have implemented derivatives correctly, you can pass optimization=Optimization('return') to Problem.solve() when evaluating the gradient with finite_differences=True and finite_differences=False. If the numerical gradient is close to the analytic one, this suggests that you have implemented derivatives correctly.

  • market_ids (array-like, optional) – Distinct market IDs over which the micro moments will be averaged to get \(\bar{g}_{M,m}\). These are also the only markets in which the moments will be computed. By default, the moments are computed for and averaged across all markets.

  • market_weights (array-like, optional) – Weights for averaging micro moments over specified market_ids. By default, these are \(1 / T_m\).

  • name (str, optional) – Name of the custom moment, which will be used when displaying information about micro moments. By default, this is "Custom".

Examples

Methods