Package: cupid_matching
cupid_matchingA Python package to solve, simulate and estimate separable matching modelsFree software: MIT licenseDocumentation:https://bsalanie.github.io/cupid_matchingSee also:An interactive Streamlit appInstallationpip install [-U] cupid_matchingImporting functions from the packageFor instance:fromcupid_matching.min_distanceimportestimate_semilinear_mdeHow it worksThe following only describes the general ideas. Seeherefor more background and the API reference on this site for the technical documentation.Thecupid_matchingpackage has codeto solve for the stable matching using our Iterative Projection Fitting Procedure (IPFP) in variants of the model of bipartite, one-to-one matching with perfectly transferable utility. It has IPFP solvers for variants of theChoo and Siow 2006model with or without singles, homoskedastic and heteroskedastic; and also for a class of nested logit modelsto estimate the parameters of separable models with semilinear surplus and entropy using a minimum distance estimatorto estimate the parameters of semilinear Choo and Siow models using a Poisson GLM estimatorfor aStreamlitinteractive app that demonstrates solving and estimating the Choo and Siow model using thecupid_matchingpackage. You can try ithere.Incidentally, myipfp_RGithub repository contains R code to solve for equilibrium in (only) the basic version of the Choo and Siow model.The package builds on the pioneering work ofChoo and SiowJPE2006and on my work with Alfred Galichon, especially ourREStud2022 paperandthis working paper.At this stage, it only deals with bipartite models. As the heterosexual marriage market is a leading example, I will refer to the two sides asmenandwomen. Each man $m$ (resp. each women $w$) has an observed, discrete-valued type $x$ (resp. $y$), along with unobserved heterogeneity.The primitivesThe primitives of this class of matching models arethemargins: the numbers $n_x$ of men of type $x=1,\ldots,X$ and the numbers $m_y$ of women of type $y=1,\ldots,Y$thejoint surpluscreated by the match of a man $m$ of type $x$ and a woman $w$ of type $y$. We assumeseparability: this joint surplus takes the form
$$
\Phi_{xy}+\varepsilon_{my} +\eta_{xw}.
$$
I will only describe here the case when the data also has singles, i.e., when $x=y=0$ is a possible type. Thefuller documentationexplains how to deal with the case when singles are not observed.A single man has utility $\varepsilon_{m0}$ and a single woman has utility $\eta_{0w}$.The modeler chooses the distributions of the vectors $(\varepsilon_{m0},\varepsilon_{m1},\ldots, \varepsilon_{mY})$ and $(\eta_{0w},\eta_{1w},\ldots,\eta_{Xw})$.The solution: the stable matchingWe denote $\mu_{xy}$ the number of matches between men of type $x$ and women of type $y$, $\mu_{x0}$ the number of single men of type $x$, and $\mu_{0y}$ the number of single women of type $y$.The total numbers must add up to the margins:
$$
\sum_{y=1}^Y \mu_{xy}+\mu_{x0}=n_x ; \text{ and } ;
\sum_{x=1}^X \mu_{xy}+\mu_{0y}=m_y.
$$
The total number of individuals is $N_i=\sum_{x=1}^X n_x+ \sum_{y=1}^Y m_y$ and the total number of households is $N_h = N_i - \sum_{x=1}^X \sum_{y=1}^Y \mu_{xy}$.Galichon-Salanié (REStud2022) shows that in large markets, if the vectors $\varepsilon$ and $\eta$ have full support, the stable matching is the unique solution to the strictly convex program $$
\max_{\mu} \left(\sum_{x=1}^X \sum_{y=1}^Y \mu_{xy}\Phi_{xy} + \mathcal{E}(\mu; n, m)\right)
$$ where $\mathcal{E}$, thegeneralized entropyfunction, depends on the assumed distributions of the $\varepsilon$ and $\eta$ random vectors.The fileschoo_siow.py,choo_siow_gender_heteroskedastic,choo_siow_heteroskedastic, andnested_logitprovideEntropyFunctionsobjects that compute the generalized entropy and at least its first derivative for, respectively,the original Choo and Siow 2006 model, in which the $\varepsilon$ and $\eta$ terms are iid draws from a type I extreme value distributionthe same model, without singles (to be used when only couples are observed)an extension of 1. that allows for a scale parameter $\tau$ for the distribution of $\eta$an extension of 3. that has type-dependent scale parameters $\sigma_x$ and $\tau_y$ (with $\sigma_1=1$a two-layer nested logit model in which singles (type 0) are in their own nest and the user chooses the structure of the other nests.Users of the package are welcome to codeEntropyFunctionsobjects for different distributions of the unobserved heterogeneity terms.Solving for the stable matchingGiven any joint surplus matrix $\Phi$; margins $n$ and $m$; and a generalized entropy $\mathcal{E}$, one would like to compute the stable matching patterns $\mu$.For the five classes of models above, this can be done efficiently using the IPFP algorithm in Galichon-Salanié (REStud2022) , which is coded inipfp_solvers.pyfor the four Choo and Siow variants and inmodel_classes.pyfor the nested logit.Here is an example, given a Numpy array $\Phi$ that is an $(X,Y)$ matrix and a number $\tau>0$:importnumpyasnpfromcupid_matching.ipfp_solversimportipfp_gender_homoskedasticsolversolution=ipfp_gender_heteroskedastic_solver(Phi,n,m,tau)mus,error_x,error_y=solutionmuxy=mus.muxyThemusabove is an instance of aMatchingobject (defined inmatching_utils.py).mus.muxyhas the number of couples by $(x,y)$ cell at the stable matching; the vectorsmus.mux0andmus.mu0ycontain the numbers of single men and women of each type.The vectorserror_xanderror_yare estimates of the precision of the solution (see the code inipfp_solvers.py).Estimating the joint surplusGiven observed matching patterns $\mu$; a class of generalized entropy functions $(\mathcal{E}^{\alpha})$; and a class of joint surplus functions $(\Phi^{\beta})$, one would like to estimate the parameter vectors $\alpha$ and $\beta$.The package provides two estimators, which are described extensively inthis paper:the minimum distance estimator inmin_distance.pythe Poisson estimator inpoisson_glm.py, which only applies to the Choo and Siow homoskedastic model.At this stagecupid_matchingonly allows for linear models of the joint surplus:$$
\Phi^{\beta}{xy} = \sum{k=1}^K \phi_{xy}^k \beta_k
$$where thebasis functions$(\phi^1,\ldots,\phi^K)$ are imposed by the analyst.The minimum distance estimator works as follows, givenan observed matching stored in aMatchingobjectmusanEntropyFunctionobjectentropy_modelthat allows forpparameters in $\alpha$an $(X,Y,K)$ Numpy array of basis functionsphi_bases:mde_results=estimate_semilinear_mde(mus,phi_bases,entropy_model)mde_results.print_results(n_alpha=p)Themde_resultsobject contains the estimated $\alpha$ and $\beta$, their estimated variance-covariance, and a specification test.The Poisson-GLM estimator of the Choo and Siow homoskedastic model takes as input the obserrved matching and the basis functions, and returns the estimated $\beta$ and its estimated variance-covariance.poisson_results=choo_siow_poisson_glm(mus_sim,phi_bases)_,mux0_sim,mu0y_sim,n_sim,m_sim=mus_sim.unpack()poisson_results.print_results()Thepoisson_resultsobject contains the estimated  $\beta$, the expected utilities $u_x$ and $v_y$, and their estimated variance-covariance.ExamplesThe following can be found in the Github repository and in the source code on PyPI:example_choosiow.pyshows how to run minimum distance and Poisson estimators on a Choo and Siow homoskedastic model.example_choosiow_no_singles.pydoes the same for a model without singles.example_nested_logit.pyshows how to run minimum distance estimators on a two-layer nested logit model.Warningsmany of these models (including all variants of Choo and Siow) rely heavily on logarithms and exponentials. It is easy to generate examples where numeric instability sets in.as a consequence, thenumericversions of the minimum distance estimator (which use numerical derivatives) are not recommended.the bias-corrected minimum distance estimator (corrected) may have a larger mean-squared error and/or introduce numerical instabilities.the estimated variance of the estimators assumes that the observed matching was sampled at the household level, and that sampling weights are all equal.Release notes{{< include releases.md >}}