---
title: "Uniform inference for ranked subgroups"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Uniform inference for ranked subgroups}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse=TRUE,comment="#>")
```

A scoring rule ranks the evaluation population before outcomes are used to
choose a subgroup size. `URATE()` estimates the effect among the highest-ranked
fraction and constructs a uniform confidence band over all subgroup sizes.
The rule may be fitted on independent training data. Inference conditions on
that realized rule and does not require it to consistently estimate CATE.
The evaluation data must satisfy the manuscript's random-sampling and complete-
randomization assumptions. Cross-validated scores require a different argument
and are not supported by this uniform-band procedure.

```{r}
library(evalHTE)
set.seed(91)
n <- 120
score <- rnorm(n)  # a prespecified rule in this simulated example
D <- sample(rep(0:1, each=n/2))
Y <- rnorm(n) + D*(1+score)
band <- URATE(D, score, Y, alpha=.1, L=1000, seed=801)
k <- band$selected
data.frame(n_selected=k,proportion=band$p[k],effect=band$rate[k],
           lower=band$lower[k])
```

The selected size maximizes the uniform lower bound, with ties resolved in
favor of the smallest subgroup. The uniform guarantee permits this selection.
A pointwise interval or p-value at that size would not provide the same
post-selection guarantee. Coverage applies to one rule and outcome; choosing
among multiple models or covariates is not covered by that guarantee.

```{r, fig.width=6, fig.height=4}
plot_CI(band)
```

The plot uses the stored calibration. Supplying `alpha` to `plot_CI()` or to
`summary()` for an evaluated HTE object recalibrates the same reference with the
same seed. Two-sided bands require `side="two.sided"` at evaluation and are
calibrated using absolute Gaussian paths. An upper band uses `side="upper"`.

For a baseline covariate, use `D=NULL`. The following curve compares each
subgroup's covariate mean with the evaluation population mean. The endpoint
contrast is zero by construction. Selection based on this curve minimizes the
upper bound; evaluating a subgroup selected by another curve instead uses its
rank index directly.

```{r}
X <- score + rnorm(n)
composition <- URATE(NULL, score, X, adjustment="difference", side="upper",
                     alpha=.1, L=1000, seed=2801)
c(estimate=composition$rate[k],upper=composition$upper[k])
```

To use fitted models, retain an independent evaluation sample through the
existing sample-splitting workflow:

```{r, eval=FALSE}
fit <- estimate_hte(treatment="D",form=Y ~ D + X,data=training_and_evaluation,
                    algorithms="causal_forest",split_ratio=.4,ngates=5)
result <- evaluate_hte(fit,alpha=.1,L=50000,seed=801)
summary(result)
plot_CI(result)
```

`URATE()` uses uncentered outcomes and the observed evaluation treatment
fraction. It estimates the marginal effect in consecutive rank blocks with a
finite-block residual correction. Gaussian draws retain the dependence from
the estimated ranking threshold and fixed treatment counts. Each endpoint
contrast transforms the entire draw before calibration.

The default objective minimizes cumulative boundary area. `objective="gates"`
minimizes the area of the GATES band above `p_min`; this integration limit does
not restrict the coverage or selection domain. The finite slope grid and Monte
Carlo quantiles approximate the asymptotic procedure. A warning at the largest
slope calls for a wider grid, and final analyses should increase `L`.

The revised prostate application uses `alpha=.1`, `L=50000`, the cumulative
objective, and model-specific seeds 801 through 804. Exact replication also
requires the paper's saved split, preprocessing, fitted scores, and model
settings. The generic training defaults do not reproduce those fitted models.
The paper adds a fixed Gaussian perturbation to its scores before evaluation;
pass those saved scores without adding another perturbation. Package tie
handling randomizes exact ties only. Neither evaluation nor plotting changes
the caller's random-number state.