funcml

funcml is a functional machine learning framework for tabular data in R.

funcml is listed in the CRAN Task View: Machine Learning & Statistical Learning.

It provides one explicit interface for the core modeling workflow:

fit models with fit()
generate predictions with predict()
validate performance with evaluate()
tune hyperparameters with tune()
compare learners with compare_learners()
interpret fitted models with interpret()
estimate causal effects with estimate()

The package is intentionally compact and opinionated: preprocessing happens before modeling, inputs stay explicit, and the API stays small instead of expanding into a large orchestration layer.

A companion paper for funcml is submitted to JMLR.

Installation

install.packages("funcml")

install.packages("remotes")
remotes::install_github("ielbadisy/funcml")

Core API

The design of funcml centers on a small set of functions:

fit()
predict()
evaluate()
tune()
compare_learners()
interpret()
estimate()

Explore the registry

funcml exposes a session-aware registry of learners, metrics, and interpretation methods.

list_learners()
#>         learner   fit   predict   tune has_fit has_predict has_tune available
#> 17     adaboost fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 24         bart fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 11          C50 fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 20      cforest fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 19        ctree fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 7      densemlp fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 8     e1071_svm fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 13        earth fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 16          fda fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 14          gam fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 10          gbm fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 1           glm fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 3        glmnet fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 12         kknn fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 21          lda fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 23     lightgbm fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 6           mlp fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 15   naivebayes fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 5          nnet fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 18          pls fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 22          qda fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 9  randomForest fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 4        ranger fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 2         rpart fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 26     stacking fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 27 superlearner fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 25      xgboost fit() predict() tune()    TRUE        TRUE     TRUE      TRUE

list_tunable_learners()
#>         learner   fit   predict   tune has_fit has_predict has_tune available
#> 17     adaboost fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 24         bart fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 11          C50 fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 20      cforest fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 19        ctree fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 7      densemlp fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 8     e1071_svm fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 13        earth fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 16          fda fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 14          gam fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 10          gbm fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 1           glm fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 3        glmnet fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 12         kknn fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 21          lda fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 23     lightgbm fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 6           mlp fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 15   naivebayes fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 5          nnet fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 18          pls fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 22          qda fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 9  randomForest fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 4        ranger fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 2         rpart fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 26     stacking fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 27 superlearner fit() predict() tune()    TRUE        TRUE     TRUE      TRUE
#> 25      xgboost fit() predict() tune()    TRUE        TRUE     TRUE      TRUE

list_metrics()
#>               metric direction
#> 1               rmse  minimize
#> 2                mae  minimize
#> 3                mse  minimize
#> 4              medae  minimize
#> 5               mape  minimize
#> 6                rsq  maximize
#> 7           accuracy  maximize
#> 8          precision  maximize
#> 9             recall  maximize
#> 10       specificity  maximize
#> 11                f1  maximize
#> 12 balanced_accuracy  maximize
#> 13           logloss  minimize
#> 14             brier  minimize
#> 15               auc  maximize
#> 16      auc_weighted  maximize
#> 17               ece  minimize
#> 18               mce  minimize
#>                                                       summary     range
#> 1         Root mean squared error for regression predictions.  [0, Inf)
#> 2             Mean absolute error for regression predictions.  [0, Inf)
#> 3              Mean squared error for regression predictions.  [0, Inf)
#> 4           Median absolute error for regression predictions.  [0, Inf)
#> 5  Mean absolute percentage error for regression predictions.  [0, Inf)
#> 6    Coefficient of determination for regression predictions. (-Inf, 1]
#> 7                                    Classification accuracy.    [0, 1]
#> 8                    Macro-averaged classification precision.    [0, 1]
#> 9                       Macro-averaged classification recall.    [0, 1]
#> 10                 Macro-averaged classification specificity.    [0, 1]
#> 11                                   Macro-averaged F1 score.    [0, 1]
#> 12                          Macro-averaged balanced accuracy.    [0, 1]
#> 13  Negative log-likelihood for classification probabilities.  [0, Inf)
#> 14              Brier score for classification probabilities.    [0, 2]
#> 15                                  Area under the ROC curve.    [0, 1]
#> 16              Weighted multiclass area under the ROC curve.    [0, 1]
#> 17      Expected calibration error for binary classification.    [0, 1]
#> 18       Maximum calibration error for binary classification.    [0, 1]

