---
title: "Introduction to rifexpectile"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to rifexpectile}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 6, fig.height = 4)
```

## Motivation

Recentered influence function (RIF) regressions extend the
Oaxaca-Blinder decomposition from the mean to other distributional
statistics. Applied to quantiles, this requires estimating an inverse
density term at each quantile, which can be noisy and irregular,
especially in the tails. **rifexpectile** implements a density-free
alternative based on unconditional expectiles: the expectile RIF depends
only on primitive moments of the outcome and requires no density
estimation, no bandwidth choice, and no kernel smoothing.

The underlying methodology (the closed-form influence function, the
two-sample asymptotic theory, and an empirical application) is described
in a companion manuscript; this vignette focuses on how to use the
package, not on re-deriving that theory.

```{r setup}
library(rifexpectile)
```

## A first example with simulated data

The package ships with a small simulated data set, `wage_gap_sim`, with
a synthetic outcome `logy` observed in two waves ("2000" and "2010"),
along with covariates `x1` (continuous) and `x2` (binary), and a
stylized sampling weight. No real or proprietary data are used anywhere
in this package.

```{r}
data(wage_gap_sim)
head(wage_gap_sim)
```

The main function, `rif_decompose()`, takes a formula, a data frame, and
the name of the column identifying the two groups to compare:

```{r}
fit <- rif_decompose(
  logy ~ x1 + x2,
  data = wage_gap_sim,
  group = "group",
  ref_group = "2000",
  alpha = seq(0.1, 0.9, by = 0.2),
  boot_reps = 100,
  seed = 1
)
fit
```

The `total` column is always exactly the difference of the two groups'
sample expectiles at that level (this is a finite-sample identity, not
an approximation, whenever an intercept is included -- see
`?rif_decompose` for the algebra). The `composition` and `structure`
columns are the RIF-regression-based two-fold decomposition of that
total into an endowment effect and a returns effect.

```{r}
plot(fit, which = "structure")
```

### Covariate-level detail

The covariate-level composition and structure contributions are
available directly, and sum to the aggregate reported above:

```{r}
fit$detail_structure
colSums(fit$detail_structure)  # matches fit$structure
```

### Weighted decomposition

Passing a `weights` argument re-estimates the expectile, the RIF, and
the regression step using survey weights at every stage:

```{r}
fit_w <- rif_decompose(
  logy ~ x1 + x2,
  data = wage_gap_sim,
  group = "group",
  ref_group = "2000",
  alpha = c(0.1, 0.5, 0.9),
  weights = "weight",
  boot_reps = 100,
  seed = 1
)
fit_w
```

## A second example with public data

To illustrate the package on a widely used, publicly available data set
rather than only a simulated one, this section uses `wage1` from the
**wooldridge** package (Wooldridge, *Introductory Econometrics*), a
standard cross-section of US wages with a `female` indicator -- the
classic setting for an Oaxaca-Blinder-type decomposition of the gender
wage gap.

```{r, eval = requireNamespace("wooldridge", quietly = TRUE)}
data(wage1, package = "wooldridge")
wage1$group <- ifelse(wage1$female == 1, "female", "male")

fit_gap <- rif_decompose(
  lwage ~ educ + exper + tenure,
  data = wage1,
  group = "group",
  ref_group = "male",
  alpha = c(0.1, 0.25, 0.5, 0.75, 0.9),
  boot_reps = 200,
  seed = 1
)
fit_gap
```

```{r, eval = requireNamespace("wooldridge", quietly = TRUE)}
plot(fit_gap, which = "structure")
```

Here `ref_group = "male"` means the composition term uses male
coefficients as the reference and asks how much of the (female - male)
gap in log-wage expectiles is attributable to differences in observed
characteristics (education, experience, tenure) versus differences in
their estimated returns, at each point of the log-wage distribution
rather than only at the mean.

## Reproducibility of the underlying data

`simulate_income_data()` is the function used to generate
`wage_gap_sim`; the generating script is in `data-raw/wage_gap_sim.R`
in the package source, so the bundled example data set can be
regenerated or modified directly.

```{r}
str(simulate_income_data(n = 5, seed = 42))
```