Migrating to mpindex 0.3.0

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:

# Old (0.2.x) — now errors
define_mpi_specs(
  "path/to/specs.csv",
  .uid            = "uuid",
  .poverty_cutoff = 1/3
)
#> Error in `define_mpi_specs()`:
#> ! Argument(s) renamed in 0.3.0 in `define_mpi_specs()`: `.uid` -> `uid`. Please update your call.

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:

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)
#> Error in `define_deprivation()`:
#> ! No MPI Specs supplied. Pass the result of `define_mpi_specs()` as `mpi_specs`, or use `global_mpi_specs()` to load the built-in Global MPI spec.

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

# Soft-deprecated: raises a warning but still works
specs <- use_global_mpi_specs()
#> Warning: `use_global_mpi_specs()` was deprecated in mpindex 0.3.0.
#> ℹ Please use `global_mpi_specs()` instead.
#> This warning is displayed once per session.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.

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"
)
#> Error:
#> ! The `aggregation` argument has been removed from `define_mpi_specs()`. Pass grouping columns via `by` in `compute_mpi()` instead.

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)

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