list_interpretability_methods()
#>                                  compute   plot has_compute has_plot
#> 1              interpret(method = "vip") plot()        TRUE     TRUE
#> 2          interpret(method = "permute") plot()        TRUE     TRUE
#> 3              interpret(method = "pdp") plot()        TRUE     TRUE
#> 4              interpret(method = "ice") plot()        TRUE     TRUE
#> 5              interpret(method = "ale") plot()        TRUE     TRUE
#> 6            interpret(method = "local") plot()        TRUE     TRUE
#> 7             interpret(method = "lime") plot()        TRUE     TRUE
#> 8             interpret(method = "shap") plot()        TRUE     TRUE
#> 9      interpret(method = "local_model") plot()        TRUE     TRUE
#> 10     interpret(method = "interaction") plot()        TRUE     TRUE
#> 11       interpret(method = "surrogate") plot()        TRUE     TRUE
#> 12         interpret(method = "profile") plot()        TRUE     TRUE
#> 13 interpret(method = "ceteris_paribus") plot()        TRUE     TRUE
#> 14     interpret(method = "calibration") plot()        TRUE     TRUE

Example data

This README uses funcml::arthritis as the main running example.

Here, status is the outcome for a binary classification task.

demo_dat <- funcml::arthritis
demo_dat$status <- as.factor(demo_dat$status)
levels(demo_dat$status)
#> [1] "No"  "Yes"

Fit a classification model

fit() trains a model and returns a funcml_fit object.

xgb_spec <- list(
  nrounds = 30,
  max_depth = 3,
  eta = 0.1,
  subsample = 1,
  colsample_bytree = 1
)

fit_obj <- fit(
  status ~ age + gender + bmi + diabetes + smoke + covered_health,
  data = demo_dat,
  model = "xgboost",
  spec = xgb_spec,
  seed = 42
)

fit_obj
#> <funcml_fit> classification model: xgboost
#> Formula: status ~ age + gender + bmi + diabetes + smoke + covered_health
#> Features: 6 | Obs: 4856

Generate predictions

The same fitted object can produce class predictions or class probabilities.

predict(fit_obj, demo_dat[1:6, ])
#> [1] Yes No  No  No  No  No 
#> Levels: No Yes

pred_prob <- predict(
  fit_obj,
  demo_dat[1:6, ],
  type = "prob"
)

pred_prob
#>             No        Yes
#> [1,] 0.4382392 0.56176078
#> [2,] 0.5414010 0.45859897
#> [3,] 0.8288925 0.17110750
#> [4,] 0.9638367 0.03616334
#> [5,] 0.5076765 0.49232352
#> [6,] 0.5064105 0.49358952

Evaluate predictive performance

evaluate() applies the same learner under a resampling plan and returns fold-level results with summary statistics.

eval_obj <- evaluate(
  data = demo_dat,
  formula = status ~ age + gender + bmi + diabetes + smoke + covered_health,
  model = "xgboost",
  spec = xgb_spec,
  resampling = cv(v = 4, seed = 42)
)

eval_obj
#> <funcml_eval> model: xgboost | task: classification
#>               metric   mean     sd n std_error conf_level conf_low conf_high
#> 1           accuracy 0.7473 0.0146 4    0.0073       0.95   0.7241    0.7706
#> 2          precision 0.6932 0.0234 4    0.0117       0.95   0.6559    0.7304
#> 3             recall 0.6405 0.0178 4    0.0089       0.95   0.6121    0.6689
#> 4        specificity 0.6405 0.0178 4    0.0089       0.95   0.6121    0.6689
#> 5                 f1 0.6657 0.0195 4    0.0098       0.95   0.6347    0.6968
#> 6  balanced_accuracy 0.6405 0.0178 4    0.0089       0.95   0.6121    0.6689
#> 7            logloss 0.4925 0.0088 4    0.0044       0.95   0.4785    0.5065
#> 8              brier 0.3278 0.0076 4    0.0038       0.95   0.3158    0.3398
#> 9                auc 0.7869 0.0118 4    0.0059       0.95   0.7681    0.8058
#> 10               ece 0.0359 0.0042 4    0.0021       0.95   0.0292    0.0426
#> 11               mce 0.0800 0.0137 4    0.0068       0.95   0.0583    0.1018

plot(eval_obj)

funcml also supports grouped cross-validation, time-based resampling, and holdout validation through group_cv(), time_cv(), and holdout().

Tune hyperparameters

tune() searches candidate hyperparameter settings using the same evaluation framework.

tune_grid <- expand.grid(
  max_depth = c(2, 3),
  eta = c(0.05, 0.1),
  nrounds = c(20, 30)
)

tune_obj <- tune(
  data = demo_dat,
  formula = status ~ age + gender + bmi + diabetes + smoke + covered_health,
  model = "xgboost",
  grid = tune_grid,
  resampling = cv(v = 3, seed = 42),
  metric = "logloss",
  subsample = 1,
  colsample_bytree = 1,
  seed = 42
)

