% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/summary_rpm.R
\name{summary_rpm}
\alias{summary_rpm}
\alias{print.summary_rpm}
\alias{show.summary_rpm}
\title{Summarize Revealed Preference Matchings data via a Model Specification}
\usage{
summary_rpm(
  formula,
  Xdata,
  Zdata,
  Xid = NULL,
  Zid = NULL,
  pair_id = NULL,
  X_w = NULL,
  Z_w = NULL,
  pair_w = NULL,
  sampled = NULL,
  sampling_design = "stock-flow",
  control = control.rpm(),
  verbose = FALSE
)
}
\arguments{
\item{formula}{formula; an \code{\link{formula}} object, of the form \code{
~ <model terms>}. For the details on the possible \code{<model terms>}, see
\code{\link{rpm-terms}}.}

\item{Xdata}{data.frame for women. Each row is a woman, each column is a variable on that women
or her partnerships. It must contain the women's ID variable (see \code{Xid}) and
a variable with the ID of the women's partner. If the women is single the men's ID should be NA.}

\item{Zdata}{data.frame for men. Each row is a man, each column is a variable on that men
It must contain the men's ID variable (see \code{Zid}).}

\item{Xid}{string The name of the variable in \code{Xdata} containing the IDs of the women.}

\item{Zid}{string The name of the variable in \code{Zdata} containing the IDs of the men.}

\item{pair_id}{string The name of the variable in \code{Xdata} containing the ID of the men paired with the women in
\code{Xid}. If the women is not paired it must be NA.}

\item{X_w}{string The name of the variable in \code{Xdata} containing the individual weight of the women.
If this is NULL then it is assumed the sample is unweighted from a population with 2000 women in it.}

\item{Z_w}{string The name of the variable in \code{Zdata} containing the individual weight of the man
If this is NULL then it is assumed the sample is unweighted from a population with 2000 men in it.}

\item{pair_w}{string The name of the variable in \code{Xdata} containing the pair weight of that women.
If the women is not paired it should be NA.
If this is NULL then it is computed from the individual weights using the \code{sampling_design}.
Note that the pair weights currently do not play a role in the estimation. They do in the quasi-likelihood version of the code.
If this is NULL then it is assumed the sample is unweighted from a population with 2000 men in it.}

\item{sampled}{string The name of the logical variable in \code{Xdata} and \code{Zdata} containing the 
indicator that the person was sampled directly (as distinct from being included as the match of a directly sampled
person. All single people are directly sampled.}

\item{sampling_design}{string; The name of the sampling protocol used to select the survey data. Valid values are
\code{"stock-flow"} (default) (individuals are sampled, data contains both
singles and couples);
\code{"stock-stock"} (households are sampled, each household can be a single or a couple);
\code{"census"} (the sample is a census of the population of people).}

\item{control}{A list of control parameters for algorithm tuning. Constructed using
\code{\link{control.rpm}}, which should be consulted for specifics.}

\item{verbose}{logical; if this is \code{TRUE}, the program will print out
additional information, including data summary statistics.}
}
\value{
\code{\link{summary}} returns a list with many components, like \code{\link{rpm}} object without the model estimates. In particular it includes \code{stats} and \code{popstats}.
\code{stats} is the named vector of sample statistics from the model. 
while \code{popstats} is the named vector of population statistics from the model. 
It alos includes \code{counts} and \code{pmf}. Each of these is a contingency table in array
representation of S3 class \code{c("xtabs", "table")}, with a \code{"call"}
}
\description{
\code{\link{summary_rpm}} produces tabular summaries of data revealed preference matchings
based on a formula specifying a revealed preference model
for men and women of certain
characteristics (or shared characteristics) of people of the opposite sex.
The model assumes a one-to-one stable matching using an observed set of
matchings and a set of (possibly dyadic) covariates to 
estimate the parameters for
linear equations of utilities.
}
\details{
The pairings are determined by the \code{pair_id} variable in \code{Xdata}. 
If that variable is NA then the women is
assumed to be single. If men are listed in \code{Zdata} and are not partnered then they are assumed single.
Weights are specified by three optional variables in \code{Xdata}.
\describe{
\item{X_w}{: This is character string of the name of the weight variable for women. The sum of the weights should be the
number of women in the population.}
\item{Z_w}{: This is character string of the name of the weight variable for men. The sum of the weights should be the
number of men in the population.}
\item{pair_w}{: This is character string of the name of the weight variable for pairs.}
}
}
\examples{
library(rpm)
data(fauxmatching)
summary_rpm(~match("edu") + WtoM_diff("edu",3),
        Xdata=fauxmatching$Xdata, Zdata=fauxmatching$Zdata,
        X_w="X_w", Z_w="Z_w",
        pair_w="pair_w", pair_id="pair_id", Xid="pid", Zid="pid",
        sampled="sampled",sampling_design="stock-flow")
}
\references{
Goyal, Shuchi; Handcock, Mark S.; Jackson, Heide M.; Rendall, Michael S. and Yeung, Fiona C. (2023).
\emph{A Practical Revealed Preference Model for Separating Preferences and Availability Effects in Marriage Formation},
\emph{Journal of the Royal Statistical Society}, A. \doi{10.1093/jrsssa/qnad031} 

Dagsvik, John K. (2000) \emph{Aggregation in Matching Markets} \emph{International Economic Review}, Vol. 41, 27-57.
JSTOR: https://www.jstor.org/stable/2648822, \doi{10.1111/1468-2354.00054}

Menzel, Konrad (2015).
\emph{Large Matching Markets as Two-Sided Demand Systems}
Econometrica, Vol. 83, No. 3 (May, 2015), 897-941. \doi{10.3982/ECTA12299}
}
\seealso{
control.rpm, summary.rpm, rpm
}
\keyword{models}
