Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ielbadisy/funcml

Functional Machine Learning in R
https://github.com/ielbadisy/funcml

classification g-computation interpretable-machine-learning machine-learning regression tabular-data

Last synced: 19 days ago
JSON representation

Functional Machine Learning in R

Awesome Lists containing this project

README 

          
---

output: github_document

---



```{r, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-",

  out.width = "100%",

  warning = FALSE,

  message = FALSE

)



pkgload::load_all(".", export_all = FALSE, helpers = FALSE, quiet = TRUE)

ggplot2::theme_set(theme_funcml())

set.seed(42)

```



# funcml



[![R-CMD-check](https://github.com/ielbadisy/funcml/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ielbadisy/funcml/actions/workflows/R-CMD-check.yaml)

[![CRAN status](https://www.r-pkg.org/badges/version/funcml)](https://CRAN.R-project.org/package=funcml)

[![CRAN checks](https://badges.cranchecks.info/worst/funcml.svg)](https://cran.r-project.org/web/checks/check_results_funcml.html)

[![CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/funcml)](https://cran.r-project.org/package=funcml)

[![License: GPL-3](https://img.shields.io/badge/license-GPL--3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

[![CRAN Task View: Machine Learning](https://img.shields.io/badge/CRAN%20Task%20View-Machine%20Learning-2c7fb8)](https://cran.r-project.org/web/views/MachineLearning.html)

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20707605.svg)](https://doi.org/10.5281/zenodo.20707605)



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



`funcml` is listed in the

[CRAN Task View: Machine Learning & Statistical Learning](https://cran.r-project.org/web/views/MachineLearning.html).



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



```r

install.packages("funcml")



install.packages("remotes")

remotes::install_github("ielbadisy/funcml")

```



## Core API



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



```r

fit()

predict()

evaluate()

tune()

compare_learners()

interpret()

estimate()

```



## Explore the registry



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



```{r registry}

list_learners()

```



```{r registry-tunable}

list_tunable_learners()

```



```{r registry-metrics}

list_metrics()

```



```{r registry-interpret}

list_interpretability_methods()

```



## Example data



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



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



```{r demo-data}

demo_dat <- funcml::arthritis

demo_dat$status <- as.factor(demo_dat$status)

levels(demo_dat$status)

```



## Fit a classification model



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



```{r fit-model}

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

```



## Generate predictions



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



```{r predict-class}

predict(fit_obj, demo_dat[1:6, ])

```



```{r predict-prob}

pred_prob <- predict(

  fit_obj,

  demo_dat[1:6, ],

  type = "prob"

)



pred_prob

```



## Evaluate predictive performance



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



```{r evaluate-model}

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

```



```{r evaluate-plot}

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.



```{r tune-model}

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

```



```{r tune-plot}

plot(tune_obj)

```



## Compare learners



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



```{r compare-models}

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

```



```{r compare-plot}

plot(compare_obj)

```



## Interpret fitted models



`interpret()` operates directly on fitted `funcml_fit` objects.



```{r interpret-permute}

permute_obj <- interpret(

  fit = fit_obj,

  data = demo_dat,

  method = "permute",

  nsim = 20,

  seed = 42

)



summary(permute_obj)

```



```{r interpret-permute-plot}

plot(permute_obj)

```



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



```{r interpret-ale}

ale_obj <- interpret(

  fit = fit_obj,

  data = demo_dat,

  method = "ale",

  features = c("age"),

  type = "prob"

)



plot(ale_obj)

```



Other supported methods include PDP, ICE, SHAP, local explanations, surrogate models, interaction diagnostics, and calibration plots.



## Inspect calibration



For classification, the same interface also supports calibration diagnostics.



```{r calibration}

calibration_obj <- interpret(

  fit = fit_obj,

  data = demo_dat,

  method = "calibration",

  type = "prob",

  bins = 10,

  strategy = "quantile"

)



plot(calibration_obj)

```



## 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.



```{r estimate-causal}

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

```



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")`.



```{r estimate-plot}

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.



```{r ensemble}

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")

```



## 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 using one of the references below.



**Zenodo (preferred, citable archive):**

```

EL BADISY, I. (2026). funcml: Functional Machine Learning Software for R. https://doi.org/10.5281/zenodo.20707605

```



**GitHub repository:**

```

El Badisy, I. (2026). funcml (Version 0.7.1) [Computer software]. https://github.com/ielbadisy/funcml

```



BibTeX:

```

@software{El_Badisy_funcml_2026, author = {El Badisy, Imad},

license = {GPL-3.0-only},

month = apr,

title = {{funcml}},

doi = {10.5281/zenodo.20707605},

url = {https://doi.org/10.5281/zenodo.20707605},

version = {0.7.1},

year = {2026}

}

```