MAIHDA: Multilevel Analysis of Individual Heterogeneity and Discriminatory Accuracy

Description

Provides a comprehensive toolkit for conducting Multilevel Analysis of Individual Heterogeneity and Discriminatory Accuracy (MAIHDA). Methods are described in Merlo (2018) doi:10.1016/j.socscimed.2017.12.018 and Evans et al. (2018) doi:10.1016/j.socscimed.2017.11.011. Automatically generates intersectional strata, fits analytical models, extracts statistics, and produces visualizations.

Author(s)

Maintainer: Hamid Bulut hamid.bulut@ymail.com

See Also

Useful links:

• https://github.com/hdbt/MAIHDA

• https://hdbt.github.io/MAIHDA/

• Report bugs at https://github.com/hdbt/MAIHDA/issues

Add Stratum Labels to Estimates

Description

Internal helper function to merge stratum labels into stratum estimates.

Usage

add_stratum_labels(stratum_estimates, strata_info)

Arguments

Value

Data frame with labels merged in

Bootstrap PVC

Description

Internal function to compute bootstrap confidence intervals for PVC.

Usage

bootstrap_pvc(model1, model2, n_boot, conf_level)

Arguments

Value

A vector with lower and upper confidence bounds

Bootstrap VPC/ICC

Description

Internal function to compute bootstrap confidence intervals for VPC.

Usage

bootstrap_vpc(model, data, formula, n_boot, conf_level)

Arguments

Value

A vector with lower and upper confidence bounds

Calculate Proportional Change in Between-Stratum Variance (PVC)

Description

Calculates the proportional change in between-stratum variance (PVC) between two MAIHDA models. The PVC measures how much the between-stratum variance changes when moving from one model to another, and is calculated as: PVC = (Var_model1 - Var_model2) / Var_model1

Usage

calculate_pvc(
  model1,
  model2,
  bootstrap = FALSE,
  n_boot = 1000,
  conf_level = 0.95
)

Arguments

Details

The PVC is interpreted as the proportional reduction (or increase if negative) in between-stratum variance when moving from model1 to model2. A positive PVC indicates that model2 explains some of the between-stratum variance present in model1, while a negative PVC suggests that model2 has more unexplained between-stratum variance.

When bootstrap = TRUE, the function resamples the data with replacement and refits both models for each bootstrap sample to obtain confidence intervals for the PVC estimate.

Value

A list containing:

Examples

# Create strata and fit two models
strata_result <- make_strata(maihda_sim_data, c("gender", "race"))
model1 <- fit_maihda(health_outcome ~ age + (1 | stratum), data = strata_result$data)
model2 <- fit_maihda(health_outcome ~ age + gender + (1 | stratum), data = strata_result$data)

# Calculate PVC without bootstrap
pvc_result <- calculate_pvc(model1, model2)
print(pvc_result$pvc)

# Calculate PVC with bootstrap CI
# pvc_boot <- calculate_pvc(model1, model2, bootstrap = TRUE, n_boot = 500)
# print(pvc_boot)

Compare MAIHDA Models

Description

Compares variance partition coefficients (VPC/ICC) across multiple MAIHDA models, with optional bootstrap confidence intervals.

Usage

compare_maihda(
  ...,
  model_names = NULL,
  bootstrap = FALSE,
  n_boot = 1000,
  conf_level = 0.95
)

Arguments

Value

A data frame comparing VPC/ICC across models with optional confidence intervals.

Examples

# Create strata and models using simulated data
strata_1 <- make_strata(maihda_sim_data, vars = c("gender", "race"))
strata_2 <- make_strata(maihda_sim_data, vars = c("gender", "race", "education"))

model1 <- fit_maihda(health_outcome ~ age + (1 | stratum), data = strata_1$data)
model2 <- fit_maihda(health_outcome ~ age + gender + (1 | stratum), data = strata_2$data)

# Compare without bootstrap
comparison <- compare_maihda(model1, model2,
                            model_names = c("Base", "With Gender"))

