---
title: "Drawing a Sequential Poisson Sample"
vignette: >
  %\VignetteIndexEntry{Drawing a Sequential Poisson Sample}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
knitr:
  opts_chunk: 
    collapse: true
    comment: '#>'
---

Sequential Poisson sampling is a variation of Poisson sampling for drawing probability-proportional-to-size samples with a given number of units. It's a fast, simple, and flexible method for sampling units proportional to their size, and is often used for drawing a sample of businesses. The purpose of this vignette is to give an example of how the functions in this package can be used to easily draw a sample using the sequential Poisson method. More details can be found on the help pages for the functions used in this vignette.

## Drawing a sample of businesses

Consider the problem of drawing a sample of businesses in order to measure the value of sales for the current quarter. The frame is a business register that gives an enumeration of all businesses in operation, along with the revenue of each business from the previous year and the region in which they are headquartered.

```{r frame}
library(sps)
set.seed(123654)

frame <- data.frame(
  revenue = round(rlnorm(1e3) * 1000),
  region = sample(1:3, 1e3, prob = c(0.2, 0.3, 0.5), replace = TRUE)
)

head(frame)
```

Associated with each business is a value for their sales for the current quarter, although these values are not observable for all businesses. The purpose of drawing a sample is to observe sales for a subset of businesses, and extrapolate the value of sales from the sample of business to the entire population. Sales are positively correlated with last year's revenue, and this is the basis for sampling businesses proportional to revenue.

```{r outcome}
sales <- round(frame$revenue * runif(1e3, 0.5, 2))
```

Budget constraints mean that it's feasible to draw a sample of 100 businesses. Businesses operate in different regions, and so the sample will be stratified by region. This requires determining how the total sample size of 100 is allocated across regions. A common approach is to do this allocation proportional to the total revenue in each region.

```{r allocation}
allocation <- with(frame, prop_allocation(revenue, 100, region))
allocation
```

With the sample size for each region in hand, it's now time to draw a sample and observe the value of sales for these businesses. In practice this is usually the result of a survey that's administered to the sampled units.

```{r sample}
sample <- with(frame, sps(revenue, allocation, region))

survey <- cbind(frame[sample, ], sales = sales[sample])

head(survey)
```

An important piece of information from the sampling process is the design weights, as these enable estimating the value of sales in the population with the usual Horvitz-Thompson estimator.

```{r weights}
survey$weight <- weights(sample)

head(survey)
```

```{r estimate}
ht <- with(survey, sum(sales * weight))
ht
```

The Horvitz-Thompson estimator is (asymptotically) unbiased under sequential Poisson sampling, so it should be no surprise that the estimate is fairly close the true (but unknown) value of sales among all businesses.

```{r bias}
ht / sum(sales) - 1
```

But in practice it's not possible to determine how far an estimate is from the true value in the population. Instead, a common measure of the quality of a estimate is the coefficient of variation, and this requires estimating the variance of the Horvitz-Thompson estimator.

A general approach for estimating the variance of the Horvitz-Thompson estimator is to construct bootstrap replicate weights from the design weights for the sample, compute a collection of estimates for the total based on these replicate weights, and then compute the variance of this collection of estimates. 

```{r variance}
repweights <- sps_repweights(weights(sample))

var <- attr(repweights, "tau")^2 *
  mean((colSums(survey$sales * repweights) - ht)^2)

sqrt(var) / ht
```

There is also an analytic estimator for the variance of the Horvitz-Thompson estimator under sequential Poisson sampling. It's less flexible than the bootstrap estimator, but is more precise.

```{r variance2}
sps_var <- function(y, w) {
  y <- y[w > 1]
  w <- w[w > 1]
  n <- length(y)
  total <- sum(y * w)
  n / (n - 1) * sum((1 - 1 / w) * (w * y - total / n)^2)
}

var <- with(
  survey,
  mapply(sps_var, split(sales, region), split(weight, region))
)

sqrt(sum(var)) / ht
```

## Coordinating samples

Suppose another sample of businesses from the same frame is needed for a purpose other than measuring the value of sales. It is often desirable to negatively coordinate these samples so that the same businesses are not inundated with responding to surveys, without affecting the statistical properties of the sample. This sort of coordination is easily done by associating to each business a permanent random number, and suitably "rotating" them to reduce the overlap between both samples.

```{r prns}
frame$prn <- runif(1000)

head(frame)
```

Permanent random numbers can be used with methods other than sequential Poisson---the procedure is the same for any order sampling scheme (including simple random sampling).

