Nothing
R/rpm-terms.R
In rpm: Modeling of Revealed Preferences Matchings
#' Terms used in a Revealed Preference Matchings Model
#'
#' 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).
#'
#' 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.
#'
#' @docType methods
#' @name rpm-terms
#' @aliases rpm-terms rpm.terms terms-rpm terms.rpm absdiff
#' W_atleast W_atmost W_cov W_factor W_greaterthan
#' M_atleast M_atmost M_cov M_factor M_greaterthan
#' WtoM_diff MtoW_diff
#' match
#' diff
#' mix
#'
#' @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.
#' }
#' }
#' @return No return value, called for side effects.
#' @seealso \code{\link[=rpm-package]{rpm}} package,
#' \code{\link{rpm}}
#' @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}
#'
#' @keywords models
#' @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)
#' }
NULL
Try the rpm package in your browser
Any scripts or data that you put into this service are public.
rpm documentation built on May 29, 2024, 12:07 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
#' Terms used in a Revealed Preference Matchings Model
#'
#' 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).
#'
#' 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.
#'
#' @docType methods
#' @name rpm-terms
#' @aliases rpm-terms rpm.terms terms-rpm terms.rpm absdiff
#' W_atleast W_atmost W_cov W_factor W_greaterthan
#' M_atleast M_atmost M_cov M_factor M_greaterthan
#' WtoM_diff MtoW_diff
#' match
#' diff
#' mix
#'
#' @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.
#' }
#' }
#' @return No return value, called for side effects.
#' @seealso \code{\link[=rpm-package]{rpm}} package,
#' \code{\link{rpm}}
#' @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}
#'
#' @keywords models
#' @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)
#' }
NULL
Try the rpm package in your browser
Any scripts or data that you put into this service are public.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.