tune_obj
#> <funcml_tune> metric=logloss direction=min search=grid
#> Best:
#>   max_depth eta nrounds   mean     sd n std_error conf_level conf_low conf_high
#> 8         3 0.1      30 0.4933 0.0119 3    0.0069       0.95   0.4636    0.5229

plot(tune_obj)

Compare learners

compare_learners() benchmarks multiple learners under a common resampling design.

compare_obj <- compare_learners(
  data = demo_dat,
  formula = status ~ age + gender + bmi + diabetes + smoke + covered_health,
  models = c("glm", "rpart", "xgboost"),
  metrics = c("accuracy", "logloss"),
  resampling = cv(v = 4, seed = 42),
  specs = list(xgboost = xgb_spec)
)

compare_obj
#> <funcml_compare> task: classification | tuned: FALSE
#>     model   metric   mean     sd n std_error conf_level conf_low conf_high
#> 1     glm accuracy 0.7451 0.0170 4    0.0085       0.95   0.7180    0.7722
#> 2     glm  logloss 0.4897 0.0131 4    0.0066       0.95   0.4688    0.5106
#> 3   rpart accuracy 0.7337 0.0167 4    0.0084       0.95   0.7071    0.7603
#> 4   rpart  logloss 0.5311 0.0130 4    0.0065       0.95   0.5104    0.5517
#> 5 xgboost accuracy 0.7473 0.0146 4    0.0073       0.95   0.7241    0.7706
#> 6 xgboost  logloss 0.4925 0.0088 4    0.0044       0.95   0.4785    0.5065
#>   tuned rank
#> 1 FALSE    2
#> 2 FALSE    1
#> 3 FALSE    3
#> 4 FALSE    3
#> 5 FALSE    1
#> 6 FALSE    2

plot(compare_obj)

Interpret fitted models

interpret() operates directly on fitted funcml_fit objects.

permute_obj <- interpret(
  fit = fit_obj,
  data = demo_dat,
  method = "permute",
  nsim = 20,
  seed = 42
)

summary(permute_obj)
#>          feature   importance      std_dev
#> 1            age 0.0768121911 0.0039101175
#> 2         gender 0.0192030478 0.0032380942
#> 3            bmi 0.0175658979 0.0038212586
#> 4 covered_health 0.0056013180 0.0021176594
#> 5          smoke 0.0053953871 0.0017159311
#> 6       diabetes 0.0005663097 0.0003398597

plot(permute_obj)

A second example shows accumulated local effects for one feature from the same fitted model.

ale_obj <- interpret(
  fit = fit_obj,
  data = demo_dat,
  method = "ale",
  features = c("age"),
  type = "prob"
)

plot(ale_obj)

Partial dependence shows the model-implied effect of one feature, averaged over the rest of the data.

pdp_obj <- interpret(
  fit = fit_obj,
  data = demo_dat,
  method = "pdp",
  features = c("age"),
  type = "prob"
)

plot(pdp_obj)

SHAP values explain an individual prediction. interpret(method = "shap") computes them with funcml’s own Monte Carlo permutation estimate (no external SHAP dependency); plot() supports waterfall, force, beeswarm/summary, importance, dependence, dependence2d, and interaction views.

shap_obj <- interpret(
  fit = fit_obj,
  data = demo_dat,
  method = "shap",
  newdata = demo_dat[1, , drop = FALSE],
  nsim = 30,
  type = "prob",
  seed = 42
)

plot(shap_obj, kind = "waterfall")

The beeswarm/summary view explains the model across many observations at once, ordered by mean absolute SHAP value and colored by feature value.

shap_many_obj <- interpret(
  fit = fit_obj,
  data = demo_dat,
  method = "shap",
  newdata = demo_dat[1:80, , drop = FALSE],
  nsim = 15,
  type = "prob",
  seed = 42
)

plot(shap_many_obj, kind = "beeswarm")

Other supported methods include ICE, local explanations, surrogate models, and interaction diagnostics.

Inspect calibration

For classification, the same interface also supports calibration diagnostics.

calibration_obj <- interpret(
  fit = fit_obj,
  data = demo_dat,
  method = "calibration",
  type = "prob",
  bins = 10,
  strategy = "quantile"
)

plot(calibration_obj)

Decision curve analysis

interpret(method = "dca") reports net benefit across risk thresholds against the “treat all” and “treat none” strategies (Vickers and Elkin, 2006).

dca_obj <- interpret(
  fit = fit_obj,
  data = demo_dat,
  method = "dca"
)

