---
title: "Measuring Economic Resilience and Recovery with ERRI"
author: "Anbukkani Perumal, Mrinmoy Ray, and Chiranjit Mazumder"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Measuring Economic Resilience and Recovery with ERRI}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Purpose

Economic resilience is not a single observed variable. `ERRI` represents it as
six complementary dimensions calculated relative to an estimated no-shock
counterfactual. Let the observed outcome for unit $i$ at time $t$ be $Y_{it}$
and its counterfactual be $Y^{(0)}_{it}$. The scaled adverse gap is

$$
G_{it}=\frac{Y^{(0)}_{it}-Y_{it}}{s_i},
$$

where $s_i$ is the pre-shock standard deviation, absolute mean, or one.

The package measures maximum adverse gap (depth), summed adverse gap (cumulative
loss), time required to remain within a tolerance, strength of recovery,
post-shock residual volatility relative to pre-shock volatility, and positive
performance beyond the counterfactual after recovery.

## Example

```{r}
library(ERRI)
dat <- erri_example_data()
head(dat)
```

The example contains three fictional regional income series. The shock begins
in 2020.

```{r}
fit <- erri(dat, time = "year", outcome = "income", unit = "region",
            shock_time = 2020, method = "trend", scale = "sd",
            epsilon = 0.25, consecutive = 2)
fit
```

```{r, fig.cap="Observed and counterfactual paths with a prediction interval."}
plot(fit, type = "trajectory", unit = "North")
```

```{r, fig.cap="Comparison of composite ERRI estimates."}
plot(fit, type = "index")
```

## Uncertainty

Residual bootstrap intervals propagate uncertainty in the pre-shock
counterfactual. At least several hundred replications are recommended for an
empirical study.

```{r}
boot <- erri_bootstrap(fit, R = 99, seed = 2026)
subset(boot$intervals, measure == "ERRI")
rank_probability(boot)
```

## Weight sensitivity

The default weights are equal. The following analysis draws random weights
from the simplex and recalculates scores and rankings.

```{r}
sens <- erri_sensitivity(fit, R = 250, seed = 2026)
aggregate(ERRI ~ unit, sens, function(x) c(mean = mean(x), sd = sd(x)))
```

## Interpretation and limitations

A higher score denotes stronger measured resilience under the selected model,
scale, tolerance, and weights. The score is not automatically causal. A shock
date must be substantively justified, and a trend, mean, or AR(1)
counterfactual may be inadequate when other events affect the outcome. Report
component estimates, bootstrap intervals, and weight sensitivity rather than
only the composite index.