handcock/rpm

R package "rpm": Modeling of Revealed Preferences Matchings

The rpm package

This is an R package to estimate revealed preferences based on observed bipartite matchings.

Many problems in demography require models for partnership formation that separate latent preferences for partners from the availability of partners. This package consider models for matchings within a bipartite population where individuals have utility for people based on observed and unobserved characteristics. People can form a partnership or remain unpartnered. The models represent both the availability of potential partners of different types and preferences of individuals for such people.

We develop a large-population likelihood framework to estimate preference parameters based on sample survey data on partnerships and population composition. The framework was originally due to Dagsvik (2000) and Menzel (2015). Based on simulation studies conducted in Goyal, Handcock, Jackson, Rendall and Yeung (2023), for realistic population sizes, the model recovers preference parameters that are invariant under different population availabilities. The software uses bootstrap methods to bias correct parameter estimates for small population sizes and produce confidence intervals that have the correct coverage.

The package was originally developed by Ryan M. Admiraal and Mark S. Handcock.

Installation

The package is available on CRAN and can be installed using

install.packages("rpm")

Installation of the development version

To install it, you can also use:

# If devtools is not installed:
# install.packages("devtools")

devtools::install_github("handcock/rpm")

Resources

To run an example use:

library(rpm)
data(fauxmatching)
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)

For details on how to construct data for input to rpm() see the documentation:

help(fauxmatching)

For information on the current terms that can be used in formulas for rpm() see the documentation:

help("rpm-terms")

Software bugs and questions

Please use the GitHub repository to report bugs or request features: https://github.com/handcock/rpm/issues

See the following papers for more information and examples:

Statistical Methodology

• Goyal, Shuchi; Handcock, Mark S.; Jackson, Heide M.; Rendall, Michael S.; Yeung, Fiona C. (2023) A Practical Revealed Preference Model for Separating Preferences and Availability Effects in Marriage Formation, Journal of the Royal Statistical Society, A.
• Dagsvik, John K. (2000) Aggregation in Matching Markets JSTOR: https://www.jstor.org/stable/2648822, International Economic Review, Vol. 41, 27-57.
• Menzel, Konrad (2015) Large Matching Markets as Two-Sided Demand Systems, Econometrica, Vol. 83, No. 3 (May, 2015), 897-941.

rpm's Issues

Please consider adding BugReports to DESCRIPTION

Hello, in addition to URL, please consider adding also BugReports to DESCRIPTION, so it's easier to find this issue from https://cran.r-project.org/package=rpm.

Explicitly specify argument 'tied.method' when calling matrixStats::rowRanks()

TL;DR

Whenever calling colRanks() or rowRanks() from matrixStats, please specify argument ties.method explicitly. In future releases of matrixStats, it will be an error if not doing so.

We will roll out this change slowly. First users of your package will see warnings, which are non-breaking. Only in a later release, matrixStats will produce errors, which then are breaking.

To be ahead of this, please update your package to explicitly specify the ties.method argument.

Background

The matrixStats package will eventually require that argument ties.method of colRanks() and rowRanks() is explicitly specified. Relying on the default value will become deprecated, and eventually also defunct. For example, instead of calling colRanks(X), one could specify colRanks(X, ties.method = "max") or colRanks(X, ties.method = "average").

The reason for this is that the default ties.method value for colRanks() and rowRanks() is currently ties.method = "max", whereas the corresponding one for base::rank() is ties.method = "average". We want the matrixStats functions to eventually also default to ties.method = "average". In order to do so, we cannot just switch from one version to the other, because that would change the result. You can read about this in HenrikBengtsson/matrixStats#142.

This is why we are reaching out to you, so you can make sure to use the ties.method that you intended. When scanning packages that use colRanks() and rowRanks() of matrixStats without specifying the ties.method argument, your package came up. See below for details.

Details

We ran reverse-package dependency checks (R CMD check) with environment variable R_MATRIXSTATS_TIES_METHOD_MISSING=defunct to detect with missing ties.method argument. Your package came up with the following:

* using log directory ‘/c4/home/henrik/repositories/matrixStats/revdep/checks/rpm/new/rpm.Rcheck’
* using R version 4.3.3 (2024-02-29)
* using platform: x86_64-pc-linux-gnu (64-bit)
* R was compiled by
    gcc (GCC) 10.2.1 20210130 (Red Hat 10.2.1-11)
    GNU Fortran (GCC) 10.2.1 20210130 (Red Hat 10.2.1-11)
