A convenience method to build a CART model via YARF. There are many customizations available.

Usage

YARFCART(
  X = NULL,
  y = NULL,
  Xy = NULL,
  Xother = NULL,
  allow_missingness_in_y = FALSE,
  bootstrap_indices = NULL,
  other_indices = NULL,
  mtry = NULL,
  nodesize = NULL,
  mtry_script = NULL,
  split_vals_script = NULL,
  make_node_to_leaf_script = NULL,
  cost_single_node_calc_script = NULL,
  cost_both_children_calc_script = NULL,
  node_assign_script = NULL,
  after_node_birth_function_script = NULL,
  shared_scripts = NULL,
  use_missing_data = TRUE,
  replace_missing_data_with_x_j_bar = FALSE,
  serialize = FALSE,
  seed = NULL,
  calculate_oob_error = TRUE,
  oob_cost_calculation_script = NULL,
  verbose = TRUE,
  debug_log = FALSE
)

Arguments

X

The data frame of training data

y

The vector of training responses

Xy

The data frame of training data where the last column is responses

Xother

Other data that is used in the training but the RF doesn't split on it

allow_missingness_in_y

If TRUE, missingness in the response variable, y, is allowed. If this is not handled in the custom functions, YARF will crash. Default is FALSE.

bootstrap_indices

A list with keys 1, 2, ..., num_trees where each value is the indices of the training data you wish to use for each tree. The default is NULL indicating the default algorithm of sampling 1, ..., n with replacement (i.e. the non-parametric bootstrap default). Needless to say indices specified here will not be part of the out-of-bag collection of indices. You may specify more than enough (i.e. more than num_trees) elements in this list. Only the first num_trees will be used. No warning message will be displayed if you include too many.

other_indices

An optional list with keys 1,2,..., num_trees where each value is indices of the training data you wish to use in some custom way for each tree using a custom function. If not custom function is specified which makes use of this, it will be ignored. However, indices specified here will not be part of the out-of-bag collection of indices. If this is not your wish, the elements in the vectors specified in this list's values should be a subset of those in the values of bootstrap_indices. The default is NULL indicating you do not wish to specify any "other" data records.

mtry

The number of variables tried at every split. The default is NULL which indicates the out-of-box RF default which is floor(p / 3) for regression and floor(sqrt(p)) for classification. If you want a custom function, leave this NULL and see next parameter.

nodesize

The minimum number of observations in a node. YARF will stop splitting at this point. If NULL the out-of-the-box default of 5 for regression and 1 for classification will be used.

mtry_script

A custom javascript function which selects the variables to be greedily searched (see below) The default is NULL which employs the mtry argument. If you specify your function please randomize the order of the returned attributes to arbitrate ties.

function tryVars(node){ //node is of type YARF.YARFNode

...

return int_array //a subset of 0,...,p-1, indices indicating the variables to perform the exhaustive search on

}

split_vals_script

A custom javascript function which selects the split values to be greedily searched in feature j. The default is NULL which employs the midpoints of all sorted values.

function tryVals(node, j){ //node is of type YARF.YARFNode and j is the feature number in 0,...,p-1

...

return double_array //a vector of split vals to greedily assess

}

make_node_to_leaf_script

A custom javascript function to be used to calculate nodesize (see below). The default is NULL where nodesize will be calculated as a static constant (see the nodesize argument).

function makeNodeIntoLeaf(node){ //node is of type YARF.YARFNode

...

return boolean //where true makes this node into a leaf

}

cost_single_node_calc_script

A custom cost calculation for a potential node (when considering a split) in Javascript (see below). The default is NULL which means the out-of-the-box default of sum of squared error relative to the sample average (if regression) and sum of entropy (if classification). You may find it convenient to also made a node assignment here. If so, make sure you specify the node assignment function as a blank function (not NULL).

function nodeCost(node){ //node is of type YARF.YARFNode

...

return double //where a higher number indicates a higher cost

}

cost_both_children_calc_script

A custom cost calculation in Javascript for an entire split considering both the putative left and right children nodes (see below). The default is NULL which means the out-of-the-box default for Random Forests which is sum of left and right nodes' costs for regression and average of left and right nodes' cost (relative to the number of observations in each node).

function totalChildrenCost(leftNode, rightNode){ //both nodes are of type YARF.YARFNode

...

return double //where a higher number indicates a higher cost

}

node_assign_script

A custom node assignment function in Javascript (see below). This function is run after RF greedily finds the "lowest cost" split. The default is NULL corresponding to the sample average of the node responses in regression or the modal class during classification.

function assignYhatToNode(node){ //node is of type YARF.YARFNode

...

return double //assigned as this node's predicted value ("y_hat")

}

after_node_birth_function_script

A custom function in Javascript which is executed after a node is given birth to. The default is NULL which implies nothing special is done, the Random Forest default. This is particularly useful to record extra information in the node (e.g. by writing a hash to the other_info field in the node).

function nodeAfterNodeBirth(node){ //node is of type YARF.YARFNode

...

}

shared_scripts

Custom Javascript code that are always in scope when running all your custom methods. The default is NULL for no shared scripts.

use_missing_data

Use the "missing-incorporated-in-attributes" strategy to fit data with missingness. The default is TRUE.

replace_missing_data_with_x_j_bar

Replace missing predictor values with their training-column means before fitting.

serialize

Should the YARF model be saved? The default is FALSE as this is costly in processing time and memory. This can only be set to TRUE if wait = TRUE. If TRUE, we will automatically serialize after other operations that add data (such as the OOB evaluation).

seed

Set a random seed for reproducibility.

calculate_oob_error

Should we also calculate the OOB error? Default is TRUE. Automatically is turned off if wait becomes FALSE.

oob_cost_calculation_script

This parameter will determine the out-of-bag cost of the RF forest model. Default is NULL. If it is NULL, then the cost will be 1-R^2 for regression models and misclassification error for classification models.

If non-null, an optional custom Javascript function which calculates the cost of a prediction given the true value of the prediction (see below). If is likely similar to cost_single_node_calc_script. It is recommended to share code between them by writing a function included in the shared_scripts argument which can be referenced when calculating OOB results.

function oobCost(y_hat, y){ //y_hat is the predicted value and y is the true value (both are of type double)

...

return double //where a larger number indicates a higher cost to the error between y and y_hat.

}

If this script is specified (i.e. the argument is non-NULL), this will also affect the output of the YARF_update_with_oob_results function. This script can be reset after the model is built if necessary.

verbose

Should we print out messages verbosely during construction? Default is FALSE.

debug_log

Should we print out messages from Java? Default is FALSE.

Value

A list that (a) reiterates all ob the above arguments passed in and (b) pred_type is the guess as to modeling type: regression or classification (c) java_YARF is the Java object (d) y_levels is the unique values of the response variable (e) model_matrix_training_data is the data matrix with factor variables converted to dummies that is fed into YARF as the X variables (f) training_data_features is the names of the features (g) predictors_which_are_factors is a list of the variables that are factors and (h) n and p which are the dimensions of the training data model matrix and (i) various other convenient data and internal data of use to other functions in this package.

Author

Adam Kapelner