% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/binsqreg.R
\name{binsqreg}
\alias{binsqreg}
\title{Data-Driven Binscatter Quantile Regression with Robust Inference Procedures and Plots}
\usage{
binsqreg(y, x, w = NULL, data = NULL, at = NULL, quantile = 0.5,
  deriv = 0, dots = NULL, dotsgrid = 0, dotsgridmean = T,
  line = NULL, linegrid = 20, ci = NULL, cigrid = 0, cigridmean = T,
  cb = NULL, cbgrid = 20, polyreg = NULL, polyreggrid = 20,
  polyregcigrid = 0, by = NULL, bycolors = NULL, bysymbols = NULL,
  bylpatterns = NULL, legendTitle = NULL, legendoff = F, nbins = NULL,
  binspos = "qs", binsmethod = "dpi", nbinsrot = NULL, pselect = NULL,
  sselect = NULL, samebinsby = F, randcut = NULL, nsims = 500,
  simsgrid = 20, simsseed = NULL, vce = "nid", cluster = NULL,
  asyvar = F, level = 95, noplot = F, dfcheck = c(20, 30),
  masspoints = "on", weights = NULL, subset = NULL, plotxrange = NULL,
  plotyrange = NULL, printplot = TRUE, qregopt = NULL, ...)
}
\arguments{
\item{y}{outcome variable. A vector.}

\item{x}{independent variable of interest. A vector.}

\item{w}{control variables. A matrix, a vector or a \code{\link{formula}}.}

\item{data}{an optional data frame containing variables in the model.}

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

\item{quantile}{the quantile to be estimated. A number strictly between 0 and 1.}

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

\item{dots}{a vector or a logical value. If \code{dots=c(p,s)}, a piecewise polynomial of degree \code{p} with
\code{s} smoothness constraints is used for point estimation and plotting as "dots".
The default is \code{dots=c(0,0)}, which corresponds to piecewise constant (canonical binscatter).
If \code{dots=T}, the default \code{dots=c(0,0)} is used unless the degree \code{p} or smoothness \code{s} selection
is requested via the option \code{pselect} or \code{sselect} (see more details in the explanation of \code{pselect} and \code{sselect}).
If \code{dots=F} is specified, the dots are not included in the plot.}

\item{dotsgrid}{number of dots within each bin to be plotted. Given the choice, these dots are point estimates
evaluated over an evenly-spaced grid within each bin. The default is \code{dotsgrid=0}, and only
the point estimates at the mean of \code{x} within each bin are presented.}

\item{dotsgridmean}{If true, the dots corresponding to the point estimates evaluated at the mean of \code{x} within each bin
are presented. By default, they are presented, i.e., \code{dotsgridmean=T}.}

\item{line}{a vector or a logical value. If \code{line=c(p,s)}, a piecewise polynomial of degree \code{p} with \code{s} smoothness constraints
is used for plotting as a "line". If \code{line=T} is specified, \code{line=c(0,0)} is used unless the degree \code{p} or smoothness \code{s}
selection is requested via the option \code{pselect} or \code{sselect} (see more details in the explanation of \code{pselect} and \code{sselect}).
If \code{line=F} or \code{line=NULL} is specified, the line is not included in the plot.  The default is \code{line=NULL}.}

\item{linegrid}{number of evaluation points of an evenly-spaced grid within each bin used for evaluation of
the point estimate set by the \code{line=c(p,s)} option. The default is \code{linegrid=20},
which corresponds to 20 evenly-spaced evaluation points within each bin for fitting/plotting the line.}

\item{ci}{a vector or a logical value. If \code{ci=c(p,s)} a piecewise polynomial of degree \code{p} with \code{s} smoothness constraints is used for
constructing confidence intervals. If \code{ci=T} is specified, \code{ci=c(1,1)} is used unless the degree \code{p} or smoothness \code{s}
selection is requested via the option \code{pselect} or \code{sselect} (see more details in the explanation of \code{pselect} and \code{sselect}).
If \code{ci=F} or \code{ci=NULL} is specified, the confidence intervals are not included in the plot.  The default is \code{ci=NULL}.}

\item{cigrid}{number of evaluation points of an evenly-spaced grid within each bin used for evaluation of the point
estimate set by the \code{ci=c(p,s)} option. The default is \code{cigrid=1}, which corresponds to 1
evenly-spaced evaluation point within each bin for confidence interval construction.}

\item{cigridmean}{If true, the confidence intervals corresponding to the point estimates evaluated at the mean of \code{x} within each bin
are presented. The default is \code{cigridmean=T}.}

\item{cb}{a vector or a logical value. If \code{cb=c(p,s)}, a the piecewise polynomial of degree \code{p} with \code{s} smoothness constraints is used for
constructing the confidence band. If the option \code{cb=T} is specified, \code{cb=c(1,1)} is used unless the degree \code{p} or smoothness \code{s}
selection is requested via the option \code{pselect} or \code{sselect} (see more details in the explanation of \code{pselect} and \code{sselect}).
If \code{cb=F} or \code{cb=NULL} is specified, the confidence band is not included in the plot. The default is \code{cb=NULL}.}

\item{cbgrid}{number of evaluation points of an evenly-spaced grid within each bin used for evaluation of the point
estimate set by the \code{cb=c(p,s)} option. The default is \code{cbgrid=20}, which corresponds
to 20 evenly-spaced evaluation points within each bin for confidence interval construction.}

\item{polyreg}{degree of a global polynomial regression model for plotting. By default, this fit is not included
in the plot unless explicitly specified. Recommended specification is \code{polyreg=3}, which
adds a cubic (global) polynomial fit of the regression function of interest to the binned scatter plot.}

\item{polyreggrid}{number of evaluation points of an evenly-spaced grid within each bin used for evaluation of
the point estimate set by the \code{polyreg=p} option. The default is \code{polyreggrid=20},
which corresponds to 20 evenly-spaced evaluation points within each bin for confidence
interval construction.}

\item{polyregcigrid}{number of evaluation points of an evenly-spaced grid within each bin used for constructing
confidence intervals based on polynomial regression set by the \code{polyreg=p} option.
The default is \code{polyregcigrid=0}, which corresponds to not plotting confidence
intervals for the global polynomial regression approximation.}

\item{by}{a vector containing the group indicator for subgroup analysis; both numeric and string variables
are supported. When \code{by} is specified, \code{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 \code{samebinsby} below for imposing a common binning structure across subgroups.}

\item{bycolors}{an ordered list of colors for plotting each subgroup series defined by the option \code{by}.}

\item{bysymbols}{an ordered list of symbols for plotting each subgroup series defined by the option \code{by}.}

\item{bylpatterns}{an ordered list of line patterns for plotting each subgroup series defined by the option \code{by}.}

\item{legendTitle}{String, title of legend.}

\item{legendoff}{If true, no legend is added.}

\item{nbins}{number of bins for partitioning/binning of \code{x}.  If \code{nbins=T} or \code{nbins=NULL} (default) is specified, the number
of bins is selected via the companion command \code{\link{binsregselect}} in a data-driven, optimal way whenever possible.
If a vector with more than one number is specified, the number of bins is selected within this vector via the companion command \code{\link{binsregselect}}.}

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

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

\item{nbinsrot}{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.}

\item{pselect}{vector of numbers within which the degree of polynomial \code{p} for point estimation is selected.
 Piecewise polynomials of the selected optimal degree \code{p} are used to construct dots or line
 if \code{dots=T} or \code{line=T} is specified,
 whereas piecewise polynomials of degree \code{p+1} are used to construct confidence intervals
 or confidence band if \code{ci=T} or \code{cb=T} is specified.
 \emph{Note:} To implement the degree or smoothness selection, in addition to \code{pselect} or \code{sselect},
\code{nbins=#} must be specified.}

\item{sselect}{vector of numbers within which the number of smoothness constraints \code{s} for point estimation is selected.
Piecewise polynomials with the selected optimal \code{s} smoothness constraints are used to construct dots or line
 if \code{dots=T} or \code{line=T} is specified,
whereas piecewise polynomials with \code{s+1} constraints are used to construct
confidence intervals or confidence band if \code{ci=T} or \code{cb=T} is
specified.  If not specified, for each value \code{p} supplied in the option \code{pselect}, only the piecewise polynomial
with the maximum smoothness is considered, i.e., \code{s=p}.}

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

\item{randcut}{upper bound on a uniformly distributed variable used to draw a subsample for bins/degree/smoothness selection.
Observations for which \code{runif()<=#} are used. # must be between 0 and 1.  By default, \code{max(5000, 0.01n)} observations
are used if the samples size \code{n>5000}.}

\item{nsims}{number of random draws for constructing confidence bands. The default is
\code{nsims=500}, which corresponds to 500 draws from a standard Gaussian random vector of size
\code{[(p+1)*J - (J-1)*s]}. Setting at least \code{nsims=2000} is recommended to obtain the final results.}

\item{simsgrid}{number of evaluation points of an evenly-spaced grid within each bin used for evaluation of
the supremum operation needed to construct confidence bands. The default is \code{simsgrid=20}, which corresponds to 20 evenly-spaced
evaluation points within each bin for approximating the supremum operator.
Setting at least \code{simsgrid=50} is recommended to obtain the final results.}

\item{simsseed}{seed for simulation.}

\item{vce}{Procedure to compute the variance-covariance matrix estimator (see \code{\link[quantreg]{summary.rq}} for more details). Options are
\itemize{
\item \code{"iid"} which presumes that the errors are iid and computes an estimate of the asymptotic covariance matrix as in KB(1978).
\item \code{"nid"} which presumes local (in quantile) linearity of the the conditional quantile functions and computes a Huber sandwich estimate using a local estimate of the sparsity.
\item \code{"ker"} which uses a kernel estimate of the sandwich as proposed by Powell (1991).
\item \code{"boot"} which implements one of several possible bootstrapping alternatives for estimating standard errors including a variate of the wild bootstrap for clustered response. See \code{\link[quantreg]{boot.rq}} for further details.
}}

\item{cluster}{cluster ID. Used for compute cluster-robust standard errors.}

\item{asyvar}{if true, the standard error of the nonparametric component is computed and the uncertainty related to control
variables is omitted. Default is \code{asyvar=FALSE}, that is, the uncertainty related to control variables is taken into account.}

\item{level}{nominal confidence level for confidence interval and confidence band estimation. Default is \code{level=95}.}

\item{noplot}{if true, no plot is produced, but requested plotting data are still returned.}

\item{dfcheck}{adjustments for minimum effective sample size checks, which take into account number of unique
values of \code{x} (i.e., number of mass points), number of clusters, and degrees of freedom of
the different statistical models considered. The default is \code{dfcheck=c(20, 30)}.
See \href{https://nppackages.github.io/references/Cattaneo-Crump-Farrell-Feng_2025_Stata.pdf}{Cattaneo, Crump, Farrell and Feng (2025)} for more details.}

\item{masspoints}{how mass points in \code{x} are handled. Available options:
\itemize{
\item \code{"on"} all mass point and degrees of freedom checks are implemented. Default.
\item \code{"noadjust"} mass point checks and the corresponding effective sample size adjustments are omitted.
\item \code{"nolocalcheck"} within-bin mass point and degrees of freedom checks are omitted.
\item \code{"off"} "noadjust" and "nolocalcheck" are set simultaneously.
\item \code{"veryfew"} forces the function to proceed as if \code{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.
}}

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

\item{subset}{optional rule specifying a subset of observations to be used.}

\item{plotxrange}{a vector. \code{plotxrange=c(min, max)} specifies a range of the x-axis for plotting. Observations outside the range are dropped in the plot.}

\item{plotyrange}{a vector. \code{plotyrange=c(min, max)} specifies a range of the y-axis for plotting. Observations outside the range are dropped in the plot.}

\item{printplot}{if true, the generated \code{ggplot} object is printed when \code{noplot=FALSE}. If false, the plot object is returned without printing.}

\item{qregopt}{a list of optional arguments used by \code{\link[quantreg]{rq}}.}

\item{...}{optional arguments to control bootstrapping. See \code{\link[quantreg]{boot.rq}}.}
}
\value{
\item{\code{bins_plot}}{A \code{ggplot} object for binscatter plot.}
       \item{\code{data.plot}}{A list containing data for plotting. Each item is a sublist of data frames for each group. Each sublist may contain the following data frames:
       Plotting data frames with a bin indicator include \code{n}, the number of observations in the corresponding bin.
       \itemize{
       \item \code{data.dots} Data for dots. It contains: \code{x}, evaluation points; \code{bin}, the indicator of bins;
                              \code{isknot}, indicator of inner knots; \code{mid}, midpoint of each bin; and \code{fit}, fitted values.
       \item \code{data.line} Data for line. It contains: \code{x}, evaluation points; \code{bin}, the indicator of bins;
                               \code{isknot}, indicator of inner knots; \code{mid}, midpoint of each bin; and \code{fit}, fitted values.
       \item \code{data.ci} Data for CI. It contains: \code{x}, evaluation points; \code{bin}, the indicator of bins;
                               \code{isknot}, indicator of inner knots; \code{mid}, midpoint of each bin;
                               \code{ci.l} and \code{ci.r}, left and right boundaries of each confidence intervals.
       \item \code{data.cb} Data for CB. It contains: \code{x}, evaluation points; \code{bin}, the indicator of bins;
                               \code{isknot}, indicator of inner knots; \code{mid}, midpoint of each bin;
                               \code{cb.l} and \code{cb.r}, left and right boundaries of the confidence band.
       \item \code{data.poly} Data for polynomial regression. It contains: \code{x}, evaluation points;
                               \code{bin}, the indicator of bins;
                               \code{isknot}, indicator of inner knots; \code{mid}, midpoint of each bin; and
                               \code{fit}, fitted values.
       \item \code{data.polyci} Data for confidence intervals based on polynomial regression. It contains: \code{x}, evaluation points;
                               \code{bin}, the indicator of bins;
                               \code{isknot}, indicator of inner knots; \code{mid}, midpoint of each bin;
                               \code{polyci.l} and \code{polyci.r}, left and right boundaries of each confidence intervals.
       \item \code{data.bin} Data for the binning structure. It contains: \code{bin.id}, ID for each bin;
                               \code{left.endpoint} and \code{right.endpoint}, left and right endpoints of each bin;
                               and \code{n}, number of observations in each bin.}}
       \item{\code{imse.var.rot}}{Variance constant in IMSE, ROT selection.}
       \item{\code{imse.bsq.rot}}{Bias constant in IMSE, ROT selection.}
       \item{\code{imse.var.dpi}}{Variance constant in IMSE, DPI selection.}
       \item{\code{imse.bsq.dpi}}{Bias constant in IMSE, DPI selection.}
       \item{\code{cval.by}}{A vector of critical values for constructing confidence band for each group.}
       \item{\code{opt}}{ A list containing options passed to the function, as well as \code{N.by} (total sample size for each group),
                          \code{Ndist.by} (number of distinct values in \code{x} for each group), \code{Nclust.by} (number of clusters for each group),
                          and \code{nbins.by} (number of bins for each group), and \code{byvals} (number of distinct values in \code{by}).
                          The degree and smoothness of polynomials for dots, line, confidence intervals and confidence band for each group are saved
                          in \code{dots}, \code{line}, \code{ci}, and \code{cb}.}
       \item{\code{call}}{The matched function call.}
}
\description{
\code{binsqreg} implements binscatter quantile regression with robust inference procedures and plots, following the
            results in \href{https://nppackages.github.io/references/Cattaneo-Crump-Farrell-Feng_2024_AER.pdf}{Cattaneo, Crump, Farrell and Feng (2024)} and
            \href{https://nppackages.github.io/references/Cattaneo-Crump-Farrell-Feng_2026_RESTAT.pdf}{Cattaneo, Crump, Farrell and Feng (2026)}.
            Binscatter provides a flexible way to describe the quantile relationship between two variables, after
            possibly adjusting for other covariates, based on partitioning/binning of the independent variable of interest.
            The main purpose of this function is to generate binned scatter plots with curve estimation with robust pointwise confidence intervals and
            uniform confidence band.  If the binning scheme is not set by the user, the companion function
            \code{\link{binsregselect}} is used to implement binscatter in a data-driven way. Hypothesis testing about the function of interest
            can be conducted via the companion function \code{\link{binstest}}.
}
\examples{
 x <- runif(500); y <- sin(x)+rnorm(500)
 ## Binned scatterplot
 binsqreg(y,x)
}
\references{
Cattaneo, M. D., R. K. Crump, M. H. Farrell, and Y. Feng. 2024: \href{https://nppackages.github.io/references/Cattaneo-Crump-Farrell-Feng_2024_AER.pdf}{On Binscatter}. American Economic Review 114(5): 1488-1514.

Supplemental Appendix for On Binscatter: \href{https://nppackages.github.io/references/Cattaneo-Crump-Farrell-Feng_2024_AER--Supplemental.pdf}{Supplemental Appendix}.

Cattaneo, M. D., R. K. Crump, M. H. Farrell, and Y. Feng. 2026: \href{https://nppackages.github.io/references/Cattaneo-Crump-Farrell-Feng_2026_RESTAT.pdf}{Nonlinear Binscatter Methods}. Review of Economics and Statistics, revise and resubmit.

Supplemental Appendix for Nonlinear Binscatter Methods: \href{https://nppackages.github.io/references/Cattaneo-Crump-Farrell-Feng_2026_RESTAT--Supplemental.pdf}{Supplemental Appendix}.

Cattaneo, M. D., R. K. Crump, M. H. Farrell, and Y. Feng. 2025: \href{https://nppackages.github.io/references/Cattaneo-Crump-Farrell-Feng_2025_Stata.pdf}{Binscatter Regressions}. Stata Journal 25(1): 3-50.
}
\seealso{
\code{\link{binsregselect}}, \code{\link{binstest}}.
}
\author{
Matias D. Cattaneo (maintainer). \email{matias.d.cattaneo@gmail.com}.

Richard K. Crump. \email{richard.crump@gmail.com}.

Max H. Farrell. \email{mhfarrell@gmail.com}.

Yingjie Feng. \email{fengyingjiepku@gmail.com}.
}
