Package {ihsMW}

Title:	Clean and Harmonise 'Malawi Integrated Household Survey' Data
Version:	1.0.0
Description:	An offline suite of tools to clean, aggregate, and harmonise data from the 'Malawi Integrated Household Survey' ('IHS'). Provides crop-specific unit conversions, stratified winsorization, and automatic cross-round harmonisation for complex survey designs.
License:	MIT + file LICENSE
Depends:	R (≥ 4.1.0)
URL:	https://github.com/vituk123/ihsMW, https://vituk123.github.io/ihsMW/
BugReports:	https://github.com/vituk123/ihsMW/issues
Imports:	dplyr (≥ 1.1.0), readr (≥ 2.1.0), rlang (≥ 1.1.0), cli (≥ 3.6.0)
Suggests:	srvyr (≥ 1.2.0), survey (≥ 4.2.0), testthat (≥ 3.0.0), usethis (≥ 2.2.0), pkgdown (≥ 2.0.0), knitr (≥ 1.40), rmarkdown (≥ 2.20), withr (≥ 2.5.0), jsonlite (≥ 1.8.0)
Encoding:	UTF-8
RoxygenNote:	7.3.3
VignetteBuilder:	knitr
Config/testthat/edition:	3
Language:	en-US
NeedsCompilation:	no
Packaged:	2026-07-08 01:10:50 UTC; vitumbikokayuni
Author:	Vitumbiko Kayuni [aut, cre]
Maintainer:	Vitumbiko Kayuni <vitumbikokayuni@gmail.com>
Repository:	CRAN
Date/Publication:	2026-07-08 05:50:02 UTC

Smart Aggregation to Household Level

Description

Automatically detects variable types and applies sensible aggregations (e.g., 'sum' for continuous quantities, 'max' or logical OR for dummies). Throws warnings for ambiguous columns rather than failing silently.

Usage

ihs_aggregate(data, group_col = "case_id")

Arguments

Value

A data.frame aggregated to the household level

Clean and Harmonise IHS Data

Description

This wrapper function applies standard cleaning procedures to Malawi IHS data. It handles missing value conversions, winsorization of continuous variables, and returns an audit log of all transformations applied.

Usage

ihs_clean(
  data,
  winsorize_vars = NULL,
  winsorize_by = NULL,
  probs = c(0.01, 0.99)
)

Arguments

Value

A data.frame with cleaning applied. The returned object has an 'ihs_audit' attribute containing a log of modifications.

Convert Agricultural Units to Kilograms

Description

Converts reported harvest units (e.g., Pails, Oxcarts, Heaps) into standard kilograms using official NSO crop-specific conversion factors.

Usage

ihs_convert_units(data, qty_col, unit_col, crop_col, unmapped = "warn")

Arguments

Value

A data.frame with a new qty_col_kg column.

Check the comparability of variables across IHS rounds

Description

Evaluates the completeness and comparability of variables across the available IHS rounds (IHS2, IHS3, IHS4, IHS5) using the bundled crosswalk.

Usage

ihs_crosswalk_check(verbose = TRUE)

Arguments

Value

A tibble containing the full crosswalk. If verbose is TRUE, also prints a summary.

Examples

## Not run: 
  # Check the crosswalk and print a report
  cw <- ihs_crosswalk_check()

## End(Not run)

Deflate Nominal Values to Real Values Using CPI

Description

Converts nominal monetary values to real (constant-price) values using Malawi CPI data. By default uses 2019 (IHS5 baseline) as the reference period.

Usage

ihs_deflate(data, value_cols, round = NULL, base_year = 2019)

Arguments

Value

A data.frame with new *_real suffixed columns containing deflated values.

Examples

## Not run: 
  # Deflate IHS4 consumption to 2019 prices
  real_data <- ihs_deflate(df, value_cols = "rexp_cat01", round = "IHS4")

## End(Not run)

Harmonise Raw IHS Data

Description