# Compare with bootstrap CI
comparison_boot <- compare_maihda(model1, model2,
                                 model_names = c("Base", "With Gender"),
                                 bootstrap = TRUE, n_boot = 500)

Extract Between-Stratum Variance

Description

Internal function to extract between-stratum variance from a MAIHDA model.

Usage

extract_between_variance(model)

Arguments

Value

Numeric value of between-stratum variance

Fit MAIHDA Model

Description

Fits a multilevel model for MAIHDA (Multilevel Analysis of Individual Heterogeneity and Discriminatory Accuracy) using either lme4 or brms.

Usage

fit_maihda(formula, data, engine = "lme4", family = "gaussian", ...)

Arguments

Value

A maihda_model object containing:

Examples

# Create strata
strata_result <- make_strata(maihda_sim_data, vars = c("gender", "race", "education"))

# Fit model with lme4
model <- fit_maihda(health_outcome ~ age + (1 | stratum),
                    data = strata_result$data,
                    engine = "lme4")

# Fit model with brms (if brms is available)
# model_brms <- fit_maihda(health_outcome ~ age + (1 | stratum),
#                          data = strata_result$data,
#                          engine = "brms")

Simulated Health Data for MAIHDA Examples

Description

A simulated dataset containing health outcomes and demographic variables for 500 individuals. This dataset is designed to demonstrate intersectional health inequalities suitable for MAIHDA analysis. The data includes main effects and intersectional effects between gender, race, and education.

Usage

data("maihda_sim_data")

Format

A data frame with 500 observations on the following 6 variables:

id

Integer identifier for each individual

gender

Character variable indicating gender ("Male" or "Female")

race

Character variable indicating race/ethnicity ("White", "Black", "Hispanic", or "Asian")

education

Character variable indicating education level ("High School", "Some College", "College", or "Graduate")

age

Numeric variable for age in years (range: 18-80)

health_outcome

Numeric variable representing a health score (higher is better)

Details

The health outcome was simulated with:

• Main effects of gender, race, education, and age

• Intersectional effects (e.g., Black women, men with high school education)

• Random noise with standard deviation of 10

The data demonstrates typical patterns in health inequalities research where outcomes vary both by individual characteristics and their intersections.

Examples

data(maihda_sim_data)

# View structure
str(maihda_sim_data)

# Summary statistics
summary(maihda_sim_data)


# Example MAIHDA analysis
library(MAIHDA)

# Create strata
strata_result <- make_strata(maihda_sim_data, vars = c("gender", "race"))

# Fit model
model <- fit_maihda(health_outcome ~ age + (1 | stratum), 
                   data = strata_result$data)

# Summarize
summary_maihda(model)

# Visualize
plot_maihda(model, type = "caterpillar")

Create Strata from Multiple Variables

Description

This function creates strata (intersectional categories) from multiple categorical variables in a dataset.

Usage

make_strata(data, vars, sep = "_", min_n = 1)

Arguments

Details

If any of the specified variables has a missing value (NA) for a given observation, that observation will be assigned to the NA stratum (stratum = NA), rather than creating a stratum that includes the missing value.

The strata_info data frame is also attached as an attribute to the data, which allows fit_maihda() to automatically capture stratum labels for use in plots and summaries.

Value

A list with two elements:

Examples

# Create strata from gender and race variables
result <- make_strata(maihda_sim_data, vars = c("gender", "race"))
print(result$strata_info)

Caterpillar Plot

Description

Caterpillar Plot

Usage

plot_caterpillar(summary_obj, n_strata)

Arguments

Value

A ggplot2 object

Plot Model Comparison

Description

Creates a plot comparing VPC/ICC across multiple models.

Usage

plot_comparison(comparison_df)

Arguments

Value

A ggplot2 object.

Examples

# Create strata and models using simulated data
strata_1 <- make_strata(maihda_sim_data, vars = c("gender", "race"))
strata_2 <- make_strata(maihda_sim_data, vars = c("gender", "race", "education"))

