civic_fit: Fit an interpretable ICARM model — works with any tabular...

In civic.icarm: Interpretable Civic-Accountable and Responsible Machine Learning

Fit an interpretable ICARM model — works with any tabular data

Description

Single unified entry point for all civic.icarm modelling. Automatically detects the prediction task from your target variable — you do not need to choose between classification and regression upfront.

**Task auto-detection rules:** | Target type | Task | Default model | |—|—|—| | 'factor' / 'character', 2 levels | Binary classification | '"cart"' | | 'factor' / 'character', 3+ levels | Multi-class classification | '"cart"' | | 'numeric' / 'integer' | Regression | '"cart"' |

**Supported models:**

*Binary classification:* - '"cart"' — Classification tree (rpart). Fully inspectable. - '"logistic"' — Logistic regression (stats::glm). Coefficient-interpretable. - '"logistic_l1"' — L1-penalised logistic (glmnet). Requires 'glmnet'.

*Multi-class classification:* - '"cart"' — Classification tree (rpart). Handles any number of classes. - '"multinomial"' — Multinomial logistic regression (nnet). Requires 'nnet'.

*Regression:* - '"cart"' — Regression tree (rpart). - '"linear"' — Ordinary least squares (stats::lm). - '"gam"' — Generalised Additive Model (mgcv). Requires 'mgcv'.

Usage

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

Arguments

formula	A model formula. Use '.' for all columns: 'target ~ .' or 'target ~ x1 + x2 + x3'.
data	A 'data.frame' or 'tibble' of training data.
task	One of '"auto"' (default), '"binary"', '"multiclass"', or '"regression"'. Use '"auto"' to let the package detect the task.
model	Character. Model type. Use '"auto"' to let the package pick a sensible default, or specify one explicitly (see above).
seed	Integer. Random seed recorded for reproducibility (default 2025).
cart_control	A [rpart::rpart.control()] list for tuning CART trees. Default: 'cp = 0.01', 'minsplit = 20'.
positive	Character. For binary classification: which factor level is the "positive" class. If 'NULL', uses the first factor level.
...	Additional arguments passed to the underlying model fitter.

Value

An S3 object of class 'civic_model' containing:

'fit'

The underlying fitted model object.

'task'

Detected/specified task: '"binary"', '"multiclass"', or '"regression"'.

'model'

Model type string.

'formula'

The model formula used.

'outcome'

Name of the target/outcome variable.

'levels'

Factor levels (classification only).

'positive'

Positive class (binary classification only).

'seed'

Random seed used.

'n_train'

Number of training rows.

'data_hash'

SHA-256 digest of training data for provenance.

'trained_at'

POSIXct timestamp.

'n_features'

Number of predictor features.

'feature_names'

Names of predictor features.

Examples

# Binary classification (auto-detected from factor target)
data(civic_voting)
m <- civic_fit(voted ~ age + education + political_interest,
               data = civic_voting)
print(m)

# Regression (auto-detected from numeric target)
data(civic_education)
m2 <- civic_fit(civic_knowledge_score ~ age + stats_course + news_consumption,
                data = civic_education)

# Explicit model choice
m3 <- civic_fit(voted ~ ., data = civic_voting, model = "logistic")

# Works on any data frame — here using the built-in iris dataset
m4 <- civic_fit(Species ~ ., data = iris)   # multi-class
m5 <- civic_fit(Sepal.Length ~ ., data = iris)  # regression

civic.icarm documentation built on June 18, 2026, 1:06 a.m.