Package {icarm}

icarm: Interpretable Contextual-Accountable and Responsible Machine Learning

Description

A general-purpose framework for Interpretable Contextual-Accountable and Responsible Machine Learning (ICARM) that works with any clean tabular data across any application domain.

The contextual accountability framing captures a core principle: what counts as fair, interpretable, and responsible depends on the deployment context. A model predicting hospital readmission requires different accountability standards than one predicting loan default or civic participation. icarm operationalises this principle through domain-agnostic tools that adapt to any context.

## Quickstart library(icarm) m <- icarm_fit(outcome ~ ., data = your_data) ex <- icarm_explain(m, data = your_data) fair <- icarm_fairness(m, your_data, "outcome", "protected_col") icarm_scorecard(m, test_data, outcome = "outcome")

## ICARM definition Interpretable: model decisions can be explained to affected stakeholders.

Contextual-Accountable: accountability standards are evaluated relative to the deployment domain and the specific groups affected.

Responsible: models are audited for fairness, calibration, and reproducibility before deployment.

Machine Learning: statistical learning methods applied to structured tabular data.

Author(s)

Maintainer: Olushina Olawale Awe olawaleawe@gmail.com

Other contributors:

• Ludwigsburg University of Education [funder]

References

Awe OO (2025) civic.icarm: A Unified R Framework for Interpretable, Civic-Accountable and Responsible Machine Learning. https://cran.r-project.org/package=civic.icarm

Breiman L (2001) Random Forests. doi:10.1023/A:1010933404324

Chen T, Guestrin C (2016) XGBoost. doi:10.1145/2939672.2939785

Generate a JSON audit trail

Description

Generate a JSON audit trail

Usage

icarm_audit(
  object,
  metrics = NULL,
  fairness = NULL,
  notes = NULL,
  analyst = NULL,
  path = NULL
)

Arguments

Value

Invisibly, the JSON string.

Examples

m <- icarm_fit(Species ~ ., iris)
trail <- icarm_audit(m, analyst = "O. O. Awe")
cat(trail)

Probability calibration diagnostics

Description

Probability calibration diagnostics

Usage

icarm_calibrate(object, data, outcome, positive = NULL, n_bins = 10L)

Arguments

Value

An object of class 'icarm_calibration'.

Examples

m   <- icarm_fit(
  Petal.Width ~ Sepal.Length + Sepal.Width, iris,
  model = "linear")
# calibration only for binary:
data(icarm_medical)
m2  <- icarm_fit(readmitted ~ ., icarm_medical)
cal <- icarm_calibrate(m2, icarm_medical, "readmitted", "Yes")
print(cal)

Compare multiple icarm_models

Description

Compare multiple icarm_models

Usage

icarm_compare(
  models,
  test_data,
  outcome,
  protected = NULL,
  positive = NULL,
  threshold = 0.5
)

Arguments

Value

A tibble of class 'icarm_comparison'.

Examples

sp <- icarm_split(iris, stratify = "Species")
m1 <- icarm_fit(Species ~ ., sp$train, model = "cart")
m2 <- icarm_fit(Species ~ ., sp$train, model = "multinomial")
cmp <- icarm_compare(list(CART=m1, Multinom=m2),
                     sp$test, outcome="Species")
print(cmp)

Equalized odds curves across thresholds

Description

Equalized odds curves across thresholds

Usage

icarm_equalized_odds_curve(
  object,
  data,
  outcome,
  protected,
  positive = NULL,
  thresholds = seq(0.05, 0.95, 0.05)
)

Arguments

Value

A tibble with threshold, group, tpr, fpr, tnr.

Equity summary from a fairness report

Description

Equity summary from a fairness report

Usage

icarm_equity_summary(fairness)

Arguments

Value

A named list of scalar equity indicators.

Generate global model explanations

Description

Generate global model explanations

Usage

icarm_explain(object, data = NULL, label = NULL)

Arguments

Value

An object of class 'icarm_explainer'.

Examples

m  <- icarm_fit(Species ~ ., iris)
ex <- icarm_explain(m)
print(ex)
icarm_plot_importance(ex)

Local explanation for individual observations

Description

Local explanation for individual observations

Usage

icarm_explain_local(explainer, newdata, n_features = 10L)

Arguments

Value

A list of tibbles, one per row of newdata.

Examples

m  <- icarm_fit(Species ~ ., iris)
ex <- icarm_explain(m)
icarm_explain_local(ex, iris[1:2, ])

Group-level fairness audit

Description

Group-level fairness audit

Usage

icarm_fairness(
  object,
  data,
  outcome,
  protected,
  positive = NULL,
  threshold = 0.5
)

Arguments

Value

A tibble of class 'icarm_fairness'.

Examples

m <- icarm_fit(Species ~ ., iris)
iris$size <- factor(ifelse(iris$Sepal.Length > 5.8,
                           "large","small"))
icarm_fairness(m, iris, "Species", "size")

Synthetic Financial Loan Default Dataset

Description

