binspwc: Data-Driven Pairwise Group Comparison using Binscatter...

Description Usage Arguments Value Author(s) References See Also Examples

View source: R/binspwc.R


binspwc implements hypothesis testing procedures for pairwise group comparison of binscatter estimators, following the results in Cattaneo, Crump, Farrell and Feng (2021a). If the binning scheme is not set by the user, the companion function binsregselect is used to implement binscatter in a data-driven way. Binned scatter plots based on different methods can be constructed using the companion functions binsreg, binsqreg or binsglm. Hypothesis testing for parametric functional forms of and shape restrictions on the regression function of interest can be conducted via the companion function binstest.


binspwc(y, x, w = NULL, data = NULL, estmethod = "reg",
  family = gaussian(), quantile = NULL, deriv = 0, at = NULL,
  nolink = F, by = NULL, pwc = c(3, 3), testtype = "two-sided",
  lp = Inf, bins = c(2, 2), bynbins = NULL, binspos = "qs",
  binsmethod = "dpi", nbinsrot = NULL, samebinsby = FALSE,
  randcut = NULL, nsims = 500, simsgrid = 20, simsseed = NULL,
  vce = NULL, cluster = NULL, asyvar = F, dfcheck = c(20, 30),
  masspoints = "on", weights = NULL, subset = NULL, numdist = NULL,
  numclust = NULL, ...)



outcome variable. A vector.


independent variable of interest. A vector.


control variables. A matrix, a vector or a formula.


an optional data frame containing variables used in the model.


estimation method. The default is estmethod="reg" for tests based on binscatter least squares regression. Other options are "qreg" for quantile regression and "glm" for generalized linear regression. If estmethod="glm", the option family must be specified.


a description of the error distribution and link function to be used in the generalized linear model when estmethod="glm". (See family for details of family functions.)


the quantile to be estimated. A number strictly between 0 and 1.


derivative order of the regression function for estimation, testing and plotting. The default is deriv=0, which corresponds to the function itself.


value of w at which the estimated function is evaluated. The default is at="mean", which corresponds to the mean of w. Other options are: at="median" for the median of w, at="zero" for a vector of zeros. at can also be a vector of the same length as the number of columns of w (if w is a matrix) or a data frame containing the same variables as specified in w (when data is specified). Note that when at="mean" or at="median", all factor variables (if specified) are excluded from the evaluation (set as zero).


if true, the function within the inverse link function is reported instead of the conditional mean function for the outcome.


a vector containing the group indicator for subgroup analysis; both numeric and string variables are supported. When by is specified, binsreg implements estimation and inference for each subgroup separately, but produces a common binned scatter plot. By default, the binning structure is selected for each subgroup separately, but see the option samebinsby below for imposing a common binning structure across subgroups.


a vector. pwc=c(p,s) sets a piecewise polynomial of degree p with s smoothness constraints for testing the difference between groups. The default is pwc=c(3,3), which corresponds to a cubic B-spline estimate of the function of interest for each group.


type of pairwise comparison test. The default is testtype="two-sided", which corresponds to a two-sided test of the form H0: mu_1(x)=mu_2(x). Other options are: testtype="left" for the one-sided test form H0: mu_1(x)<=mu_2(x) and testtype="right" for the one-sided test of the form H0: mu_1(x)>=mu_2(x).


an Lp metric used for (two-sided) parametric model specification testing and/or shape restriction testing. The default is lp=Inf, which corresponds to the sup-norm of the t-statistic. Other options are lp=q for a positive integer q.


A vector. Degree and smoothness for bin selection. The default is bins=c(2,2), which corresponds to a quadratic spline estimate.


a vector of the number of bins for partitioning/binning of x, which is applied to the binscatter estimation for each group. If not specified, the number of bins is selected via the companion function binsregselect in a data-driven way whenever possible.


position of binning knots. The default is binspos="qs", which corresponds to quantile-spaced binning (canonical binscatter). The other options are "es" for evenly-spaced binning, or a vector for manual specification of the positions of inner knots (which must be within the range of x).


method for data-driven selection of the number of bins. The default is binsmethod="dpi", which corresponds to the IMSE-optimal direct plug-in rule. The other option is: "rot" for rule of thumb implementation.


