diff --git a/DESCRIPTION b/DESCRIPTION index 14087e31..74330c90 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,8 @@ Package: FFTrees Type: Package Title: Generate, Visualise, and Evaluate Fast-and-Frugal Decision Trees -Version: 2.1.0 -Date: 2025-09-03 +Version: 2.1.0.9001 +Date: 2026-05-02 Authors@R: c(person("Nathaniel", "Phillips", role = c("aut"), email = "Nathaniel.D.Phillips.is@gmail.com", comment = c(ORCID = "0000-0002-8969-7013")), person("Hansjoerg", "Neth", role = c("aut", "cre"), email = "h.neth@uni.kn", comment = c(ORCID = "0000-0001-5427-3141")), person("Jan", "Woike", role = "aut", comment = c(ORCID = "0000-0002-6816-121X")), @@ -32,5 +32,5 @@ License: CC0 URL: https://CRAN.R-project.org/package=FFTrees, https://www.nathanieldphillips.co/FFTrees/ BugReports: https://github.com/ndphillips/FFTrees/issues VignetteBuilder: knitr -RoxygenNote: 7.3.2 +RoxygenNote: 7.3.3 Language: en-US diff --git a/R/fftrees_cuerank.R b/R/fftrees_cuerank.R index a3fd188b..1ca9f35c 100644 --- a/R/fftrees_cuerank.R +++ b/R/fftrees_cuerank.R @@ -35,8 +35,8 @@ fftrees_cuerank <- function(x = NULL, newdata = NULL, - data = "train", # type of data - rounding = NULL) { + data = "train", # type of data + rounding = NULL) { # ToDo: Use a sensible default, e.g., rounding = 3 (in the FFTrees() function) # Prepare: ------ diff --git a/README.Rmd b/README.Rmd index 337bfae1..bbac4724 100644 --- a/README.Rmd +++ b/README.Rmd @@ -37,16 +37,16 @@ doi_JDM <- "10.1017/S1930297500006239" # FFTrees `r packageVersion("FFTrees")` FFTrees - - - - +[![CRAN status](https://www.r-pkg.org/badges/version/FFTrees)](https://CRAN.R-project.org/package=FFTrees) +[![Downloads/month](https://cranlogs.r-pkg.org/badges/FFTrees?color="00a9e0")](https://www.r-pkg.org/pkg/FFTrees) +[![Total downloads](https://cranlogs.r-pkg.org/badges/grand-total/FFTrees?color="00a9e0")](https://www.r-pkg.org/pkg/FFTrees) +[![R-CMD-check](https://github.com/ndphillips/FFTrees/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ndphillips/FFTrees/actions/workflows/R-CMD-check.yaml) -[![CRAN status](https://www.r-pkg.org/badges/version/FFTrees)](https://CRAN.R-project.org/package=FFTrees) -[![Total downloads](https://cranlogs.r-pkg.org/badges/grand-total/FFTrees?color="00a9e0")](https://www.r-pkg.org/pkg/FFTrees) + + @@ -106,8 +106,39 @@ library(FFTrees) # load package ``` +### Questions answered by FFTs + + + +A _fast-and-frugal tree_ (FFT) provides answers to binary prediction problems like: + +- Which of 2 categories should we predict for each individual case in the data? +- How successful is this prediction process for a sample of cases? + + + +To _create_ FFTs, we must answer 2 key questions: + +- Which variables should we use to predict the criterion? +- How should we combine those predictor variables into FFTs? + + + +Once we have created FFTs, questions regarding their _performance_ include: + +- How accurate are the predictions of a specific FFT? +- How costly are the predictions of each algorithm? + +Answering these performance-related questions requires applying FFTs to data. + + + +The **FFTrees** package answers these questions by creating, evaluating, and visualizing FFTs. + + ### Using data +Any prediction problem requires some data that contains some predictors and a criterion variable. The `heartdisease` data provides medical information for 303\ patients that were examined for heart disease. The full data contains a binary criterion variable describing the true state of each patient and were split into two subsets: A `heart.train` set for fitting decision trees, and `heart.test` set for a testing these trees. @@ -134,21 +165,6 @@ knitr::kable(head(heart.test), caption = c_test) Our challenge is to predict each patient's `diagnosis` ---\ a column of logical values indicating the true state of each patient (i.e., `TRUE` or\ `FALSE`, based on the patient suffering or not suffering from heart disease)\ --- from the values of potential predictors. -### Questions answered by FFTs - -To solve binary classification problems by FFTs, we must answer two key questions: - -- Which of the variables should we use to predict the criterion? -- How should we use and combine predictor variables into FFTs? - -Once we have created some FFTs, additional questions include: - -- How accurate are the predictions of a specific FFT? -- How costly are the predictions of each algorithm? - -The **FFTrees** package answers these questions by creating, evaluating, and visualizing FFTs. - - ### Creating fast-and-frugal trees (FFTs) We use the main `FFTrees()` function to create FFTs for the `heart.train` data and evaluate their predictive performance on the `heart.test` data: @@ -281,7 +297,7 @@ When using **FFTrees** in your own work, please cite us and share your experienc -By\ 2025, over 150\ scientific publications have used or cited **FFTrees** (see [Google Scholar](https://scholar.google.com/scholar?oi=bibs&hl=en&cites=205528310591558601) for the full list). +By\ 2026, over 160\ scientific publications have used or cited **FFTrees** (see [Google Scholar](https://scholar.google.com/scholar?oi=bibs&hl=en&cites=205528310591558601) for the full list). Examples include: - Lötsch, J., Haehner, A., & Hummel, T. (2020). Machine-learning-derived rules set excludes risk of Parkinson’s disease in patients with olfactory or gustatory symptoms with high accuracy. @@ -308,6 +324,7 @@ Age at diagnosis, but not HPV type, is strongly associated with clinical course _PloS One_, _14_(6). doi\ [10.1371/journal.pone.0216697](https://doi.org/10.1371/journal.pone.0216697) + ---- diff --git a/README.md b/README.md index 8784f834..cb1b7231 100644 --- a/README.md +++ b/README.md @@ -3,26 +3,24 @@ -# FFTrees 2.1.0 FFTrees +# FFTrees 2.1.0.9001 FFTrees - - - - - - - - - - - - [![CRAN status](https://www.r-pkg.org/badges/version/FFTrees)](https://CRAN.R-project.org/package=FFTrees) +[![Downloads/month](https://cranlogs.r-pkg.org/badges/FFTrees?color=%2200a9e0%22)](https://www.r-pkg.org/pkg/FFTrees) [![Total downloads](https://cranlogs.r-pkg.org/badges/grand-total/FFTrees?color=%2200a9e0%22)](https://www.r-pkg.org/pkg/FFTrees) +[![R-CMD-check](https://github.com/ndphillips/FFTrees/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ndphillips/FFTrees/actions/workflows/R-CMD-check.yaml) + + + + + + + + @@ -102,14 +100,50 @@ included in **FFTrees**: library(FFTrees) # load package ``` +### Questions answered by FFTs + + + +A *fast-and-frugal tree* (FFT) provides answers to binary prediction +problems like: + +- Which of 2 categories should we predict for each individual case in + the data? +- How successful is this prediction process for a sample of cases? + + + +To *create* FFTs, we must answer 2 key questions: + +- Which variables should we use to predict the criterion? +- How should we combine those predictor variables into FFTs? + + + +Once we have created FFTs, questions regarding their *performance* +include: + +- How accurate are the predictions of a specific FFT? +- How costly are the predictions of each algorithm? + +Answering these performance-related questions requires applying FFTs to +data. + + + +The **FFTrees** package answers these questions by creating, evaluating, +and visualizing FFTs. + ### Using data -The `heartdisease` data provides medical information for 303 patients -that were examined for heart disease. The full data contains a binary -criterion variable describing the true state of each patient and were -split into two subsets: A `heart.train` set for fitting decision trees, -and `heart.test` set for a testing these trees. Here are the first rows -and columns of both subsets of the `heartdisease` data: +Any prediction problem requires some data that contains some predictors +and a criterion variable. The `heartdisease` data provides medical +information for 303 patients that were examined for heart disease. The +full data contains a binary criterion variable describing the true state +of each patient and were split into two subsets: A `heart.train` set for +fitting decision trees, and `heart.test` set for a testing these trees. +Here are the first rows and columns of both subsets of the +`heartdisease` data: - `heart.train` (the training / fitting data) describes 150 patients: @@ -145,22 +179,6 @@ logical values indicating the true state of each patient (i.e., `TRUE` or `FALSE`, based on the patient suffering or not suffering from heart disease) — from the values of potential predictors. -### Questions answered by FFTs - -To solve binary classification problems by FFTs, we must answer two key -questions: - -- Which of the variables should we use to predict the criterion? -- How should we use and combine predictor variables into FFTs? - -Once we have created some FFTs, additional questions include: - -- How accurate are the predictions of a specific FFT? -- How costly are the predictions of each algorithm? - -The **FFTrees** package answers these questions by creating, evaluating, -and visualizing FFTs. - ### Creating fast-and-frugal trees (FFTs) We use the main `FFTrees()` function to create FFTs for the @@ -195,7 +213,7 @@ plot(heart_fft, main = "Heart Disease") ``` - + **Figure 1**: A fast-and-frugal tree (FFT) predicting heart disease for `test` data and its performance characteristics. @@ -239,7 +257,7 @@ plot(my_fft, main = "My custom FFT") ``` - + **Figure 2**: An FFT predicting heart disease created from a verbal description. @@ -304,7 +322,7 @@ continue developing the package. -By 2025, over 150 scientific publications have used or cited **FFTrees** +By 2026, over 160 scientific publications have used or cited **FFTrees** (see [Google Scholar](https://scholar.google.com/scholar?oi=bibs&hl=en&cites=205528310591558601) for the full list). Examples include: @@ -344,6 +362,6 @@ for the full list). Examples include: ------------------------------------------------------------------------ -\[File `README.Rmd` last updated on 2025-09-03.\] +\[File `README.Rmd` last updated on 2026-05-02.\] diff --git a/inst/HeartFFT.jpeg b/inst/HeartFFT.jpeg deleted file mode 100644 index f51da542..00000000 Binary files a/inst/HeartFFT.jpeg and /dev/null differ diff --git a/man/figures/README-example-heart-plot-1.png b/man/figures/README-example-heart-plot-1.png index 064181fe..36895ae6 100644 Binary files a/man/figures/README-example-heart-plot-1.png and b/man/figures/README-example-heart-plot-1.png differ diff --git a/man/figures/README-example-heart-verbal-1.png b/man/figures/README-example-heart-verbal-1.png index 9e665876..b9ecaf9e 100644 Binary files a/man/figures/README-example-heart-verbal-1.png and b/man/figures/README-example-heart-verbal-1.png differ diff --git a/vignettes/FFTrees_examples.Rmd b/vignettes/FFTrees_examples.Rmd index af97ba52..03290a5e 100644 --- a/vignettes/FFTrees_examples.Rmd +++ b/vignettes/FFTrees_examples.Rmd @@ -164,20 +164,20 @@ knitr::include_graphics("virginica.jpg") ``` The `iris.v` dataset contains data about 150\ flowers (see `?iris.v`). -Our goal is to predict which flowers are of the class _Virginica_. -In this example, we'll create trees using the entire dataset (without splitting the available data into explicit training vs. test subsets), so that we are really fitting the data, rather than engaging in genuine prediction: +Our present goal is to predict which flowers are of the class _Virginica_. +In this example, we create trees using the entire dataset (without splitting the available data into explicit training vs. test subsets), so that we are really fitting the data, rather than engaging in prediction: ```{r iris-fft, message = FALSE, results = 'hide'} # Create FFTrees object for iris data: iris_fft <- FFTrees(formula = virginica ~., data = iris.v, - main = "Iris viginica", + main = "Iris virginica", decision.labels = c("Not-Vir", "Vir")) ``` -The **FFTrees** package provides various functions to inspect the `FFTrees` object `iris_fft`. +The **FFTrees** package provides various functions to inspect the `FFTrees` object\ `iris_fft`. For summary information on the best training tree, we can print the `FTrees` object (by evaluating `iris_fft` or `print(iris_fft)`). -Alternatively, we could visualize the tree (via `plot(iris_fft)`) or summarize the `FFTrees` object (via `summary(iris_fft)`): +Alternatively, we can visualize the tree (via `plot(iris_fft)`) or summarize the `FFTrees` object (via `summary(iris_fft)`): ```{r iris-fft-print, echo = TRUE, eval = FALSE, results = 'hide'} # Inspect resulting FFTs: @@ -198,7 +198,7 @@ We can plot the training cue accuracies during training by specifying `what = "c plot(iris_fft, what = "cues") ``` -It looks like the two cues\ `pet.len` and\ `pet.wid` are the best predictors for this dataset. +It looks like the two cues\ `pet.len` and\ `pet.wid` are the best predictors for this data. Based on this insight, we should expect the final trees will likely use one or both of these cues. diff --git a/vignettes/FFTrees_mytree.Rmd b/vignettes/FFTrees_mytree.Rmd index a72e3ec2..9dbfc2e0 100644 --- a/vignettes/FFTrees_mytree.Rmd +++ b/vignettes/FFTrees_mytree.Rmd @@ -589,7 +589,7 @@ summary(y) # plot(y, tree = 1) ``` -Comparing the accuracy statistics of our new FFTs (in object\ `y`) to our original FFTs (in object\ `x`) shows that swapping the 2nd and 3rd cue had hardly an effect. +Comparing the accuracy statistics of our new FFTs (in object\ `y`) to our original FFTs (in object\ `x`) shows that swapping the 2nd and 3rd cues hardly had an\ effect. Upon reflection, this is not surprising: Most people are still classified into the same categories as before. However, if we were to evaluate the costs of classification (e.g., by considering the\ `pci` and\ `mcu` measures or the `cost` measures for cue usage), we could still detect differences between FFTs that show the same accuracy. @@ -598,7 +598,8 @@ However, if we were to evaluate the costs of classification (e.g., by considerin We just created a new `FFTrees` object\ `y` by using `FFTrees` object\ `x` for a set of customized FFTs defined by the `tree.definitions` argument. This circumvented the FFT building algorithms and used the provided FFT definitions instead. -Thus, the ordinary distinction between training and test data no longer applies in this context: As no model is being fitted here, both sets were used to evaluate the FFTs in `tree.definitions` on these data. +Thus, the ordinary distinction between training and test data no longer applies in this context: +As no model is being fitted here, both sets were used to evaluate (or "test") the FFTs in `tree.definitions` on these data. Acknowledging this, we may use the full dataset of `heartdisease`, rather than splitting it into two distinct subsets: diff --git a/vignettes/FFTrees_plot.Rmd b/vignettes/FFTrees_plot.Rmd index ac7cf21d..dad0a316 100644 --- a/vignettes/FFTrees_plot.Rmd +++ b/vignettes/FFTrees_plot.Rmd @@ -31,6 +31,7 @@ knitr::opts_chunk$set(collapse = FALSE, library(FFTrees) ``` + ## Visualizing FFTrees The **FFTrees** package makes it very easy to visualize and evaluate fast-and-frugal trees (FFTs): @@ -122,6 +123,7 @@ By contrast, `age`\ (3) seems a pretty poor cue for predicting survival on its o Inspecting cue accuracies can provide valuable information for constructing FFTs. While they provide lower bounds on the performance of trees (as combining cues is only worthwhile when this yields a benefit), even poor individual cues can shine in combination with other predictors. + ### Visualizing FFTs and their performance To visualize the tree from an `FFTrees` object, use `plot()`.