A synthetic dataset of 1,000 loan applicants with financial and demographic variables. Suitable for binary classification (predicting loan default) and fairness auditing across gender and ethnicity — a classic algorithmic fairness benchmark.

Usage

icarm_financial

Format

A tibble with 1,000 rows and 12 variables:

age

Integer. Applicant age (20-75).

income

Numeric. Annual income (USD).

credit_score

Integer. Credit score (300-850).

loan_amount

Numeric. Requested loan amount (USD).

loan_term

Integer. Loan term in months.

employment_status

Factor. Employment category.

home_owner

Factor. Yes or No.

num_accounts

Integer. Number of credit accounts.

debt_ratio

Numeric. Debt-to-income ratio (0-1).

gender

Factor. male or female.

ethnicity

Factor. Ethnicity category.

default

Factor. Yes (defaulted) or No.

Source

Synthetic data generated by the icarm team.

Examples

data(icarm_financial)
m <- icarm_fit(default ~ credit_score + income +
               loan_amount + debt_ratio,
               icarm_financial, model = "logistic",
               positive = "Yes")

Fit an ICARM model on any tabular data

Description

Single unified entry point for all icarm modelling. Automatically detects the prediction task from your target variable and supports both interpretable and extended (black-box) model families.

**Task auto-detection:** | Target type | Task | |—|—| | numeric / integer | regression | | factor / character, 2 levels | binary classification | | factor / character, 3+ levels | multi-class classification |

**Interpretable models (ICARM-compliant):** - '"cart"' — Classification/Regression Tree (rpart) - '"logistic"' — Logistic regression (binary) - '"logistic_l1"' — L1-penalised logistic (glmnet) - '"linear"' — Linear regression - '"gam"' — Generalised Additive Model (mgcv) - '"multinomial"' — Multinomial logistic (nnet)

**Extended models (requires post-hoc explanation):** - '"random_forest"' — Random forest (randomForest) - '"xgboost"' — Gradient boosting (xgboost) - '"svm"' — Support vector machine (e1071)

Usage

icarm_fit(
  formula,
  data,
  task = "auto",
  model = "auto",
  seed = 2025L,
  positive = NULL,
  cart_control = NULL,
  ...
)

Arguments

Value

An S3 object of class 'icarm_model' with full provenance.

Examples

# Works on any data — task auto-detected
m1 <- icarm_fit(Species ~ ., iris)              # multiclass
m2 <- icarm_fit(Sepal.Length ~ ., iris)         # regression

# Extended models
m3 <- icarm_fit(Species ~ ., iris,
                model = "random_forest")

# Built-in datasets
data(icarm_medical)
m4 <- icarm_fit(readmitted ~ ., icarm_medical,
                model = "cart")

Synthetic Medical Readmission Dataset

Description

A synthetic dataset of 500 hospital patients with clinical and administrative variables, designed for binary classification (predicting 30-day readmission) and fairness auditing across gender and insurance type.

Usage

icarm_medical

Format

A tibble with 500 rows and 12 variables:

age

Integer. Patient age (18-90).

gender

Factor. male or female.

bmi

Numeric. Body mass index.

systolic_bp

Integer. Systolic blood pressure (mmHg).

diastolic_bp

Integer. Diastolic blood pressure (mmHg).

glucose_level

Integer. Fasting glucose (mg/dL).

smoker

Factor. Yes or No.

diabetes

Factor. Yes or No.

insurance

Factor. Public, Private, or None.

num_prior_visits

Integer. Prior hospital visits.

length_of_stay

Integer. Current stay in days.

readmitted

Factor. Yes (readmitted within 30 days) or No.

Source

Synthetic data generated by the icarm team.

Examples

data(icarm_medical)
m <- icarm_fit(readmitted ~ ., icarm_medical,
               model = "logistic", positive = "Yes")

Compute performance metrics for any task

Description

Compute performance metrics for any task

Usage

icarm_metrics(y_true, y_pred, y_prob = NULL, positive = NULL, type = "auto")

Arguments

Value

A named numeric vector of metrics.

Examples

# Classification
y    <- factor(c("yes","no","yes","yes","no"))
yhat <- factor(c("yes","no","no","yes","no"))
icarm_metrics(y, yhat, positive = "yes")

# Regression
icarm_metrics(c(1,2,3,4,5), c(1.1,2.2,2.9,4.1,4.8))

# Multiclass
m <- icarm_fit(Species ~ ., iris)
icarm_metrics(iris$Species, predict(m, iris))

Plot calibration curve

Description

Plot calibration curve

Usage

icarm_plot_calibration(calibration, title = NULL)

Arguments

Value

A ggplot2 object.

Plot multi-model comparison

Description

Plot multi-model comparison

Usage

icarm_plot_comparison(
  comparison,
  metrics = c("accuracy", "f1", "max_tpr_gap", "min_dp_ratio"),
  title = NULL
)

Arguments

Value

A ggplot2 object.

Plot confusion matrix

Description

Plot confusion matrix

Usage

icarm_plot_confusion(y_true, y_pred, title = NULL)

