The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.