Migrating to mpindex 0.3.x

In mpindex: Multidimensional Poverty Index (MPI) via the Alkire-Foster Method

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  error = TRUE   # allow expect_error demonstrations to render
)

library(mpindex)

Version 0.3.* 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:

# 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.) | 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:

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:

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:

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:

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:

define_deprivation(df_household, drinking_water, cutoff = drinking_water == 2)

---

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

# 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):

# 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:

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:

# 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:

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):

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):

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:

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

After:

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:

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

After:

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:

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:

define_mpi_specs(
  system.file("extdata", "global-mpi-specs.csv", package = "mpindex"),
  aggregation = "region"
)

Before:

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

After:

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

---

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

mpindex documentation built on Oct. 4, 2026, 5:07 p.m.