Arguments

Value

A ggplot2 object.

Examples

m    <- icarm_fit(Species ~ ., iris)
yhat <- predict(m, iris)
icarm_plot_confusion(iris$Species, yhat)

Plot group-level fairness metric

Description

Plot group-level fairness metric

Usage

icarm_plot_fairness(fairness, metric = "acc", title = NULL, ref_line = NULL)

Arguments

Value

A ggplot2 object.

Examples

m <- icarm_fit(Species ~ ., iris)
iris$size <- factor(ifelse(iris$Sepal.Length>5.8,"large","small"))
f <- icarm_fairness(m, iris, "Species", "size")
icarm_plot_fairness(f, metric = "acc")

Plot feature importance

Description

Plot feature importance

Usage

icarm_plot_importance(explainer, n_features = 15L, title = NULL)

Arguments

Value

A ggplot2 object.

Examples

m  <- icarm_fit(Species ~ ., iris)
ex <- icarm_explain(m)
icarm_plot_importance(ex)

Plot per-group ROC curves

Description

Plot per-group ROC curves

Usage

icarm_plot_roc_groups(eoc_tbl, title = NULL)

Arguments

Value

A ggplot2 object.

Plot threshold performance curves

Description

Plot threshold performance curves

Usage

icarm_plot_thresholds(
  thresholds_tbl,
  metrics = c("accuracy", "recall", "precision", "f1"),
  title = NULL
)

Arguments

Value

A ggplot2 object.

Synthetic Racism and Civic Participation Survey

Description

A synthetic dataset of 150 individuals capturing experiences of racism, policing, migration, and civic participation across multiple demographic groups. Suitable for fairness auditing, regression, binary, and multi-class classification.

Usage

icarm_racism_survey

Format

A tibble with 150 rows and 16 variables:

age

Integer. Age in years (18-75).

gender

Factor. male, female, diverse.

hair_color

Factor. blonde, brown, black, other.

skin_color

Factor. light, medium, dark.

relationship_status

Factor. single, engaged, married.

racism_impact

Integer 0-10. Perceived racism impact.

police_stop

Factor. 0 times, 1 time, 2 or more.

migrant_status

Factor. Yes or No.

income

Numeric. Monthly income (EUR).

education_level

Ordered factor. Education level.

employment_status

Factor. Employment category.

area_type

Factor. Urban or Rural.

religion

Factor. Religion category.

language_proficiency

Ordered factor. Language level.

number_of_friends

Integer 0-10.

political_orientation

Integer 0-3 (left to right).

Source

Synthetic data generated by the icarm team.

Examples

data(icarm_racism_survey)
m <- icarm_fit(racism_impact ~ ., icarm_racism_survey,
               model = "linear")

Generate a full accountability scorecard

Description

Generate a full accountability scorecard

Usage

icarm_scorecard(
  object,
  test_data,
  outcome,
  protected = NULL,
  positive = NULL,
  analyst = NULL,
  project = "icarm",
  path = NULL
)

Arguments

Value

Invisibly, the scorecard list.

Examples

sp <- icarm_split(iris, stratify = "Species")
m  <- icarm_fit(Species ~ ., sp$train)
iris_test <- sp$test
iris_test$size <- factor(
  ifelse(iris_test$Sepal.Length > 5.8, "large","small"))
icarm_scorecard(m, iris_test, outcome="Species",
                protected="size", project="Iris Demo")

Reproducible train/test split

Description

Reproducible train/test split

Usage

icarm_split(data, prop = 0.75, seed = 2025L, stratify = NULL)

Arguments

Value

A named list with train, test, seed, prop.

Examples

splits <- icarm_split(iris, prop = 0.8, stratify = "Species")
nrow(splits$train)

Threshold sweep for binary classification

Description

Threshold sweep for binary classification

Usage

icarm_thresholds(
  y_true,
  y_prob,
  positive = NULL,
  thresholds = seq(0.1, 0.9, 0.05)
)

Arguments

Value

A tibble with one row per threshold.

Examples

y   <- factor(sample(c("yes","no"), 200, replace = TRUE))
p   <- runif(200)
thr <- icarm_thresholds(y, p, positive = "yes")
icarm_plot_thresholds(thr)

Predict from an icarm_model

Description

Predict from an icarm_model

Usage

## S3 method for class 'icarm_model'
predict(object, newdata, type = c("class", "prob"), threshold = 0.5, ...)

Arguments

Value

Factor vector, probability matrix, or numeric vector.

Examples

m <- icarm_fit(Species ~ ., iris)
predict(m, iris[1:5, ], type = "class")

Print an icarm_model

Description

Print an icarm_model

Usage

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

Arguments

Value

Invisibly returns the icarm_model object x. Called for its side effect of printing a formatted summary to the console.

Summary of an icarm_model

Description

Summary of an icarm_model

Usage

## S3 method for class 'icarm_model'
summary(object, ...)

Arguments

Value

Invisibly returns the summary of the underlying fitted model object. Called for its side effect of printing a detailed model summary to the console.