Merge pull request #188 from hneth/master

Rename global options and make tree definition functions available to users

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: FFTrees
 Type: Package
 Title: Generate, Visualise, and Evaluate Fast-and-Frugal Decision Trees
-Version: 1.9.0.9022
-Date: 2023-03-22
+Version: 1.9.0.9024
+Date: 2023-03-24
 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")),

NAMESPACE

@@ -6,6 +6,7 @@ S3method(print,FFTrees)
 S3method(summary,FFTrees)
 export(FFTrees)
 export(FFTrees.guide)
+export(add_fft_df)
 export(fftrees_apply)
 export(fftrees_create)
 export(fftrees_cuerank)
@@ -18,7 +19,9 @@ export(get_best_tree)
 export(get_exit_type)
 export(get_fft_df)
 export(inwords)
+export(read_fft_df)
 export(showcues)
+export(write_fft_df)
 import(testthat)
 importFrom(caret,confusionMatrix)
 importFrom(cli,cli_progress_bar)

R/util_abc.R

@@ -450,17 +450,26 @@ get_exit_word <- function(data){
 #' of an \code{FFTrees} object \code{x}
 #' (as a \code{data.frame}).
 #'
+#' The FFTs in the \code{data.frame} returned
+#' are represented in the one-line per FFT definition format
+#' used by an \code{FFTrees} object.
+#'
 #' In addition to looking up \code{x$trees$definitions},
 #' \code{get_fft_df} verifies that the FFT definitions
 #' are valid (given current settings).
 #'
 #' @param x An \code{FFTrees} object.
 #'
-#' @return A set of FFT definitions (as a \code{data.frame}/\code{tibble}).
+#' @return A set of FFT definitions (as a \code{data.frame}/\code{tibble},
+#' in the one-line per FFT definition format used by an \code{FFTrees} object).
 #'
 #' @family utility functions
+#' @family tree definition and conversion functions
 #'
 #' @seealso
+#' \code{\link{read_fft_df}} for reading one FFT definition from tree definitions;
+#' \code{\link{write_fft_df}} for writing one FFT to tree definitions;
+#' \code{\link{add_fft_df}} for adding FFTs to tree definitions;
 #' \code{\link{FFTrees}} for creating FFTs from and applying them to data.
 #'
 #' @export

R/util_const.R

@@ -121,6 +121,7 @@ exit_types <- c(0, 1, 0.5)  # (global constant)
 stopping_rules <- c("exemplars", "levels", "statdelta")  # (global constant)
 
 
+
 # Handling NA values: ------
 
 
@@ -140,6 +141,16 @@ allow_NA_crit <- FALSE  # (global constant)
 
 
 
+# - replace_NA_num_pred: ----
+
+# Replace NA values in numeric predictors (by mean of predictor)?
+# - TRUE replaces NA in numeric predictors by their mean;
+# - FALSE keeps (but handles them later)
+
+replace_NA_num_pred <- TRUE  # (global constant)
+
+
+
 # - fin_NA_options: ----
 
 # Options for dealing with NA values in final nodes / leaf cues:

R/util_data.R

@@ -313,9 +313,7 @@ handle_NA_data <- function(data, criterion_name, mydata, quiet){
     # Keep NA values in numeric predictors (but remove in classtable() of 'util_stats.R').
     # +++ here now +++ : OR: Allow to replace NA-values in numeric predictors by mean/median?
 
-    replace_num_NA <- TRUE  # TRUE replaces NA in numeric predictors by their mean / FALSE keeps (but handles them later)
-
-    if (replace_num_NA){
+    if (replace_NA_num_pred){ # use global constant:
 
       # Replace NAs in numeric predictors:
       data[ix_pred_num_NA] <- replace_NA_num(df = data[ix_pred_num_NA])
@@ -359,6 +357,7 @@ handle_NA_data <- function(data, criterion_name, mydata, quiet){
 } # handle_NA_data().
 
 
+
 # replace_NA_vec: ------
 
 # Goal: Replace NA-values in a vector by mean() of existing values.
@@ -369,7 +368,9 @@ replace_NA_vec <- function(v){
   # by data type:
   if (is.numeric(v)){
 
-    v[is.na(v)] <- mean(v, na.rm = TRUE)
+    v[is.na(v)] <- mean(v, na.rm = TRUE)  # replace NA values by mean
+
+    # v[is.na(v)] <- median(v, na.rm = TRUE)  # replace NA values by median
 
   } else {
 

R/util_gfft.R

@@ -22,8 +22,8 @@
 # Details:
 #
 # 2 FFT translation functions:
-# - read: From multi-FFT df (with 1 row per tree) to 1 FFT df (in "tidy" format: with 1 row per node),
-# - write: back from to 1 FFT df (with 1 row per node) to multi-tree df (with 1 row per tree).
+# - read_fft_df: From multi-FFT df (with 1 row per tree) to 1 FFT df (in "tidy" format: with 1 row per node),
+# - write_fft_df: Back from to 1 FFT df (with 1 row per node) to multi-tree df (with 1 row per tree).
 #
 # 1 FFT collection function:
 # - add_fft_df: Adds definitions (as df) of individual FFTs (as df) to (a set of existing) definitions.
@@ -46,7 +46,7 @@
 # This creates a "tidy" representation of 1 FFT.
 #
 # Inputs:
-# ffts_df: A set of FFT definitions (as df, usually from an FFTrees object,
+# : A set of FFT definitions (as df, usually from an FFTrees object,
 #       with suitable variable names to pass verify_ffts_df()).
 # tree: A tree ID (corresponding to tree in ffts_df).
 #
@@ -57,6 +57,39 @@
 # - fftrees_ffttowords()
 
 
+#' Read an FFT definition from tree definitions
+#'
+#' @description \code{read_fft_df} reads and returns
+#' the definition of a single FFT (as a tidy data frame)
+#' from the multi-line FFT definitions of an \code{FFTrees} object.
+#'
+#' \code{read_fft_df} allows reading individual tree definitions
+#' to manipulate them with other tree trimming functions.
+#'
+#' \code{\link{write_fft_df}} provides the inverse functionality.
+#'
+#' @param ffts_df A set of FFT definitions (as a data frame,
+#' usually from an \code{FFTrees} object,
+#' with suitable variable names to pass \code{verify_ffts_df}.
+#'
+#' @param tree The ID of the to-be-selected FFT (as an integer),
+#' corresponding to a tree in \code{ffts_df}.
+#' Default: \code{tree = 1}.
+#'
+#' @return A definition of one FFT
+#' (as a data frame in tidy format, with one row per node).
+#'
+#' @family tree definition and conversion functions
+#' @family tree trimming functions
+#'
+#' @seealso
+#' \code{\link{get_fft_df}} for getting the FFT definitions of an \code{FFTrees} object;
+#' \code{\link{write_fft_df}} for writing one FFT to tree definitions;
+#' \code{\link{add_fft_df}} for adding FFTs to tree definitions;
+#' \code{\link{FFTrees}} for creating FFTs from and applying them to data.
+#'
+#' @export
+
 read_fft_df <- function(ffts_df, tree = 1){
 
   # Prepare: ----
@@ -147,9 +180,42 @@ read_fft_df <- function(ffts_df, tree = 1){
 # Output: FFT definition in 1 line (as non-tidy df).
 #
 # Note: Code is currently used at the end of
-# - fftrees_grow_fan()         +++ here now +++
-# - fftrees_wordstofftrees()   +++ here now +++
-
+# - fftrees_grow_fan()
+# - fftrees_wordstofftrees()
+
+
+#' Write an FFT definition to tree definitions
+#'
+#' @description \code{write_fft_df} writes
+#' the definition of a single FFT (as a tidy data frame)
+#' into the one-line FFT definition used by an \code{FFTrees} object.
+#'
+#' \code{write_fft_df} allows turning individual tree definitions
+#' into the one-line FFT definition format
+#' used by an \code{FFTrees} object.
+#'
+#' \code{\link{read_fft_df}} provides the inverse functionality.
+#'
+#' @param fft A definition of one FFT
+#' (as a data frame in tidy format, with one row per node).
+#'
+#' @param tree The ID of the to-be-written FFT (as an integer).
+#' Default: \code{tree = -99L}.
+#'
+#' @return An FFT definition in the one line
+#' FFT definition format used by an \code{FFTrees} object
+#' (as a data frame).
+#'
+#' @family tree definition and conversion functions
+#' @family tree trimming functions
+#'
+#' @seealso
+#' \code{\link{get_fft_df}} for getting the FFT definitions of an \code{FFTrees} object;
+#' \code{\link{read_fft_df}} for reading one FFT definition from tree definitions;
+#' \code{\link{add_fft_df}} for adding FFTs to tree definitions;
+#' \code{\link{FFTrees}} for creating FFTs from and applying them to data.
+#'
+#' @export
 
 write_fft_df <- function(fft, tree = -99L){
 
@@ -232,6 +298,44 @@ write_fft_df <- function(fft, tree = -99L){
 # Output: Verified tree definitions of x$trees$definitions (as 1 df); else NA.
 
 
+#' Add an FFT definition to tree definitions
+#'
+#' @description \code{add_fft_df} adds the definition(s) of
+#' one or more FFT(s) (in the multi-line format of an \code{FFTrees} object)
+#' or a single FFT (as a tidy data frame)
+#' to the multi-line FFT definitions of an \code{FFTrees} object.
+#'
+#' \code{add_fft_df} allows for collecting and combining
+#' (sets of) tree definitions after
+#' manipulating them with other tree trimming functions.
+#'
+#' @param fft A (set of) FFT definition(s)
+#' (in the multi-line format of an \code{FFTrees} object)
+#' or one FFT (as a data frame in tidy format, with one row per node).
+#'
+#' @param ffts_df A set of FFT definitions (as a data frame,
+#' usually from an \code{FFTrees} object,
+#' with suitable variable names to pass \code{verify_ffts_df}.
+#' Default: \code{ffts_df = NULL}.
+#'
+#' @param quiet Hide feedback messages (as logical)?
+#' Default: \code{quiet = FALSE}.
+#'
+#' @return A (set of) FFT definition(s) in the one line
+#' FFT definition format used by an \code{FFTrees} object
+#' (as a data frame).
+#'
+#' @family tree definition and conversion functions
+#' @family tree trimming functions
+#'
+#' @seealso
+#' \code{\link{get_fft_df}} for getting the FFT definitions of an \code{FFTrees} object;
+#' \code{\link{read_fft_df}} for reading one FFT definition from tree definitions;
+#' \code{\link{write_fft_df}} for writing one FFT to tree definitions;
+#' \code{\link{FFTrees}} for creating FFTs from and applying them to data.
+#'
+#' @export
+
 add_fft_df <- function(fft, ffts_df = NULL, quiet = FALSE){
 
   if (verify_ffts_df(fft)){   # Case 1: fft is a (set of) FFT-definitions (in 1 row per tree, as df) ----
@@ -301,7 +405,6 @@ add_fft_df <- function(fft, ffts_df = NULL, quiet = FALSE){
 
 # add_nodes: ------
 
-
 # Goal: Add some node(s) (or cues) to a given FFT.
 #
 # Inputs:
@@ -324,11 +427,16 @@ add_fft_df <- function(fft, ffts_df = NULL, quiet = FALSE){
 # 4. If nodes contain a new exit, it needs to have a valid final type (i.e., exit_types[3]).
 #    The exit of the former exit is re-set to signal (i.e., exit_types[2]).
 
-
 add_nodes <- function(fft,
                       nodes = NA,  # as vector (1 integer or multiple nodes)
-                      class = NA, cue = NA, direction = NA, threshold = NA, exit = NA,  # variables of fft nodes (as df rows)
+                      class = NA,  # variables of fft nodes (as df rows)
+                      cue = NA,
+                      direction = NA,
+                      threshold = NA,
+                      exit = NA,
+                      #
                       my.node = NA,
+                      #
                       quiet = FALSE){
 
   # Prepare: ----

README.Rmd

@@ -40,6 +40,7 @@ url_JDM_doi <- "https://doi.org/10.1017/S1930297500006239"
 [![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)
 <!-- Devel badges end. -->
 
+
 <!-- Release badges start: -->
 <!-- [![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) -->

README.md

@@ -2,7 +2,7 @@
 <!-- README.md is generated from README.Rmd. Please only edit the .Rmd file! -->
 <!-- Title, version and logo: -->
 
-# FFTrees 1.9.0.9022 <img src = "./inst/FFTrees_Logo.jpg" align = "right" alt = "FFTrees" width = "225" />
+# FFTrees 1.9.0.9024 <img src = "./inst/FFTrees_Logo.jpg" align = "right" alt = "FFTrees" width = "225" />
 
 <!-- Devel badges start: -->
 
@@ -333,6 +333,6 @@ Examples include:
 
 ------------------------------------------------------------------------
 
-\[File `README.Rmd` last updated on 2023-03-22.\]
+\[File `README.Rmd` last updated on 2023-03-24.\]
 
 <!-- eof. -->