% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/binsregselect.R
\name{binsregselect}
\alias{binsregselect}
\title{Data-Driven IMSE-Optimal Partitioning/Binning Selection for Binscatter}
\usage{
binsregselect(y, x, w = NULL, data = NULL, deriv = 0, bins = NULL,
  pselect = NULL, sselect = NULL, binspos = "qs", nbins = NULL,
  binsmethod = "dpi", nbinsrot = NULL, simsgrid = 20, savegrid = F,
  vce = "HC1", useeffn = NULL, randcut = NULL, cluster = NULL,
  dfcheck = c(20, 30), masspoints = "on", weights = NULL,
  subset = NULL, norotnorm = F, numdist = NULL, numclust = 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 used in the model.}

\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{bins}{a vector. \code{bins=c(p,s)} set a piecewise polynomial of degree \code{p} with \code{s} smoothness constraints
for data-driven (IMSE-optimal) selection of the partitioning/binning scheme. By default, the function sets
\code{bins=c(0,0)}, which corresponds to piecewise constant (canonical binscatter).}

\item{pselect}{vector of numbers within which the degree of polynomial \code{p} for point estimation is selected.
\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.
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{binspos}{position of binning knots.  The default is \code{binspos="qs"}, which corresponds to quantile-spaced
binning (canonical binscatter).  The other option is \code{binspos="es"} for evenly-spaced binning.}

\item{nbins}{number of bins for degree/smoothness selection. If \code{nbins=T} or \code{nbins=NULL} (default) is specified,
the function selects the number of bins instead, given the specified degree and smoothness.
If a vector with more than one number is specified, the command selects the number of bins within this vector.}

\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{simsgrid}{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 confidence bands and hypothesis testing
procedures. The default is \code{simsgrid=20}, which corresponds to 20 evenly-spaced
evaluation points within each bin for approximating the supremum (infimum or Lp metric) operator.}

\item{savegrid}{if true, a data frame produced containing grid.}

\item{vce}{procedure to compute the variance-covariance matrix estimator. Options are
\itemize{
\item \code{"const"} homoskedastic variance estimator.
\item \code{"HC0"} heteroskedasticity-robust plug-in residuals variance estimator
                   without weights.
\item \code{"HC1"} heteroskedasticity-robust plug-in residuals variance estimator
                   with hc1 weights. Default.
\item \code{"HC2"} heteroskedasticity-robust plug-in residuals variance estimator
                   with hc2 weights.
\item \code{"HC3"} heteroskedasticity-robust plug-in residuals variance estimator
                   with hc3 weights.
}}

\item{useeffn}{effective sample size to be used when computing the (IMSE-optimal) number of bins. This option
is useful for extrapolating the optimal number of bins to larger (or smaller) datasets than
the one used to compute it.}

\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.}

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

\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{norotnorm}{if true, a uniform density rather than normal density used for ROT selection.}

\item{numdist}{number of distinct values for selection. Used to speed up computation.}

\item{numclust}{number of clusters for selection. Used to speed up computation.}
}
\value{
\item{\code{nbinsrot.poly}}{ROT number of bins, unregularized.}
       \item{\code{nbinsrot.regul}}{ROT number of bins, regularized.}
       \item{\code{nbinsrot.uknot}}{ROT number of bins, unique knots.}
       \item{\code{nbinsdpi}}{DPI number of bins.}
       \item{\code{nbinsdpi.uknot}}{DPI number of bins, unique knots.}
       \item{\code{prot.poly}}{ROT degree of polynomials, unregularized.}
       \item{\code{prot.regul}}{ROT degree of polynomials, regularized.}
       \item{\code{prot.uknot}}{ROT degree of polynomials, unique knots.}
       \item{\code{pdpi}}{DPI degree of polynomials.}
       \item{\code{pdpi.uknot}}{DPI degree of polynomials, unique knots.}
       \item{\code{srot.poly}}{ROT number of smoothness constraints, unregularized.}
       \item{\code{srot.regul}}{ROT number of smoothness constraints, regularized.}
       \item{\code{srot.uknot}}{ROT number of smoothness constraints, unique knots.}
       \item{\code{sdpi}}{DPI number of smoothness constraints.}
       \item{\code{sdpi.uknot}}{DPI number of smoothness constraints, unique knots.}
       \item{\code{imse.var.rot}}{Variance constant in IMSE expansion, ROT selection.}
       \item{\code{imse.bsq.rot}}{Bias constant in IMSE expansion, ROT selection.}
       \item{\code{imse.var.dpi}}{Variance constant in IMSE expansion, DPI selection.}
       \item{\code{imse.bsq.dpi}}{Bias constant in IMSE expansion, DPI selection.}
       \item{\code{int.result}}{Intermediate results, including a matrix of degree and smoothness (\code{deg_mat}),
                                the selected numbers of bins (\code{vec.nbinsrot.poly},\code{vec.nbinsrot.regul},
                                \code{vec.nbinsrot.uknot}, \code{vec.nbinsdpi}, \code{vec.nbinsdpi.uknot}),
                                and the bias and variance constants in IMSE (\code{vec.imse.b.rot},
                                \code{vec.imse.v.rot}, \code{vec.imse.b.dpi}, \code{vec.imse.v.dpi})
                                under each rule (ROT or DPI), corresponding to each pair of degree and smoothness
                                (each row in \code{deg_mat}).}
       \item{\code{opt}}{ A list containing options passed to the function, as well as total sample size \code{n},
                          number of distinct values \code{Ndist} in \code{x}, and number of clusters \code{Nclust}.}
       \item{\code{knot}}{A vector containing the selected or user-specified knots.}
       \item{\code{data.grid}}{A data frame containing grid.}
       \item{\code{call}}{The matched function call.}
}
\description{
\code{binsregselect} implements data-driven procedures for selecting the number of bins for binscatter
            estimation. The selected number is optimal in minimizing integrated mean squared error (IMSE).
}
\examples{
 x <- runif(500); y <- sin(x)+rnorm(500)
 est <- binsregselect(y,x)
 summary(est)
}
\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{binsreg}}, \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}.
}
