Package {mpindex}

Type:	Package
Title:	Multidimensional Poverty Index (MPI) via the Alkire-Foster Method
Version:	0.3.0
Author:	Bhas Abdulsamad [aut, cre, cph]
Maintainer:	Bhas Abdulsamad <aeabdulsamad@gmail.com>
Description:	Estimate Multidimensional Poverty Index (MPI) measures from household survey microdata using the Alkire-Foster dual-cutoff counting method (Alkire and Foster, 2011). Load indicator specifications from CSV, Excel, JSON, or plain-text files; compute the headcount ratio (H), intensity (A), and MPI = H x A across any subgroup; and export results to formatted Excel reports. Supports complex survey designs — stratification, clustering, and probability weights — and optionally appends design-based standard errors and confidence intervals.
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
Imports:	dplyr, stringr, jsonlite, tibble, openxlsx, tsg, rlang, lifecycle
Suggests:	tidyr, survey, testthat (≥ 3.0.0), knitr, rmarkdown, gt
Config/testthat/edition:	3
RoxygenNote:	7.3.3
BugReports:	https://github.com/yng-me/mpindex/issues
URL:	https://github.com/yng-me/mpindex, https://yng-me.github.io/mpindex/
VignetteBuilder:	knitr
Depends:	R (≥ 4.1.0)
NeedsCompilation:	no
Packaged:	2026-06-14 22:49:20 UTC; bhasabdulsamad
Repository:	CRAN
Date/Publication:	2026-06-15 07:50:15 UTC

Compute Multidimensional Poverty Index (MPI)

Description

The primary single-call API for computing the MPI using the Alkire-Foster (AF) counting method. Deprivation cutoffs are specified inline using the deprived helper, making the workflow self-contained and readable.

Usage

compute_mpi(
  .data,
  mpi_specs,
  deprivations,
  ...,
  by = NULL,
  include_deprivation_matrix = FALSE,
  weight = NULL,
  strata = NULL,
  cluster = NULL,
  fpc = NULL,
  survey_design = NULL,
  inference = FALSE,
  ci_level = 0.95
)

Arguments

Value

A named list of class mpi_output with components:

$index

Named list keyed by k_*: MPI, H, A, n.

$contribution

Named list keyed by k_*: contribution by indicator/dimension.

$headcount_ratio

Named list with uncensored and per-k_* censored ratios.

$deprivation_matrix

Named list with uncensored and per-k_* matrices.

See Also

define_mpi_specs, deprived, save_mpi

Examples

specs <- define_mpi_specs(
  system.file("extdata", "global-mpi-specs.csv", package = "mpindex"),
  uid = "uuid"
)

## Not run: 
mpi_result <- compute_mpi(
  df_household,
  mpi_specs = specs,
  deprivations = list(
    nutrition = deprived(
      undernourished == 1 & age < 70,
      .data = df_household_roster,
      collapse_fn = max
    ),
    child_mortality = deprived(with_child_died == 1),
    year_schooling = deprived(
      completed_6yrs_schooling == 2,
      .data = df_household_roster,
      collapse_fn = max
    ),
    school_attendance = deprived(
      attending_school == 2 & age %in% c(5:24),
      .data = df_household_roster,
      collapse_fn = max
    ),
    cooking_fuel   = deprived(cooking_fuel %in% c(4:6, 9)),
    sanitation     = deprived(toilet > 1),
    drinking_water = deprived(drinking_water == 2),
    electricity    = deprived(electricity == 2),
    housing        = deprived(
      roof %in% c(5, 7, 9) | walls %in% c(5, 8, 9, 99) == 2 | floor %in% c(5, 6, 9)
    ),
    assets = deprived(!(
      (asset_tv + asset_telephone + asset_mobile_phone + asset_computer +
         asset_animal_cart + asset_bicycle + asset_motorcycle +
         asset_refrigerator) > 1 &
        (asset_car + asset_truck) > 0
    ))
  )
)

## End(Not run)

Compute MPI from a deprivation profile (internal)

Description

Internal implementation used by compute_mpi. Not exported. Use compute_mpi directly.

