Merge pull request #198 from hneth/master

Preparing CRAN release

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: FFTrees
 Type: Package
 Title: Generate, Visualise, and Evaluate Fast-and-Frugal Decision Trees
-Version: 1.9.0.9032
-Date: 2023-06-01
+Version: 2.0.0
+Date: 2023-06-06
 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")),

NEWS.md

@@ -1,16 +1,9 @@
 
-# Upcoming release {-}
+# FFTrees 2.0
 
-Please note:
+## 2.0.0
 
-- **FFTrees** version 2.0.0 will be released in **June 2023**.
-
-
-# FFTrees 1.9
-
-## 1.9.0.9031
-
-This is the current development version of **FFTrees**, available at <https://github.com/ndphillips/FFTrees>.
+**FFTrees** version 2.0.0 was released [on CRAN](https://CRAN.R-project.org/package=FFTrees) [on 2023-06-06]. 
 
 <!-- Log of changes: --> 
 
@@ -22,41 +15,43 @@ Changes since last release:
 
 ### Major changes 
 
-<!-- gfft: Manipulating FFTs --> 
+<!-- gfft: Converting and manipulating FFTs --> 
 
-- Enabled conversions between tree definition formats and manipulating individual FFTs:
+- Enabled conversions between tree definition formats and manipulating FFT definitions:
     - tree definition and conversion functions: `get_fft_df`, `read_fft_df`, `write_fft_df`, `add_fft_df` 
     - tree trimming functions: `add_nodes`, `drop_nodes`, `edit_nodes`, `flip_exits`, `reorder_nodes`, `select_nodes`
 
 
-<!-- NA handling: --> 
+<!-- Growing FFTs: Stopping rules: --> 
 
-- Allowing for missing inputs (`NA` values) in data:
-    - `NA` values in categorical (i.e., character/factor/logical) predictors are treated as `<NA>` factor levels. 
-    - `NA` values in numeric predictors are either _imputed_ (as the mean of the corresponding predictor) or 
-    _ignored_ when creating and using FFTs to decide/predict (if possible). 
-    - `NA` values in the criterion variable are yet to be dealt with.  
-
+- Growing FFTs: 
+   - enabled `stopping.rule = "statdelta"` 
+   - fixed a bug in `fftrees_grow_fan()` that prevented `ifan` algorithm from stopping 
+   when finding a perfect FFT (given the current `goal.chase` parameter)  
 
-<!-- Stopping rule: --> 
 
-- Growing FFTs:
-   - enabled `stopping.rule = "statdelta"`. 
-   - fixed a bug in `fftrees_grow_fan()` that prevented `ifan` algorithm from stopping when finding a perfect FFT (given the current `goal.chase` parameter). 
+<!-- NA handling: --> 
 
+- Handling missing inputs (`NA` values) in data:
+    - `NA` values in categorical (i.e., character/factor/logical) predictors are treated as `<NA>` factor levels  
+    - `NA` values in numeric predictors are either _ignored_ (by default) or 
+    _imputed_ (as the mean of the corresponding predictor) when creating and using FFTs to decide/predict (if possible) 
+    - `NA` values in the criterion variable are yet to be dealt with 
+
 
 <!-- Minor: --> 
 
 ### Minor changes 
 
 - Added utility functions (and corresponding verification functions): 
-    - `get_best_tree()` retrieves the ID of the best tree in an `FFTrees` object (given `goal`).
-    - `get_exit_type()` converts a vector of exit descriptions into FFT exits (given `exit_types`).
-    - `get_fft_df()` retrieves the tree definitions of an `FFTrees` object.  
+    - `get_best_tree()` retrieves the ID of the best tree in an `FFTrees` object (given `goal`) 
+    - `get_exit_type()` converts a vector of exit descriptions into FFT exits (given `exit_types`) 
+    - `get_fft_df()` retrieves the tree definitions of an `FFTrees` object 
 
-- Added detailed cost information when printing FFTs (with `print.FFTrees()`). 
-- Improved user feedback (by making `quiet` a list with four distinct options). 
+- Added cost information when printing FFTs (with `print.FFTrees()`). 
+- Improved user feedback (by making `quiet` a list with four options). 
 - Increased vocabulary for interpreting verbal FFT descriptions (using `my.tree`). 
+- Improved documentation of included data (e.g., in `FFTrees.guide()`). 
 
 
 <!-- Details: --> 
@@ -74,11 +69,12 @@ Changes since last release:
 
 The current development version of **FFTrees** is available at <https://github.com/ndphillips/FFTrees>. 
 
-
-<!-- Released versions: --> 
+<!-- Older versions: --> 
 
 ------ 
 
+# FFTrees 1.9
+
 ## 1.9.0
 
 **FFTrees** version 1.9.0 was released [on CRAN](https://CRAN.R-project.org/package=FFTrees) [on 2023-02-08]. 
@@ -480,6 +476,6 @@ Thus, the main tree building function is now `FFTrees()` and the new tree object
 
 ------ 
 
-[File `NEWS.md` last updated on 2023-05-31.]
+[File `NEWS.md` last updated on 2023-06-06.]
 
 <!-- eof. -->

R/util_abc.R

@@ -9,7 +9,7 @@
 # (A) Applying or computing stuff: ------
 
 
-# apply_break: ------
+# - apply_break: ------
 
 # Takes a direction, threshold value, and cue vector, and returns a vector of decisions.
 
@@ -64,7 +64,7 @@ apply_break <- function(direction,
 
 
 
-# fact_clean: ------
+# - fact_clean: ------
 
 #' Clean factor variables in prediction data
 #'
@@ -127,7 +127,7 @@ fact_clean <- function(data.train,
 # (B) Enabling stuff: ------
 
 
-# enable_wacc: ------
+# - enable_wacc: ------
 
 # Test whether wacc makes sense (iff sens.w differs from its default of 0.50).
 
@@ -154,7 +154,7 @@ enable_wacc <- function(sens.w, sens.w_epsilon = 10^-4){
 # (C) Getting stuff: ------
 
 
-# get_bacc_wacc: ------
+# - get_bacc_wacc: ------
 
 # Obtain either bacc or wacc (for displays in print and plot functions).
 # Output: Named vector (with name specifying the current type of measure).
@@ -184,7 +184,7 @@ get_bacc_wacc <- function(sens, spec,  sens.w){
 
 
 
-# get_best_tree: ------
+# - get_best_tree: ------
 
 #' Select the best tree (from current set of FFTs)
 #'
@@ -328,7 +328,7 @@ get_best_tree <- function(x,
 
 
 
-# get_exit_type: ------
+# - get_exit_type: ------
 
 # Goal: Convert/get various exit type descriptions (from a vector x)
 #       given current exit_types (given by global constant).
@@ -425,7 +425,7 @@ get_exit_type <- function(x, verify = TRUE){
 
 
 
-# get_exit_word: ------
+# - get_exit_word: ------
 
 # Goal: Get "Decide" for 'train' data vs. "Predict" for 'test' data.
 
@@ -438,7 +438,7 @@ get_exit_word <- function(data){
 
 
 
-# get_fft_df: ------
+# - get_fft_df: ------
 
 # Goal: Extract (and verify) ALL definitions from an FFTrees object (as 1 df).
 # Output: Verified tree definitions of x$trees$definitions (as 1 df); else NA.
@@ -465,7 +465,6 @@ get_exit_word <- function(data){
 #'
 #' @family utility functions
 #' @family tree definition and manipulation functions
-#' @family tree selection, conversion, and collection functions
 #'
 #' @seealso
 #' \code{\link{read_fft_df}} for reading one FFT definition from tree definitions;
@@ -498,7 +497,7 @@ get_fft_df <- function(x){
 
 
 
-# get_lhs_formula: ------
+# - get_lhs_formula: ------
 
 # Goal: Get the (name of the) criterion variable from (LHS of) a formula (and verify formula).
 
@@ -523,7 +522,7 @@ get_lhs_formula <- function(formula){
 # (D) Handling strings or quotes: ------
 
 
-# add_quotes: ------
+# - add_quotes: ------
 
 add_quotes <- function(x) {
 
@@ -537,7 +536,7 @@ add_quotes <- function(x) {
 # (E) Combinatorics: Number of combinations and permutations: --------
 
 
-# all_permutations: List all permutations of a vector/set x / permute a set/vector x: ------
+# - all_permutations: List all permutations of a vector/set x / permute a set/vector x: ------
 
 # See also: library(combinat)
 # set <- c("a", "b", "c")
@@ -576,7 +575,7 @@ all_permutations <- function(x) {
 # all_permutations(c("A", "B", "b", "a"))
 
 
-# all_combinations: List all combinations of a length n of a set x: ------
+# - all_combinations: List all combinations of a length n of a set x: ------
 
 # # (a) Using utils::combn:
 # m <- utils::combn(x = 1:4, m = 2)
@@ -635,7 +634,7 @@ all_combinations <- function(x, length){
 
 
 
-# all_subsets: List all combinations of all sub-lengths 0 < n < length(x) of a set x: ------
+# - all_subsets: List all combinations of all sub-lengths 0 < n < length(x) of a set x: ------
 
 # Goal: Get all subsets of x (i.e., all possible combinations of all possible lengths 0 < n < length(x)).
 #       Note: The extreme NULL (an empty set) is NOT, but the full set (all of x) can be included/returned.
@@ -702,16 +701,15 @@ all_subsets <- function(x, include_x = TRUE){
 NULL
 
 
-# R version check: ------
+# - R version check: ------
 
 ## quiets concerns of R CMD check re: the .'s that appear in pipelines:
 if (getRversion() >= "2.15.1") utils::globalVariables(c(".", "tree", "tree_new", "tree", "level"))
 
 
 
-
 # ToDo: ------
 
-# - Get all_subsets() based on all_combinations().
+# - Get all_subsets() based on all_combinations()?
 
 # eof.

R/util_const.R

@@ -34,7 +34,7 @@ cost_outcomes_default <- list(hi = 0, fa = 1, mi = 1, cr = 0)  # (global constan
 # - cost_cues_default: ----
 
 # Cue cost = graded mcu / "graded frugality":
-# Note: A value of 1 for all cues in data corresponds to mcu.
+# Note: A value of 1 (for all cues in data) corresponds to mcu.
 
 cost_cues_default <- 0  # (global constant)
 
@@ -129,7 +129,7 @@ stopping_rules <- c("exemplars", "levels", "statdelta")  # (global constant)
 
 # Allow NA cases in predictors (as logical)?
 
-allow_NA_pred <- TRUE # FALSE  # (global constant)
+allow_NA_pred <- TRUE  # (global constant)
 
 
 
@@ -144,10 +144,10 @@ 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)
+# - TRUE replaces NA in numeric predictors (currently by their mean);
+# - FALSE (by default) keeps NA values (but tries handling them later)
 
-replace_NA_num_pred <- TRUE  # (global constant)
+replace_NA_num_pred <- FALSE  # (global constant)