* running under: CentOS Linux 7 (Core)
* using session charset: UTF-8
* using option ‘--no-manual’
* checking for file ‘rpm/DESCRIPTION’ ... OK
* checking extension type ... Package
* this is package ‘rpm’ version ‘0.7-1’
* package encoding: UTF-8
* checking package namespace information ... OK
* checking package dependencies ... OK
* checking if this is a source package ... OK
* checking if there is a namespace ... OK
* checking for executable files ... OK
* checking for hidden files and directories ... OK
* checking for portable file names ... OK
* checking for sufficient/correct file permissions ... OK
* checking whether package ‘rpm’ can be installed ... WARNING
Found the following significant warnings:
  /c4/home/henrik/repositories/matrixStats/revdep/library/rpm/RcppArmadillo/include/armadillo_bits/fn_reshape.hpp:63:13: warning: ‘arma::Mat<typename T1::elem_type> arma::reshape(const arma::Base<typename T1::elem_type, T1>&, arma::uword, arma::uword, arma::uword)’ is deprecated: don't use this form: it will be removed [-Wdeprecated-declarations]
  /c4/home/henrik/repositories/matrixStats/revdep/library/rpm/RcppArmadillo/include/armadillo_bits/fn_reshape.hpp:65:7: warning: ‘arma::Mat<typename T1::elem_type> arma::reshape(const arma::Base<typename T1::elem_type, T1>&, arma::uword, arma::uword, arma::uword)’ is deprecated: don't use this form: it will be removed [-Wdeprecated-declarations]
  /c4/home/henrik/repositories/matrixStats/revdep/library/rpm/RcppArmadillo/include/armadillo_bits/fn_reshape.hpp:74:9: warning: ‘arma::Mat<typename T1::elem_type> arma::reshape(const arma::Base<typename T1::elem_type, T1>&, arma::uword, arma::uword, arma::uword)’ is deprecated: don't use this form: it will be removed [-Wdeprecated-declarations]
See ‘/c4/home/henrik/repositories/matrixStats/revdep/checks/rpm/new/rpm.Rcheck/00install.out’ for details.
* used C++ compiler: ‘g++ (GCC) 10.2.1 20210130 (Red Hat 10.2.1-11)’
* checking installed package size ... NOTE
  installed size is 11.6Mb
  sub-directories of 1Mb or more:
    libs  11.1Mb
* checking package directory ... OK
* checking DESCRIPTION meta-information ... OK
* checking top-level files ... OK
* checking for left-over files ... OK
* checking index information ... OK
* checking package subdirectories ... OK
* checking R files for non-ASCII characters ... OK
* checking R files for syntax errors ... OK
* checking whether the package can be loaded ... OK
* checking whether the package can be loaded with stated dependencies ... OK
* checking whether the package can be unloaded cleanly ... OK
* checking whether the namespace can be loaded with stated dependencies ... OK
* checking whether the namespace can be unloaded cleanly ... OK
* checking loading without being on the library search path ... OK
* checking dependencies in R code ... OK
* checking S3 generic/method consistency ... OK
* checking replacement functions ... OK
* checking foreign function calls ... OK
* checking R code for possible problems ... OK
* checking Rd files ... OK
* checking Rd metadata ... OK
* checking Rd cross-references ... OK
* checking for missing documentation entries ... OK
* checking for code/documentation mismatches ... OK
* checking Rd \usage sections ... OK
* checking Rd contents ... OK
* checking for unstated dependencies in examples ... OK
* checking contents of ‘data’ directory ... OK
* checking data for non-ASCII characters ... OK
* checking data for ASCII and uncompressed saves ... OK
* checking line endings in C/C++/Fortran sources/headers ... OK
* checking line endings in Makefiles ... OK
* checking compilation flags in Makevars ... OK
* checking for GNU extensions in Makefiles ... OK
* checking for portable use of $(BLAS_LIBS) and $(LAPACK_LIBS) ... OK
* checking use of PKG_*FLAGS in Makefiles ... OK
* checking compiled code ... OK
* checking examples ... OK
* checking for unstated dependencies in ‘tests’ ... OK
* checking tests ... ERROR
  Running ‘tests.R’
Running the tests in ‘tests/tests.R’ failed.
Complete output:
  > 
  > library(testthat)
  > library(rpm)
  Loading required package: abind
  Loading required package: future
  Loading required package: doRNG
  Loading required package: foreach
  Loading required package: rngtools
  > 
  > test_check("rpm")
  [ FAIL 1 | WARN 0 | SKIP 0 | PASS 0 ]
  
  ══ Failed tests ════════════════════════════════════════════════════════════════
  ── Error ('test-fauxmatching.R:6:3'): rpm-fit ──────────────────────────────────
  <defunctError/error/condition>
  Error: [matrixStats] Please explicitly specify argument 'ties.method' when calling colRanks() and rowRanks() of matrixStats. This is because the current default ties.method="max" will eventually be updated to ties.method="average" in order to align with the default of base::rank()
  Backtrace:
      ▆
   1. └─rpm::rpm(...) at test-fauxmatching.R:6:3
   2.   └─rpm::rpm_MLPLE(...)
   3.     └─rpm:::rpm.bootstrap.small(...)
   4.       └─rpm::Gale_Shapley(...)
   5.         └─matrixStats::rowRanks(U)
   6.           └─matrixStats:::tiesMethodMissing()
   7.             └─base (local) action(...)
  
  [ FAIL 1 | WARN 0 | SKIP 0 | PASS 0 ]
  Error: Test failures
  Execution halted
* DONE
Status: 1 ERROR, 1 WARNING, 1 NOTE