Takes a raw data.frame loaded from a Malawi IHS survey round (e.g. from a '.dta' file) and renames its columns to the standard harmonised variable names defined in the crosswalk.

Usage

ihs_harmonise(data, round = "IHS5", extra = FALSE)

Arguments

Value

A data.frame with columns renamed to standard 'harmonised_name's where applicable.

Merge Multiple Harmonised IHS Data Frames

Description

Merges two or more harmonised data.frames, auto-detecting common ID columns when by is not specified. Warns on unexpected row expansion from many-to-many joins.

Usage

ihs_merge(..., by = NULL, type = "left")

Arguments

Value

A merged data.frame with an ihs_merge_log attribute containing row counts at each merge step.

Examples

## Not run: 
  hh <- haven::read_dta("hh_mod_a.dta") |> ihs_harmonise("IHS5")
  ag <- haven::read_dta("ag_mod_a.dta") |> ihs_harmonise("IHS5")
  merged <- ihs_merge(hh, ag)

## End(Not run)

Get Standard Panel ID Columns for an IHS Round

Description

Returns the standard household, individual, and enumeration area ID column names used in a given IHS round. This is a convenience helper for users building longitudinal panels or merging modules.

Usage

ihs_panel_ids(round = "IHS5")

Arguments

Value

If a single round is specified, a named character vector of standard ID columns. If "all", a data.frame comparing ID columns across rounds.

Examples

# Get IHS5 ID columns
ihs_panel_ids("IHS5")

# Compare across all rounds
ihs_panel_ids("all")

Generate Summary Statistics Table

Description

Produces a publication-ready summary statistics table for numeric variables in IHS data. Supports grouping by a factor variable and optional survey weights.

Usage

ihs_report(data, vars = NULL, by = NULL, weights = NULL)

Arguments

Value

A data.frame of summary statistics with columns: variable, n, mean, sd, median, min, max, pct_missing. If by is specified, an additional grouping column is included.

Examples

## Not run: 
  # Basic summary
  ihs_report(harmonised_data, vars = c("rexp_cat01", "hhsize"))

  # Grouped by region
  ihs_report(harmonised_data, vars = "rexp_cat01", by = "region")

  # Weighted summary
  ihs_report(harmonised_data, vars = "rexp_cat01", weights = "hh_wgt")

## End(Not run)

Search across all IHS rounds for variables manually mapped

Description

Searches the manual harmonisation crosswalk bundled within ihsMW for specific variables.

Usage

ihs_search(keyword, round = NULL, fields = c("name", "label", "module"))

Arguments

Value

A tibble with cross-round harmonised search results.

Examples

ihs_search("consumption")
ihs_search("expenditure", round = "IHS5")
ihs_search("age", fields = c("name", "label"))

Standardize Survey Missing Codes

Description

Converts common negative missing codes (like -99 for "Refused" or -98 for "Don't Know") into standard R 'NA' values to prevent them from skewing numeric calculations.

Usage

ihs_standardize_missing(data)

Arguments

Value

A data.frame with missing values standardized

Create a Survey Design Object for IHS Data

Description

Wraps survey::svydesign() with automatic detection of standard IHS weight, strata, and PSU columns from harmonised data.

Usage

ihs_svydesign(data, weight_col = NULL, strata_col = NULL, psu_col = NULL)

Arguments

Value

A survey.design2 object from the survey package.

Examples

## Not run: 
  library(survey)
  dsgn <- ihs_svydesign(harmonised_data)
  survey::svymean(~rexp_cat01, dsgn, na.rm = TRUE)

## End(Not run)

Winsorize Continuous Variables

Description

Caps extreme outliers at specified percentiles. Crucially, this function allows for stratified winsorization (e.g., by region) to avoid over-trimming poor/rich areas, and it creates new '_w' suffixed columns to preserve raw data provenance.

Usage

ihs_winsorize(data, vars, by = NULL, probs = c(0.01, 0.99))

Arguments

Value

A data.frame with new '*_w' columns added.