Linear Gini Index Regression (GIR) in R. gir() fits the
two-stage estimator of Bhardwaj and Diaz-Villarejo (2026): a
least-squares series first stage for the conditional mid-distribution
function and a weighted linear projection for the conditional Gini
index. bboot.gir() provides Bayesian-bootstrap inference
(basic confidence intervals, standard errors, covariance, tests of
smooth coefficient transformations) and predict.gir()
evaluates the fitted conditional Gini index with pointwise
uncertainty.
Before the first CRAN release, installation from GitHub requires access to the private repository:
# install.packages("remotes")
remotes::install_github("uptoaparameter/GIR", build_vignettes = TRUE)Building the guide from GitHub requires LaTeX. A source package
produced by R CMD build already contains the guide PDF and
can be installed without LaTeX or roxygen2. To install from GitHub
without building the guide, omit
build_vignettes = TRUE.
Use ?gir, ?bboot.gir and
?predict.gir for function help. Open the detailed guide
with vignette("GIR-guide", package = "GIR") and retrieve
the software and paper references with citation("GIR").
library(GIR)
set.seed(150)
n <- 2000L
dat <- data.frame(x1 = runif(n, 0.1, 1),
x2 = rbinom(n, 1, 0.5), x3 = rbinom(n, 1, 0.5))
m <- with(dat, 0.075*x1 + 0.100*x2 + 0.125*x3)
dat$y <- rbeta(n, (1-m)/(2*m), 1)
fit <- gir(y ~ 0 + x1 + x2 + x3, data = dat,
continuous = "x1", discrete = c("x2", "x3"),
basis = "spline", basis_bounds = list(x1 = c(0.1, 1)))
summary(fit)
boot <- bboot.gir(fit, R = 999, seed = 42)
summary(boot)
confint(boot)
vcov(boot)
summary(boot, transform = c(x2 = 1, x3 = -1), null = 0)
nd <- data.frame(x1 = c(0.2, 0.8), x2 = 1, x3 = 0)
predict(fit, nd, interval = "confidence", se.fit = TRUE, bootstrap = boot)The first stage is estimated separately in every cell formed by the
discrete variables, with a tensor-product Legendre or
spline basis in the continuous ones; the user declares
which variables are which. The bootstrap refits both stages with the
same normalized exponential multipliers and keeps the estimation sample,
cells, basis sizes and bounds fixed. t0 and t
contain the untransformed coefficients and draws, which tests and
predictions reuse.
For clustered multipliers, cluster = ~ industry + region
creates one cluster for each distinct industry-region combination. This
is one-way clustering at the intersections, not two-way clustering by
the two variables separately. Clusters are identified by the values of
their defining variables and numbered in order of first occurrence. The
paper’s bootstrap theorem assumes independent observations; clustered
inference requires separate justification.
For a cluster vector, use cluster_order = "original"
when its labels follow the original dataset’s order at fitting time. The
stored fit$row.index aligns it to the estimation sample.
Use cluster_order = "estimation" for labels already in
final estimation-row order. The default "auto" infers the
order from length, but requires an explicit choice when both lengths
match and the row mapping has changed (for example, a reordered
subset). Formulas such as cluster = ~ industry
already use aligned retained columns; leave
cluster_order = "auto" for formulas or when no clustering
is requested. These controls also work in
predict(..., se.fit = TRUE) when it generates the
bootstrap; the cluster labels describe the fitting sample, not
newdata.
predict() estimates the conditional Gini
index, not individual outcomes. Its intervals are pointwise
basic intervals, not simultaneous bands. For an externally supplied
midcdf, a refitting callback or an explicit fixed
first-stage choice is required for bootstrap inference.
na.omit and na.exclude remove rows with
missing values in either stage, the case weights or supplied mid-CDF
values. Fitting requires at least one retained observation with positive
weight. An empty sample or loss of all positive weights produces a
specific error before the routine removal warning. Missing weights
follow the selected na.action policy.
Support checks use the retained sample: if omission leaves an
undeclared numeric first-stage variable with at most two distinct
values, declare it explicitly in discrete or
continuous. Custom missing-value actions report how many
removed rows had missing values and how many were complete; their own
failures are identified without assuming missing data caused them.
Prediction preserves empty outputs: no prediction rows gives an empty
vector or a zero-row confidence-interval matrix. na.exclude
restores missing positions as NA. Numerical and inference
warnings identify issues that need attention before interpreting a
fit.
The default first_stage_singular = "error" stops on a
singular or ill-conditioned first stage. If you explicitly select
"ridge", the default ridge = 1e-10 is a
numerical stabilization heuristic. The initial diagonal penalty is
ridge * mean(diag(G)), where G is the weighted
cell Gram matrix; it scales with the weights. A failed solve receives an
additional 100 times that base penalty. Inspect
fit$first_stage$diagnostics$ridge_lambda for the total
amount used. This parameter is not selected by cross-validation or
prescribed by the paper’s theory, and its effect can be substantial in
poorly identified directions. Assess sensitivity when using ridge.
Common weight scaling preserves internal fits up to floating-point error
within usable numerical ranges; external first-stage callbacks need
their own guarantees.
The test suite checks both stages against independent threshold regressions, saturated group estimates against the pairwise empirical Gini, outcome-unit and row-order invariance, and the GIR-R-squared loss decomposition. It also checks paired bootstrap draws and the arithmetic of basic confidence intervals. The mathematical tests use full-rank designs without ridge or clipping; cluster and ridge behavior have separate tests.
Run testthat::test_local(filter = "math-") from the
source directory for these checks, or
testthat::test_local() for the complete suite. The tests
also run during R CMD check and need neither the draft
paper nor network access. See
help("GIR-validation", package = "GIR") for the
correspondence with the paper’s lemmas and algorithms, numerical
tolerances and limitations. These finite-sample checks do not establish
asymptotic validity or nominal confidence-interval coverage; those
require separate theoretical and simulation assessment.
The help files are generated from the roxygen comments in
R/; after editing them run
roxygen2::roxygenize() in the package directory. Run
testthat::test_local() for the tests. Release checks also
build and check the PDF guide and function reference. Maintainer build
instructions are in tools/README.md in the source
repository. The guide’s editable source is
vignettes/GIR-guide.Rnw.
Bhardwaj, V. and Diaz-Villarejo, D. (2026). Gini Index Regression. Working paper, Universidad Carlos III de Madrid.