model1 <- fit_maihda(health_outcome ~ age + (1 | stratum), data = strata_1$data)
model2 <- fit_maihda(health_outcome ~ age + gender + (1 | stratum), data = strata_2$data)

comparison <- compare_maihda(model1, model2, bootstrap = TRUE)
plot_comparison(comparison)

Plot MAIHDA Model Results

Description

Creates various plots for visualizing MAIHDA model results including caterpillar plots, variance partition coefficient comparisons, observed vs. shrunken estimates, and predicted subgroup values with confidence intervals.

Usage

plot_maihda(
  object,
  type = c("caterpillar", "vpc", "obs_vs_shrunken", "predicted"),
  summary_obj = NULL,
  n_strata = 50,
  ...
)

Arguments

Value

A ggplot2 object.

Examples

strata_result <- make_strata(maihda_sim_data, vars = c("gender", "race"))
model <- fit_maihda(health_outcome ~ age + (1 | stratum), data = strata_result$data)

# Caterpillar plot
plot_maihda(model, type = "caterpillar")

# VPC plot
plot_maihda(model, type = "vpc")

# Observed vs shrunken plot
plot_maihda(model, type = "obs_vs_shrunken")

# Predicted values with confidence intervals
plot_maihda(model, type = "predicted")

Observed vs. Shrunken Estimates Plot

Description

Observed vs. Shrunken Estimates Plot

Usage

plot_obs_vs_shrunken(object, summary_obj)

Arguments

Value

A ggplot2 object

Plot Predicted Stratum Values with Confidence Intervals

Description

Plot Predicted Stratum Values with Confidence Intervals

Usage

plot_predicted_strata(object, summary_obj, n_strata)

Arguments

Value

A ggplot2 object

VPC Visualization Plot

Description

VPC Visualization Plot

Usage

plot_vpc(summary_obj)

Arguments

Value

A ggplot2 object

Predict from MAIHDA Model

Description

Makes predictions from a fitted MAIHDA model, either at the stratum level or individual level.

Usage

predict_maihda(object, newdata = NULL, type = c("individual", "strata"), ...)

Arguments

Value

Depending on type:

• For "individual": A numeric vector of predicted values

• For "strata": A data frame with stratum ID and predicted random effect

Examples

strata_result <- make_strata(maihda_sim_data, vars = c("gender", "race"))
model <- fit_maihda(health_outcome ~ age + (1 | stratum), data = strata_result$data)

# Individual predictions
pred_ind <- predict_maihda(model, type = "individual")

# Stratum predictions
pred_strata <- predict_maihda(model, type = "strata")

Print method for maihda_model

Description

Print method for maihda_model

Usage

## S3 method for class 'maihda_model'
print(x, ...)

Arguments

Value

No return value, called for side effects.

Print method for maihda_strata objects

Description

Print method for maihda_strata objects

Usage

## S3 method for class 'maihda_strata'
print(x, ...)

Arguments

Value

No return value, called for side effects.

Print method for maihda_summary objects

Description

Print method for maihda_summary objects

Usage

## S3 method for class 'maihda_summary'
print(x, ...)

Arguments

Value

No return value, called for side effects.

Print method for PVC results

Description

Print method for PVC results

Usage

## S3 method for class 'pvc_result'
print(x, ...)

Arguments

Value

No return value, called for side effects.

Summarize MAIHDA Model

Description

Provides a summary of a MAIHDA model including variance partition coefficients (VPC/ICC) and stratum-specific estimates.

Usage

summary_maihda(
  object,
  bootstrap = FALSE,
  n_boot = 1000,
  conf_level = 0.95,
  ...
)

Arguments

Value

A maihda_summary object containing:

Examples

strata_result <- make_strata(maihda_sim_data, vars = c("gender", "race"))
model <- fit_maihda(health_outcome ~ age + (1 | stratum), data = strata_result$data)
summary_result <- summary_maihda(model)

# With bootstrap CI
# summary_boot <- summary_maihda(model, bootstrap = TRUE, n_boot = 50)