initial number of bins value used to construct the DPI number of bins selector. If not specified, the data-driven ROT selector is used instead.


if true, a common partitioning/binning structure across all subgroups specified by the option by is forced. The knots positions are selected according to the option binspos and using the full sample. If nbins is not specified, then the number of bins is selected via the companion command binsregselect and using the full sample.


upper bound on a uniformly distributed variable used to draw a subsample for bins selection. Observations for which runif()<=# are used. # must be between 0 and 1.


number of random draws for hypothesis testing. The default is nsims=500, which corresponds to 500 draws from a standard Gaussian random vector of size [(p+1)*J - (J-1)*s].


number of evaluation points of an evenly-spaced grid within each bin used for evaluation of the supremum (infimum or Lp metric) operation needed to construct hypothesis testing procedures. The default is simsgrid=20, which corresponds to 20 evenly-spaced evaluation points within each bin for approximating the supremum (infimum or Lp metric) operator.


seed for simulation.


procedure to compute the variance-covariance matrix estimator. For least squares regression and generalized linear regression, the allowed options are the same as that for binsreg or binsqreg. For quantile regression, the allowed options are the same as that for binsqreg.


cluster ID. Used for compute cluster-robust standard errors.


If true, the standard error of the nonparametric component is computed and the uncertainty related to control variables is omitted. Default is asyvar=FALSE, that is, the uncertainty related to control variables is taken into account.


adjustments for minimum effective sample size checks, which take into account number of unique values of x (i.e., number of mass points), number of clusters, and degrees of freedom of the different stat models considered. The default is dfcheck=c(20, 30). See Cattaneo, Crump, Farrell and Feng (2021b) for more details.


how mass points in x are handled. Available options:

  • "on" all mass point and degrees of freedom checks are implemented. Default.

  • "noadjust" mass point checks and the corresponding effective sample size adjustments are omitted.

  • "nolocalcheck" within-bin mass point and degrees of freedom checks are omitted.

  • "off" "noadjust" and "nolocalcheck" are set simultaneously.

  • "veryfew" forces the function to proceed as if x has only a few number of mass points (i.e., distinct values). In other words, forces the function to proceed as if the mass point and degrees of freedom checks were failed.


an optional vector of weights to be used in the fitting process. Should be NULL or a numeric vector. For more details, see lm.


optional rule specifying a subset of observations to be used.


Number of distinct for selection. Used to speed up computation.


Number of clusters for selection. Used to speed up computation.


optional arguments to control bootstrapping if estmethod="qreg" and vce="boot". See boot.rq.



A matrix. Each row corresponds to the comparison between two groups. The first column is the test statistic. The second and third columns give the corresponding group numbers. The null hypothesis is mu_i(x)<=mu_j(x), mu_i(x)=mu_j(x), or mu_i(x)>=mu_j(x) for group i (given in the second column) and group j (given in the third column). The group number corresponds to the list of group names given by opt$byvals.


A vector of p-values for all pairwise group comparisons.


A list containing options passed to the function, as well as (total sample size for each group), (number of distinct values in x for each group), (number of clusters for each group), and (number of bins for each group), and byvals (number of distinct values in by).


Matias D. Cattaneo, Princeton University, Princeton, NJ.

Richard K. Crump, Federal Reserve Bank of New York, New York, NY.

Max H. Farrell, University of Chicago, Chicago, IL.

Yingjie Feng (maintainer), Tsinghua University, Beijing, China.


Cattaneo, M. D., R. K. Crump, M. H. Farrell, and Y. Feng. 2021a: On Binscatter. Working Paper.

Cattaneo, M. D., R. K. Crump, M. H. Farrell, and Y. Feng. 2021b: Binscatter Regressions. Working Paper.

See Also

binsreg, binsqreg, binsglm, binsregselect, binstest.


 x <- runif(500); y <- sin(x)+rnorm(500); t <- 1*(runif(500)>0.5)
 ## Binned scatterplot
 binspwc(y,x, by=t)

binsreg documentation built on Oct. 11, 2021, 9:08 a.m.