plot(dca_obj)

ROC curve and AUC confidence interval

roc_curve() and auc_ci() are standalone metric functions (backed by pROC) for a full ROC curve and a DeLong or bootstrap confidence interval on AUC.

truth_vec <- demo_dat$status
prob_vec <- predict(fit_obj, demo_dat, type = "prob")[, "Yes"]

roc_obj <- roc_curve(truth_vec, prob_vec)
plot(roc_obj)

auc_ci(truth_vec, prob_vec)
#>      auc conf_low conf_high conf_level method
#> 1 0.8056   0.7929    0.8183       0.95 delong

Estimate causal effects

estimate() extends the same framework to plug-in g-computation estimands such as the ATE.

The example below treats smoke as the treatment variable and status as the outcome, adjusting for the remaining covariates.

est_obj <- estimate(
  data = demo_dat,
  formula = status ~ smoke + diabetes + age + gender + bmi + covered_health,
  model = "glm",
  estimand = "ATE",
  treatment = "smoke",
  interval = "normal",
  seed = 42
)

est_obj
#> <funcml_estimand> ATE via g-computation
#> Treatment: smoke (Yes vs No)
#> Estimate: 0.0897 | SE: 0.0006 | 95% normal CI [0.0886, 0.0908]

By default, plot() shows the model-implied potential outcome distributions under treatment and control, with dashed lines marking the corresponding means. The unit-level effect histogram remains available with plot(est_obj, style = "effects").

plot(est_obj)

The same interface also supports ATT, CATE, and IATE.

Ensembles as first-class learners

Ensembles live in the same learner registry as base models.

stack_fit <- fit(
  status ~ age + gender + bmi + diabetes + smoke + covered_health,
  data = demo_dat,
  model = "superlearner", # or "stacking"
  spec = list(
    learners = c("glm", "rpart", "xgboost", "nnet"),
    learner_specs = list(xgboost = xgb_spec),
    meta_model = "glmnet"
  ),
  seed = 42
)

predict(stack_fit, demo_dat[1:5, ], type = "prob")
#>             No        Yes
#> [1,] 0.3184784 0.68152164
#> [2,] 0.5011472 0.49885283
#> [3,] 0.8758539 0.12414610
#> [4,] 0.9258312 0.07416884
#> [5,] 0.4985016 0.50149842

Summary

funcml provides a compact interface for tabular machine learning in R.

Use it to:

train models
generate predictions
validate performance
tune hyperparameters
compare learners
interpret fitted models
estimate causal effects

The package is designed to keep the main analysis workflow explicit.

Contributing

Contributions are welcome.

For development setup, coding standards, and pull request guidelines, see CONTRIBUTING.md.

Citation

If you use funcml in your work, please cite it.

pkgload::unload("funcml")
library(funcml)
citation("funcml")
#> To cite package 'funcml' in publications use:
#> 
#>   El Badisy I (2026). _funcml: Functional Machine Learning Framework_.
#>   R package version 0.8.8, <https://github.com/ielbadisy/funcml>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {funcml: Functional Machine Learning Framework},
#>     author = {Imad {El Badisy}},
#>     year = {2026},
#>     note = {R package version 0.8.8},
#>     url = {https://github.com/ielbadisy/funcml},
#>   }

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
R		R
README_files/figure-gfm		README_files/figure-gfm
data		data
dev		dev
inst/extdata		inst/extdata
man		man
tests		tests
vignettes		vignettes
.Rbuildignore		.Rbuildignore
.gitignore		.gitignore
CITATION.cff		CITATION.cff
CONTRIBUTING.md		CONTRIBUTING.md
DESCRIPTION		DESCRIPTION
NAMESPACE		NAMESPACE
NEWS.md		NEWS.md
README.Rmd		README.Rmd
README.md		README.md
cran-comments.md		cran-comments.md

Navigation Menu

Repository files navigation

funcml

Installation

Core API

Explore the registry

Example data

Fit a classification model

Generate predictions

Evaluate predictive performance

Tune hyperparameters

Compare learners

Interpret fitted models

Inspect calibration

Decision curve analysis

ROC curve and AUC confidence interval

Estimate causal effects

Ensembles as first-class learners

Summary

Contributing

Citation

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

funcml

Installation

Core API

Explore the registry

Example data

Fit a classification model

Generate predictions

Evaluate predictive performance

Tune hyperparameters

Compare learners

Interpret fitted models

Inspect calibration

Decision curve analysis

ROC curve and AUC confidence interval

Estimate causal effects

Ensembles as first-class learners

Summary

Contributing

Citation

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages