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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>",
  error    = TRUE   # allow expect_error demonstrations to render
)
```

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

Version 0.3.0 contains several breaking changes that require updates to existing
code. This vignette walks through each one with before/after examples so you can
migrate quickly.

---

## 1. Argument names no longer carry a `.` prefix

Every argument name across all public functions has dropped its leading `.` — the
only exception is `.data`, which stays because it is a special pronoun in the
tidyverse and collides with `base::data()`.

Passing an old dotted name now triggers an informative error:

```{r dotted-error}
# Old (0.2.x) — now errors
define_mpi_specs(
  "path/to/specs.csv",
  .uid            = "uuid",
  .poverty_cutoff = 1/3
)
```

**Rename map** — find-and-replace the left column with the right column in your
scripts:

| Old (0.2.x)                 | New (0.3.0)                  | Function(s)                         |
|-----------------------------|------------------------------|-------------------------------------|
| `.mpi_specs_file`           | `mpi_specs_file`             | `define_mpi_specs()`                |
| `.uid`                      | `uid`                        | `define_mpi_specs()`                |
| `.poverty_cutoffs`          | `poverty_cutoffs`            | `define_mpi_specs()`                |
| `.unit_of_analysis`         | `unit_of_analysis`           | `define_mpi_specs()`                |
| `.source_of_data`           | `source_of_data`             | `define_mpi_specs()`                |
| `.names_separator`          | `names_separator`            | `define_mpi_specs()`                |
| `.save_as_global_options`   | `save_as_global_options`     | `define_mpi_specs()` *(deprecated)* |
| `.indicator`                | `indicator`                  | `define_deprivation()`              |
| `.cutoff`                   | `cutoff`                     | `define_deprivation()`              |
| `.mpi_specs`                | `mpi_specs`                  | `define_deprivation()`, `compute_mpi()`, `save_mpi()` |
| `.collapse_fn`              | `collapse_fn`                | `define_deprivation()`, `deprived()` |
| `.collapse_condition`       | `collapse_fn`                | `define_deprivation()`   |
| `.set_na_equal_to`          | `set_na_equal_to`            | `define_deprivation()`, `deprived()` |
| `.deprivation_profile`      | `deprivations`               | `compute_mpi()`                     |
| `.by`                       | `by`                         | `compute_mpi()`                     |
| `.generate_output`          | `generate_output`            | `compute_mpi()`                     |
| `.mpi_output_filename`      | `mpi_output_filename`        | `compute_mpi()`                     |
| `.include_specs`            | `include_specs`              | `save_mpi()`       |
| `.weight`                   | `weight`                     | `compute_mpi()`                     |
| `.strata`                   | `strata`                     | `compute_mpi()`                     |
| `.cluster`                  | `cluster`                    | `compute_mpi()`                     |
| `.fpc`                      | `fpc`                        | `compute_mpi()`                     |
| `.survey_design`            | `survey_design`              | `compute_mpi()`                     |
| `.inference`                | `inference`                  | `compute_mpi()`                     |
| `.ci_level`                 | `ci_level`                   | `compute_mpi()`                     |
| `.filename`                 | `filename`                   | `save_mpi()`                        |

**Before:**

```r
specs <- define_mpi_specs(
  "specs.csv",
  .uid            = "uuid",
  .poverty_cutoffs = c(1/3, 1/2),
  .unit_of_analysis = "household"
)

result <- compute_mpi(
  df_household,
  .mpi_specs   = specs,
  .deprivations = deps,
  .by           = region
)
```

**After:**

```r
specs <- define_mpi_specs(
  "specs.csv",
  uid             = "uuid",
  poverty_cutoffs = c(1/3, 1/2),
  unit_of_analysis = "household"
)

result <- compute_mpi(
  df_household,
  mpi_specs    = specs,
  deprivations = deps,
  by           = region
)
```

---

## 2. `mpi_specs` is now required — no more global option

In 0.2.x, calling `use_global_mpi_specs()` stored the spec in
`options("mpi_specs")` and functions picked it up automatically when
`mpi_specs` was omitted. That implicit lookup is gone.

**Before:**

```r
use_global_mpi_specs()                        # stored in options()

dm <- define_deprivation(df, drinking_water, .cutoff = drinking_water == 2)
                                              # ↑ silently read from options()
```

**After — pass `mpi_specs` explicitly every time:**

```r
specs <- global_mpi_specs()                   # load once …

dm <- define_deprivation(
  df, drinking_water,
  cutoff    = drinking_water == 2,
  mpi_specs = specs                           # … then pass it
)
```

Omitting `mpi_specs` now raises an error that tells you exactly what to do:

```{r no-specs-error}
define_deprivation(df_household, drinking_water, cutoff = drinking_water == 2)
```

---

## 3. `use_global_mpi_specs()` is deprecated — use `global_mpi_specs()`

```{r deprecated-fn}
# Soft-deprecated: raises a warning but still works
specs <- use_global_mpi_specs()
```

Replace every call with `global_mpi_specs()` (or `define_mpi_specs()` for a
custom spec file):

```r
# Before
use_global_mpi_specs()

# After
specs <- global_mpi_specs()
```

---

## 4. `.save_as_global_options` is deprecated and no-ops

Previously you could persist the spec to `options()` via:

```r
define_mpi_specs("specs.csv", .save_as_global_options = TRUE)
```

The argument still exists so your code doesn't break immediately, but it now
emits a deprecation warning and has **no effect**. Remove it from your calls and
store the return value instead:

```r
# Before
define_mpi_specs("specs.csv", .save_as_global_options = TRUE)
# later code called getOption("mpi_specs")

# After
specs <- define_mpi_specs("specs.csv")
# pass specs explicitly to each function
```

---

## 5. `compute_mpi()` has a new signature — `deprivations` replaces `.deprivation_profile`

In 0.2.x, `compute_mpi()` accepted a `.deprivation_profile` list of
pre-computed deprivation matrices. The argument is now called `deprivations`
and accepts either inline `deprived()` cutoffs or pre-built `define_deprivation()`
data frames.

**Before:**

```r
dm1 <- define_deprivation(df, drinking_water, .cutoff = drinking_water == 2, ...)
dm2 <- define_deprivation(df, electricity,    .cutoff = electricity == 2,    ...)

result <- compute_mpi(
  df,
  .mpi_specs          = specs,
  .deprivation_profile = list(drinking_water = dm1, electricity = dm2)
)
```

**After — inline `deprived()` cutoffs (recommended):**

```r
specs  <- global_mpi_specs()

result <- compute_mpi(
  df_household,
  mpi_specs    = specs,
  deprivations = list(
    drinking_water = deprived(drinking_water == 2),
    electricity    = deprived(electricity == 2)
  )
)
```

**After — pre-built profile (useful when you need to inspect intermediates):**

```r
specs <- global_mpi_specs()

dm1 <- define_deprivation(df_household, drinking_water,
                           cutoff = drinking_water == 2, mpi_specs = specs)
dm2 <- define_deprivation(df_household, electricity,
                           cutoff = electricity == 2,    mpi_specs = specs)

result <- compute_mpi(
  df_household,
  mpi_specs    = specs,
  deprivations = list(drinking_water = dm1, electricity = dm2)
)
```

---

## 6. `.collapse` replaced by `collapse_fn`

The boolean `.collapse = TRUE` argument in `define_deprivation()` and `deprived()`
has been replaced by `collapse_fn`, which accepts the actual aggregation function.

**Before:**

```r
deprived(attending_school == 2, .collapse = TRUE)      # used any() internally
```

**After:**

```r
deprived(attending_school == 2, collapse_fn = max)     # explicit function
```

Common replacements:

| Old                  | New                      |
|----------------------|--------------------------|
| `.collapse = TRUE`   | `collapse_fn = max`      |
| *(implicit any)*     | `collapse_fn = any`      |

---

## 7. `save_mpi()` — removed arguments

Two arguments were removed from `save_mpi()`:

| Removed argument       | Reason                                          |
|------------------------|-------------------------------------------------|
| `.formatted_output`    | Formatting delegated to the `tsg` package       |
| `.include_table_summary` | Superseded by `tsg` output templates          |

The new `include_deprivation_matrix` argument (default `TRUE`) controls whether
the deprivation-matrix sheets are written to the Excel file.

**Before:**

```r
save_mpi(result, .formatted_output = TRUE, .include_table_summary = FALSE)
```

**After:**

```r
save_mpi(result, mpi_specs = specs, include_deprivation_matrix = TRUE)
```

---

## 8. Default `names_separator` changed

The default separator used when constructing `variable_name` columns inside an
`mpi_specs_df` changed from `">"` to `"__"`. This only affects you if you relied
on the auto-generated `variable_name` values matching a specific pattern.

**Before:** `d01_i01>drinking_water`
**After:**  `d01_i01__drinking_water`

Pass `names_separator = ">"` explicitly to restore the old behaviour:

```r
specs <- define_mpi_specs("specs.csv", names_separator = ">")
```

---

## 5. `aggregation` removed from `define_mpi_specs()` — use `by` in `compute_mpi()`

The `aggregation` argument in `define_mpi_specs()` (and its old dotted form
`.aggregation`) has been removed. Subgroup grouping is now specified at compute
time via the `by` argument in `compute_mpi()`.

Passing `aggregation =` now raises an informative error:

```{r aggregation-error}
define_mpi_specs(
  system.file("extdata", "global-mpi-specs.csv", package = "mpindex"),
  aggregation = "region"
)
```

**Before:**

```r
specs <- define_mpi_specs("specs.csv", uid = "uuid", aggregation = "region")
result <- compute_mpi(df, mpi_specs = specs, deprivations = ...)
# grouped by region automatically
```

**After:**

```r
specs  <- define_mpi_specs("specs.csv", uid = "uuid")
result <- compute_mpi(df, mpi_specs = specs, deprivations = ..., by = region)
```

---

## 9. Minimum R version bumped to 4.1.0

`mpindex` 0.3.0 requires R ≥ 4.1.0 (released May 2021). The native pipe `|>`
and `\(x)` lambda syntax are used throughout the package internals. Update R if
you are on an older version.

---

## Quick migration checklist

```
[ ] Strip `.` prefix from every argument name (except `.data`)
[ ] Replace use_global_mpi_specs() with specs <- global_mpi_specs()
[ ] Remove .save_as_global_options = TRUE; store the return value instead
[ ] Pass mpi_specs = specs explicitly in define_deprivation(),
    compute_mpi(), and save_mpi()
[ ] Replace .collapse = TRUE with collapse_fn = max (or collapse_fn = any)
[ ] Replace .deprivation_profile = list(...) with deprivations = list(...) in
    compute_mpi() — inline deprived() cutoffs or pre-built define_deprivation()
    outputs both work
[ ] Remove aggregation = from define_mpi_specs(); pass by = in compute_mpi() instead
[ ] Remove .formatted_output / .include_table_summary from save_mpi() calls
[ ] Verify your R version is ≥ 4.1.0
```