Usage

compute_mpi_from_profile(
  .data,
  deprivation_profile,
  ...,
  by = character(0),
  mpi_specs = NULL,
  include_deprivation_matrix = TRUE,
  weight = NULL,
  strata = NULL,
  cluster = NULL,
  fpc = NULL,
  survey_design = NULL,
  inference = FALSE,
  ci_level = 0.95
)

Arguments

Examples

specs <- define_mpi_specs(
  system.file("extdata", "global-mpi-specs.csv", package = "mpindex"),
  uid = "uuid"
)

deprivation_profile <- list()

deprivation_profile$drinking_water <- df_household |>
  define_deprivation(
    indicator = drinking_water,
    cutoff    = drinking_water == 2,
    mpi_specs = specs
  )

# ... (define remaining indicators) ...

## Not run: 
mpi_result <- compute_mpi_from_profile(
  df_household, deprivation_profile, mpi_specs = specs
)

## End(Not run)

Define deprivation cutoffs

Description

Sets a deprivation cutoff for a single indicator. For each unit of analysis, the result is 0 (not deprived), 1 (deprived), or NA (missing). An additional weighted column (indicator value × weight) is also computed.

Usage

define_deprivation(
  .data,
  indicator,
  cutoff,
  mpi_specs = NULL,
  collapse_fn = NULL,
  set_na_equal_to = 0,
  ...
)

Arguments

Value

A data frame with columns *_unweighted and *_weighted.

See Also

define_mpi_specs

Examples

specs_file <- system.file(
 "extdata",
 "global-mpi-specs.csv",
 package = "mpindex"
)

specs <- define_mpi_specs(specs_file, uid = "uuid")

df_household |>
  define_deprivation(
    indicator  = drinking_water,
    cutoff     = drinking_water == 2,
    mpi_specs  = specs
  )

df_household_roster |>
  define_deprivation(
    indicator   = school_attendance,
    cutoff      = attending_school == 2,
    mpi_specs   = specs,
    collapse_fn = max
  )

Define MPI specifications: dimensions, indicators, and weights

Description

Use to define MPI dimensions, indicators and its corresponding weights using any of the supported file types: .xlsx (Excel), .json, .csv, or .txt (TSV). You can also set the poverty cutoff or list of poverty cutoffs.

Usage

define_mpi_specs(
  mpi_specs_file = NULL,
  indicators = NULL,
  poverty_cutoffs = NULL,
  unit_of_analysis = NULL,
  uid = NULL,
  source_of_data = NULL,
  names_separator = getOption("mpindex.options")$names_separator %||% "__",
  save_as_global_options = FALSE,
  ...
)

Arguments

Value

An mpi_specs object. Pass this directly as the mpi_specs argument in compute_mpi, define_deprivation, and save_mpi.

See Also

compute_mpi

Examples

specs_file <- system.file(
  "extdata",
  "global-mpi-specs.csv",
  package = "mpindex"
)
system.file("extdata", package = "mpindex") |> list.files()

Specify a deprivation cutoff for use in compute_mpi

Description

A helper that captures a bare deprivation cutoff expression and optional per-indicator settings for use inside the deprivations argument of compute_mpi.

Usage

deprived(.cutoff, .data = NULL, collapse_fn = NULL, set_na_equal_to = 0, ...)

Arguments

Value

An object of class mpi_d.

See Also

compute_mpi

Examples

deprived(drinking_water == 2)
deprived(undernourished == 1 & age < 70, .data = df_household_roster, collapse_fn = max)

Sample dataset of households

Description

This is a synthetic dataset containing household information primarily used for demonstration purposes on how to use the mpindex package.

Usage

df_household

Format

A tibble with 198 rows and 21 variables:

uuid

Unique ID

class

Urbanity: Rural or Urban

drinking_water

Acess to drinking water: 1 - improved; 2 - unimproved

toilet

Service level of toilet or sanitation facility: 1 - basic; 2 - limited; 3 - unimproved; 4 - open defecation

with_child_died

With at least one (1) child died in the last five (5) years: 1 - with child died; 2 - without child died