```{r prn samples}
pareto <- order_sampling(\(x) x / (1 - x))

sample <- with(frame, sps(revenue, allocation, region, prn))

parsample <- with(frame, pareto(revenue, allocation, region, (prn - 0.5) %% 1))

length(intersect(sample, parsample)) / 100
```

Although there is still a meaningful overlap between the units in both samples, this is roughly half of what would be expected without using permanent random numbers.

```{r prn simualtion}
replicate(1000, {
  s <- with(frame, pareto(revenue, allocation, region))
  length(intersect(sample, s)) / 100
}) |>
  summary()
```

## Topping up

The sequential part of sequential Poisson sampling means that it's easy to grow a sample. Suppose that there is a need to sample 10 more businesses in region 1 after the sample is drawn. Simply adding 10 units to the allocation for region 1 results in a new sample that includes all the previously sampled units, so the extra units can be surveyed without discarding previously-collected data or affecting the statistical properties of the sample.

```{r top up}
sample <- with(frame, sps(revenue, allocation, region, prn))

sample_tu <- with(frame, sps(revenue, allocation + c(10, 0, 0), region, prn))

all(sample %in% sample_tu)
```

As with any proportional-to-size sampling scheme, there is a critical sample size after which some units become take-all units. If these units are not already in the sample then they can "bump" previously sampled units, requiring a larger sample size to keep all the previously sampled units in the new sample. This can be seen by finding the sample size at which each unit enters the take-all stratum.

```{r critical}
Map(\(x) head(becomes_ta(x)), split(frame$revenue, frame$region))
```

But this is rare in practice. For this example there is no point at which increasing the sample size drops a unit that was previously included in the sample. Seeing this in action requires different data.

```{r no_tu}
set.seed(13026)
x <- rlnorm(10)
u <- runif(10)

becomes_ta(x)

sample <- sps(x, 4, prn = u)

sample %in% sps(x, 5, prn = u)
```

The solution to this problem is to simply increase the size of the sample until all previously sampled units are included.

```{r yes_tu}
sample %in% sps(x, 6, prn = u)
```

It's possible to go one step further and make an iterator that draws the next unit in the sample without replacing the old ones, and gives the same result as directly drawing that many units.

```{r}
s <- sps_iterator(x, prn = u)
for (i in 1:5) {
  print(s())
}

sps(x, 6, prn = u)
```

Note that the ability to update a sample like this is not shared by the Pareto and successive order sampling schemes. For both of those methods, increasing the size of the sample can replace previously-sampled units, even without any take-all units.

```{r}
set.seed(10052)
u <- runif(10)
pareto(x, 2, prn = u) %in% pareto(x, 3, prn = u)

set.seed(10063)
u <- runif(10)
successive <- order_sampling(\(x) log(1 - x))
successive(x, 2, prn = u) %in% successive(x, 3, prn = u)
```

## Bias in the Horvitz-Thompson estimator

Despite it's simplicity, sequential Poisson sampling is only asymptotically proportional to size. This means that the Horvitz-Thompson estimator can be biased in small samples, although this bias is usually negligible for real-world sample sizes.

```{r ht bias}
sampling_distribution <- replicate(1000, {
  sample <- with(frame, sps(revenue, allocation, region))
  sum(sales[sample] * weights(sample))
})

summary(sampling_distribution / sum(sales) - 1)
```

More generally, the distribution of inclusion probabilities
is usually close to what is expected if sequential Poisson sampling was exactly proportional to size.^[See Tillé, Y. (2023). Remarks on some misconceptions about unequal probability sampling without replacement. *Computer Science Review*, 47, 100533.]

```{r tille, fig.width=8, fig.height=5.33}
#| fig.alt: >
#|   Empirical distribution of inclusion probabilities under sequential Poisson
#|   sampling is approximately Guassian.
set.seed(123456)
n <- 5e3
frame1 <- subset(frame, region == 1)

pi_est <- tabulate(
  replicate(n, sps(frame1$revenue, allocation[1])),
  nbins = nrow(frame1)
)

pi <- inclusion_prob(frame1$revenue, allocation[1])

dist <- (pi_est / n - pi) / sqrt(pi * (1 - pi) / n)

plot(
  density(dist, na.rm = TRUE),
  ylim = c(0, 0.5),
  xlim = c(-4, 4),
  ylab = "",
  xlab = "",
  main = "Empirical distribution of inclusion probabilities"
)
lines(seq(-4, 4, 0.1), dnorm(seq(-4, 4, 0.1)), lty = "dashed")
legend("topright", c("empirical", "theoretical"), lty = c("solid", "dashed"))
```

