Skip to contents

Builds a YARF Model. There are many customizations available.

Source: R/YARF_builders.R
YARF.Rd

Builds a YARF Model. There are many customizations available.

Usage

YARF(
  X = NULL,
  y = NULL,
  Xy = NULL,
  Xother = NULL,
  allow_missingness_in_y = FALSE,
  num_trees = NULL,
  bootstrap_indices = NULL,
  n_max_per_tree = 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,
  no_missing_data_split_rule = "RANDOM",
  serialize = FALSE,
  seed = NULL,
  wait = TRUE,
  calculate_oob_error = TRUE,
  fit_until_convergence = FALSE,
  oob_cost_calculation_script = NULL,
  tolerance = 0.01,
  verbose = TRUE,
  debug_log = FALSE
)

Arguments

X

The data frame of training data

y

The vector of training responses which is either numeric (for regression or factor (for classification).

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 the missings are not handled (somehow) in the custom functions, YARF will crash!! Default is FALSE.

num_trees

The number of trees in the RF. Default is NULL which sets the value to 500 if fit_until_convergence is set to FALSE and 10,000 if fit_until_convergence is set to TRUE.

If the model is fit asynchronously via the wait parameter being set to TRUE, this number represents a vague contract between the user and the software as the model fitting can be (a) halted by the user or the model can be (b) set to converge automatically (by setting the fit_until_convergence parameter to TRUE). In the latter case, this parameter functions as the maximum number of trees that can be created and thus, it is recommended that this number is very large, hence the default of 10,000.

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. If this parameter is specified, there is no need to specify n_max_per_tree.

n_max_per_tree

An upper limit on the number of observations used to build each tree. If this parameter is specified, there is no need to specify bootstrap_indices. Default is NULL for the entire dataset, n.

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 to use all possible features, set this parameter to "all". 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.

no_missing_data_split_rule

What rule should be used for missing data seen in testing for nodes that did not see missing data in training? Choices: "RANDOM" and "CONDITIONAL_ON_QUANTILE". "RANDOM" will assign a split rule for missing data at such nodes purely arbitrarily and with equal probability, i.e. 50 will condition this probability on the quantile of the split value amongst the observed (non-missing) data. For example, if the split value lies at the 75th percentile, then with probability .75, this node's rule for missing data will be to go left, and with probability .25 to go right. Note that for either of these options, the randomization happens at training time and thus during prediction the rule will be deterministic. The default is "RANDOM".

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.

wait

Should we hang R to wait for the YARF model to complete? The default is TRUE.

calculate_oob_error

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

fit_until_convergence

Default is FALSE. If TRUE, then the wait parameter is set to FALSE regardless of the user-specified value. Then, the Random Forest model is fit until "convergence" as defined below:

After each tree is completed, the OOB cost is computed. If the cost decreases the algorithm does not engage. However, upon the first increase in cost, the model checks for convergence by calculating the average change in cost and the standard deviation of change in cost. If a 95% confidence interval of the average cost is within the window created by plus or minus tolerance (i.e. from zero), then the algorithm has "converged". Upon convergence, the model is stopped and a message is printed to the console. Note that specification of the oob_cost_calculation_script and a proper tolerance level is essential.

It is strongly recommended to set the num_trees parameter large, otherwise the model can halt before it has converged since num_trees represents an upper limit. If left unspecified, num_trees is set to 10,000 when fit_until_convergence set to TRUE.

If the user wishes to view the convergence in real time, we recommend the YARF_progress function. However, this function will lock the console.

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.

tolerance

This parameter is ignored unless fit_until_convergence is set to TRUE. If so, this controls the tolerance used when assessing the convergence of the RF model. Default is 0.1. If oob_cost_calculation_script is specified, this should also be specified as 0.1 may not be appropriate for a custom oob cost function.

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