roof

Main construction material of the roof: 1 - galvanized iron/aluminum; 2 - concrete/clay tile; 3 - half galvanized iron and half concrete; 4 - wood/bamboo; 5 - cogon/nipa/anahaw; 6 - asbestos; 7 - makeshift/salvaged/improvised materials; 9 - other construction material

walls

Main construction material of the outer walls: 1 - concrete/brick/stone; 2 - wood; 3 - half concrete/brick/stone and half wood; 4 - Galvanized iron/aluminum; 5 - bamboo/sawali/cogon/nipa; 6 - asbestos; 7 - glass; 8 - makeshift/salvaged/improvised materials; 9 - none; 10 - concrete hollow blocks; 11 - concrete hollow blocks/wood; 12 - shear walls; 99 - other construction material

floor

Main construction material of the floor: 1 - concrete; 2 - wood; 3 - coconut lumber; 4 - bamboo; 5 - earth/sand/mud; 6 - makeshift/salvaged/improvised materials; 9 - other construction material

electricity

Access to electricity: 1 - with access to electricity; 2 - without access to electricity

cooking_fuel

Fuel use for cooking: 1 - electricity; 2 - kerosene (gaas); 3 - liquified petroleum gas (LPG); 4 - charcoal; 5 - wood; 6 - none; 9 - other cooking fuel such as dung, agricultural crop, or shrubs

asset_radio

Number of working radio owned by the household

asset_tv

Number of working television owned by the household

asset_telephone

Number of working telephone owned by the household

asset_mobile_phone

Number of working mobile phone owned by the household

asset_computer

Number of working computer owned by the household

asset_animal_cart

Number of animal carts owned by the household

asset_bicycle

Number of bicycle owned by the household

asset_motorcycle

Number of motorcylce owned by the household

asset_refrigerator

Number of working refrigerator owned by the household

asset_car

Number of car owned by the household

asset_truck

Number of trucks owned by the household

See Also

df_household_roster

Examples

df_household

Sample dataset of household members

Description

This dataset contains a many-to-one relationship with the df_household dataset. Hence, you can apply joins using the uuid.

Usage

df_household_roster

Format

A tibble with 905 rows and 8 variables:

uuid

Unique ID

line_number

Number identifier for each member within the household

class

Urbanity: Rural or Urban

sex

Sex of the household member

age

Age of the household member

attending_school

Whether the household member (aged 5-24 years old) is currently attending school: 1 - currently attending; 2 - currently not attending

completed_6yrs_schooling

Whether completed at least six (6) years of schooling: 1 - completed; 2 -not completed

undernourished

Whether the household member (aged below 70 years old) is undernourished: 1 - undernourished; 2 - not undernourished

See Also

df_household

Examples

df_household_roster

Load the built-in Global MPI specification

Description

Returns the mpi_specs object for the standard Global MPI (10 indicators across Health, Education, and Living Standards). Assign the result and pass it explicitly as mpi_specs.

Usage

global_mpi_specs(..., poverty_cutoffs = 1/3)

Arguments

Value

An mpi_specs object.

Examples

mpi_specs <- global_mpi_specs(uid = "uuid")

Save MPI output

Description

Save the MPI output to an Excel file using the tsg package for publication-ready table formatting.

Usage

save_mpi(
  mpi_output,
  mpi_specs,
  ...,
  filename = NULL,
  include_specs = FALSE,
  overall_label = "Overall",
  facade = tsg::get_tsg_facade()
)

Arguments

Value

Returns the normalized file path of the generated Excel file.

Examples

## Not run: 
mpi_result <- compute_mpi(df_household, mpi_specs = specs, deprivations = deps)
save_mpi(mpi_result, mpi_specs = specs, filename = "MPI Sample Output")

## End(Not run)

Use Global MPI specification

Description

Please use global_mpi_specs instead.

Usage

use_global_mpi_specs(...)

Arguments

Value

An mpi_specs object.

Examples

## Not run: 
# Deprecated — use global_mpi_specs() instead
mpi_specs <- use_global_mpi_specs(uid = "uuid")

## End(Not run)