% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rpm-terms.R
\docType{methods}
\name{rpm-terms}
\alias{rpm-terms}
\alias{rpm.terms}
\alias{terms-rpm}
\alias{terms.rpm}
\alias{absdiff}
\alias{W_atleast}
\alias{W_atmost}
\alias{W_cov}
\alias{W_factor}
\alias{W_greaterthan}
\alias{M_atleast}
\alias{M_atmost}
\alias{M_cov}
\alias{M_factor}
\alias{M_greaterthan}
\alias{WtoM_diff}
\alias{MtoW_diff}
\alias{match}
\alias{diff}
\alias{mix}
\title{Terms used in a Revealed Preference Matchings Model}
\value{
No return value, called for side effects.
}
\description{
The function \code{\link{rpm}} is used to fit 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.
It does this using an large-population likelihood based on ideas from Dagsvik (2000), Menzel (2015) and Goyal et al (2023).
}
\details{
The model represents the dyadic utility functions as deterministic linear utility functions of
dyadic variables. These utility functions are functions of observed characteristics of the women
and men.
These functions are entered as terms in the function call
to \code{\link{rpm}}.  This page describes the possible terms (and hence
linear utility functions) included in \code{\link[=rpm-package]{rpm}} package.
}
\section{Specifying models}{


Terms to \code{\link{rpm}} are specified by a formula to represent the
pairings and covariates This is done via a \code{formula}, that is,
an formula object, of the form \code{~ <term 1> + <term 2> ...}, where
\code{<term 1>}, \code{<term 2>}, etc, are each terms chosen
from the list given below.
\describe{
 \item{\code{absdiff(attr)} (quantitative attribute),
   \code{absdiff(attr)} (quantitative attribute)}{\emph{Absolute difference:}
   The \code{attr} argument specifies a quantitative attribute 
   This term adds one statistic to the model equaling
   \code{abs(attr[i]-attr[j])} for all women-man dyad (i,j).
  }
 \item{\code{W_greaterthan(attr)}}{\emph{Women's value
   greater than the men's value} Adds one statistic
   indicating if the women's value exceeds the men's value.
  }
 \item{\code{M_greaterthan(attr)}}{\emph{Men's value
   greater than the women's value} Adds one statistic
   indicating if the men's value exceeds the women's value.
  }
 \item{\code{W_atleast(attr,threshold=0)}}{\emph{Values
   greater than or equal to a threshold} Adds one statistic
   indicating if the women's value of the attribute equals or exceeds
   \code{threshold}.
  }
 \item{\code{W_atmost(threshold=0)}}{\emph{Values
   less than or equal to a threshold} Adds one statistic
   indicating if the women's value equals or is exceeded by
   \code{threshold}.
  }
 \item{\code{W_cov(attr)} (quantitative attribute),
   \code{W_cov(attr)} (quantitative attribute)
   }{\emph{Main effect of a covariate for women:}
   The \code{attr} argument specifies a quantitative attribute
   This term adds a single statistic equaling the 
   value of \code{attr(i)} for women \eqn{i} in the dyad.
   For categorical attributes,
   see \code{W_factor}.
  }
 \item{\code{diff(attr)} (quantitative attribute), \code{diff(attr)}
   (quantitative attribute)}{\emph{Woman's Gap:}
   The \code{attr} argument specifies a quantitative attribute
   This term adds one statistic to the model
   being \code{attr[i]-attr[j]} for women \eqn{i} and man \eqn{j}.
   Specifically, it is the excess of the woman's value over the man's value.
  }
 \item{\code{WtoM_diff(attr, diff)} (ordinal categorical attribute), \code{WtoM_diff(attr)}
   (ordinal categorical discrete attribute)}{\emph{Woman's Gap:}
   The \code{attr} argument specifies a ordinal categorical attribute
   This term adds one statistic to the model
   being an indicator that \code{attr[i]=attr[j]+diff} for women \eqn{i} and man \eqn{j}.
   Specifically, it indicates if the woman's value is \code{diff} higher than the man's value.
  }
 \item{\code{MtoW_diff(attr, diff)} (ordinal categorical attribute), \code{MtoW_diff(attr)}
   (ordinal categorical discrete attribute)}{\emph{Man's Gap:}
   The \code{attr} argument specifies a ordinal categorical attribute
   This term adds one statistic to the model
   being an indicator that \code{attr[j]=attr[i]+diff} for women \eqn{i} and man \eqn{j}.
   Specifically, it indicates if the man's value is \code{diff} higher than the woman's value.
  }
 \item{\code{MtoW_diff(attr)} (quantitative attribute), \code{MtoW_diff(attr)}
   (quantitative attribute)}{\emph{Difference:}
   The \code{attr} argument specifies a quantitative attribute
   This term adds one statistic to the model
   \code{attr[j]-attr[i]} for women \eqn{i} and man \eqn{j}.
  }
 \item{\code{W_factor(attr, base=1, levels=-1)} (categorical attribute),
   \code{W_factor(attr, base=1, levels=-1)} (categorical attribute)
   }{\emph{Factor attribute effect for women:}
   The \code{attr} argument specifies a categorical attribute
   This term adds
   multiple statistics to the model, one for each of (a subset of) the
   unique values of the \code{attr} attribute. Each of these statistics
   indicates if the women's has that attribute.
  }
 \item{\code{homophily(attr)}
   }{\emph{Uniform homophily effect:}
   The \code{attr} argument specifies a categorical attribute
   This term adds one statistic to the model
   indicating that the dyad matches on that attribute.
  }
 \item{\code{match(attr, diff=FALSE, collapse=NULL)}
   }{\emph{Attribute-based homophily effect:}
   The \code{attr} argument specifies a categorical attribute
   This term adds one statistic to the model for each categorical level,
   unless \code{diff} is set to \code{TRUE}, in which case the term adds multiple 
   statistics to the model, one for each of (a subset of) the unique values of the \code{attr}
   attribute. 
   If \code{diff} is set to \code{TRUE}, the optional argument \code{collapse} control what dyads 
are collapsed (or pooled).
Specifically, it is a list of indices of attribute values which are to be collapsed into a
single term. For example, \code{collapse=list(c(1,4))} will collapse the \code{(1,1)} and the 
\code{(4,4)} dyads into a single term (and group). Multiple lists can be included with arbitrary numbers of 
 dyads in a group. 
  }
 \item{\code{mix(attr, base=NULL, collapse=NULL)}
   }{\emph{Attribute mixing:} The \code{attr} argument specifies a categorical attributes
   By default, this term adds one statistic to
   the model for each possible pairing of attribute values. The
   statistic indicates if the dyad 
   has that pairing of values.
   In other words, this term produces one statistic for
   every entry in the mixing matrix for the attribute(s). The ordering of
   the attribute values is lexicographic: alphabetical (for nominal categories) or
   numerical (for ordered categories).
   The optional argument \code{base} control what statistics are 
   included in the model, specifically it lists the index of the omitted terms (in order).
   For example, \code{base=2} omits the second term. 
   The optional argument \code{collapse} control what dyads are collapsed (or pooled).
Specifically, it is a list of lists. Each element of the list is a list of dyads which are to be collapsed into a
single term. For example, \code{collapse=list(list(c(1,4),c(2,4)))} will collapse the \code{(1,4)} and the 
\code{(2,4)} dyads into a single term (and group). Multiple lists can be included with arbitrary numbers of 
 dyads in a group. 
  }
}
}

\examples{
library(rpm)
data(fauxmatching)
\donttest{
fit <- 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")
summary(fit)
}
}
\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{
\code{\link[=rpm-package]{rpm}} package,
\code{\link{rpm}}
}
\keyword{models}
