API Reference

Abstract type encompassing all tree-based learners.

Abstract type encompassing all tree-based learners with classification leaves.

Abstract type encompassing all tree-based learners with regression leaves.

Abstract type encompassing all tree-based learners with survival leaves.

Abstract type encompassing all tree-based learners with prescription leaves.

Abstract type encompassing all tree-based learners with policy leaves.

get_num_nodes(lnr::TreeLearner)

Return the number of nodes in the trained lnr.

Example

IAI.get_num_nodes(lnr)

7

is_leaf(lnr::TreeLearner, node_index::Int)

Return true if node node_index in the trained lnr is a leaf.

Example

IAI.is_leaf(lnr, 1)

false

get_depth(lnr::TreeLearner, node_index::Int)

Return the depth of node node_index in the trained lnr.

Example

IAI.get_depth(lnr, 6)

2

get_num_samples(lnr::TreeLearner, node_index::Int)

Return the number of training points contained in node node_index in the trained lnr.

Example

IAI.get_num_samples(lnr, 6)

72

get_parent(lnr::TreeLearner, node_index::Int)

Return the index of the parent of node node_index in the trained lnr.

Example

IAI.get_parent(lnr, 2)

1

get_lower_child(lnr::TreeLearner, node_index::Int)

Return the index of the lower child of node node_index in the trained lnr.

Example

IAI.get_lower_child(lnr, 1)

2

get_upper_child(lnr::TreeLearner, node_index::Int)

Return the index of the upper child of node node_index in the trained lnr.

Example

IAI.get_upper_child(lnr, 1)

5

is_parallel_split(lnr::TreeLearner, node_index::Int)

Return true if node node_index in the trained lnr is a parallel split.

Example

IAI.is_parallel_split(lnr, 1)

true

is_hyperplane_split(lnr::TreeLearner, node_index::Int)

Return true if node node_index in the trained lnr is a hyperplane split.

Example

IAI.is_hyperplane_split(lnr, 2)

true

is_categoric_split(lnr::TreeLearner, node_index::Int)

Return true if node node_index in the trained lnr is a categoric split.

Example

IAI.is_categoric_split(lnr, 5)

true

is_ordinal_split(lnr::TreeLearner, node_index::Int)

Return true if node node_index in the trained lnr is an ordinal split.

Example

IAI.is_ordinal_split(lnr, 1)

false

is_mixed_parallel_split(lnr::TreeLearner, node_index::Int)

Return true if node node_index in the trained lnr is a mixed categoric/parallel split.

Example

IAI.is_mixed_parallel_split(lnr, 2)

false

is_mixed_ordinal_split(lnr::TreeLearner, node_index::Int)

Return true if node node_index in the trained lnr is a mixed categoric/ordinal split.

Example

IAI.is_mixed_ordinal_split(lnr, 5)

false

missing_goes_lower(lnr::TreeLearner, node_index::Int)

Return true if missing values take the lower branch at node node_index in the trained lnr.

Applies to non-leaf nodes.

Example

IAI.missing_goes_lower(lnr, 1)

false

get_split_feature(lnr::TreeLearner, node_index::Int)

Return the feature used in the split at node node_index in the trained lnr.

Applies to categoric, ordinal, parallel, categoric/ordinal, and categoric/parallel splits.

Example

IAI.get_split_feature(lnr, 1)

:score1

get_split_threshold(lnr::TreeLearner, node_index::Int)

Return the threshold used in the split at node node_index in the trained lnr.

Applies to hyperplane, parallel, and categoric/parallel splits.

Example

IAI.get_split_threshold(lnr, 1)

59.980015

get_split_categories(lnr::TreeLearner, node_index::Int)

Return a Dict containing the categoric/ordinal information used in the split at node node_index in the trained lnr, where the keys are the levels used in the split and the values are true if that level follows the lower branch and false if that level follows the upper branch.

Applies to categoric, ordinal, categoric/ordinal, and categoric/parallel splits.

Example

IAI.get_split_categories(lnr, 5)

Dict{Any,Bool} with 5 entries:
  "B" => true
  "A" => true
  "C" => false
  "D" => false
  "E" => false

get_split_weights(lnr::TreeLearner, node_index::Int)

Return two Dicts containing the weights for numeric and categoric features, respectively, used in the hyperplane split at node node_index in the trained lnr.

The numeric Dict has key-value pairs of feature names and their corresponding weights in the hyperplane split.

The categoric Dict has key-value pairs of feature names and a corresponding Dict that maps the categoric levels for that feature to their weights in the hyperplane.

Any features not included in either Dict has zero weight in the hyperplane, and similarly, any categoric levels that are not included have zero weight.

Applies to hyperplane splits.

Example

numeric_weights, categoric_weights = IAI.get_split_weights(lnr, 2)
numeric_weights

Dict{Symbol,Float64} with 2 entries:
  :score3 => 0.0980674
  :score2 => 0.00123692

categoric_weights

Dict{Symbol,Dict{Any,Float64}} with 1 entry:
  :region => Dict{Any,Float64}("E"=>0.105715)

get_classification_label(lnr::ClassificationTreeLearner, node_index::Int;
                         check_leaf::Bool=true)

Return the predicted label at node node_index in the trained lnr.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

IAI.get_classification_label(lnr, 2)

"setosa"

get_classification_proba(lnr::ClassificationTreeLearner, node_index::Int;
                         check_leaf::Bool=true)

Return the predicted probabilities of class membership at node node_index in the trained lnr.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

IAI.get_classification_proba(lnr, 4)

Dict{String,Float64} with 3 entries:
  "virginica"  => 0.0925926
  "setosa"     => 0.0
  "versicolor" => 0.907407

get_regression_constant(lnr::RegressionTreeLearner, node_index::Int;
                        check_leaf::Bool=true)

Return the constant term in the regression prediction at node node_index in the trained lnr.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

IAI.get_regression_constant(lnr, 2)

30.88

IAI.get_regression_constant(lnr, 3)

30.8876

get_regression_weights(lnr::RegressionTreeLearner, node_index::Int;
                       check_leaf::Bool=true)

Return the weights for each feature in the regression prediction at node node_index in the trained lnr. The weights are returned as two Dicts in the same format as described for get_split_weights.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

numeric_weights, categoric_weights = IAI.get_regression_weights(lnr, 3)
numeric_weights

Dict{Symbol,Float64} with 4 entries:
  :Cyl  => -0.794566
  :WT   => -1.64974
  :Gear => 0.0585196
  :HP   => -0.0126672

categoric_weights

Dict{Symbol,Dict{Any,Float64}} with 0 entries

get_survival_curve(lnr::SurvivalTreeLearner, node_index::Int;
                   check_leaf::Bool=true)

Return the SurvivalCurve fitted at node node_index in the trained lnr.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

IAI.get_survival_curve(lnr, 2)

SurvivalCurve with 22 breakpoints

get_survival_expected_time(lnr::SurvivalTreeLearner, node_index::Int;
                           check_leaf::Bool=true)

Return the predicted expected survival time at node node_index in the trained lnr.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

IAI.get_survival_expected_time(lnr, 2)

22981.390188900004

get_survival_hazard(lnr::SurvivalTreeLearner, node_index::Int;
                    check_leaf::Bool=true)

Return the predicted hazard ratio at node node_index in the trained lnr.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

IAI.get_survival_hazard(lnr, 2)

0.95410407

get_prescription_treatment_rank(lnr::PrescriptionTreeLearner,
                                node_index::Int; check_leaf::Bool=true)

Return a Vector containing the treatments ordered from most effective to least effective at node node_index in the trained lnr.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

IAI.get_prescription_treatment_rank(lnr, 4)

2-element Array{String,1}:
 "A"
 "B"

get_regression_constant(lnr::PrescriptionTreeLearner, node_index::Int,
                       treatment::Any; check_leaf::Bool=true)

Return the constant in the regression prediction for treatment at node node_index in the trained lnr.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

IAI.get_regression_constant(lnr, 4, "A")

20.797052

get_regression_weights(lnr::PrescriptionTreeLearner, node_index::Int,
                       treatment::Any; check_leaf::Bool=true)

Return the weights for each feature in the regression prediction for treatment at node node_index in the trained lnr. The weights are returned as two Dicts in the same format as described for get_split_weights.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

numeric_weights, categoric_weights = IAI.get_regression_weights(lnr, 4, "A")
numeric_weights

Dict{Symbol,Float64} with 1 entry:
  :SystolicBP => -0.189847

categoric_weights

Dict{Symbol,Dict{Any,Float64}} with 0 entries

get_policy_treatment_rank(lnr::PolicyTreeLearner, node_index::Int;
                          check_leaf::Bool=true)

Return a Vector containing the treatments ordered from most effective to least effective at node node_index in the trained lnr.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

IAI.get_policy_treatment_rank(lnr, 3)

3-element Array{String,1}:
 "A"
 "C"
 "B"

get_policy_treatment_outcome(lnr::PolicyTreeLearner, node_index::Int;
                             check_leaf::Bool=true)

Return a DataFrameRow containing the quality of the treatments at node node_index in the trained lnr. These quality estimates are the values used by the model to determine the treatment ranks in get_policy_treatment_rank and are based on aggregate statistics.

Applies to leaf nodes by default, set check_leaf=false to enable retrieving the same information from a split node as though it was a leaf node.

Example

outcome = IAI.get_policy_treatment_outcome(lnr, 3)

DataFrameRow
 Row │ A         B        C
     │ Float64   Float64  Float64
─────┼────────────────────────────
   1 │ 0.827603  1.69834  1.09678

outcome.A

0.82760316

apply(lnr::TreeLearner, X::FeatureInput)

Return a Vector{Int} that contains the leaf index in lnr into which each point in the features X falls.

apply_nodes(lnr::TreeLearner, X::FeatureInput)

Return a Vector with one entry for each node in lnr. The tth element is a Vector{Int} containing the indices of the points from the features X that fall into node t or its children.

decision_path(lnr::TreeLearner, X::FeatureInput)

Return a SparseMatrixCSC{Bool,Int64} where entry (i, j) is true if the ith point in the features X passes through the jth node in lnr.

print_path(lnr::TreeLearner, X::FeatureInput)

Print the decision path for each sample in the features X. The output displays the value of the relevant features for the specified sample and the rules for the path that it takes through the tree.

print_path(lnr::TreeLearner, X::FeatureInput, i::Int)

Print the decision path for the ith sample in the features X.

variable_importance(lnr::TreeLearner; keyword_arguments...)

For tree learners, the importance of each variable is measured as the total decrease in the loss function as a direct result of each split in the trees of lnr that use this variable.

Keyword Arguments

• proportion_to_use::Real: a number between 0 and 1 indicating the proportion of trees to use when calculating importance. The default value is 0.1, indicating that the best 10% of the trees saved in lnr should be used.

set_threshold!(lnr::ClassificationTreeLearner, label::Any, threshold::Real,
               simplify::Bool=false)

For a binary classification problem, update the the predicted labels in the leaves of lnr. After running, a leaf will predict label only if the predicted probability for this label is at least threshold; otherwise, the other label will be predicted.

If simplify is true, the tree will be simplified so that there is no split that has two leaves with the same label prediction as children. This means that if both sides of a split are leaf nodes with the same label prediction, the split will be deleted from the tree and replaced with a single leaf node. This simplification is applied recursively throughout the tree.

Refer to the documentation on setting the threshold for more information.

write_html(f, lnr::TreeLearner; keyword_arguments...)
write_html(f, grid::GridSearch; keyword_arguments...)

Write interactive browser visualization of lnr or grid to f in HTML format.

Keyword Arguments

• show_node_id=true: whether to show the ID label for each node

• data: specify data to be shown in the visualization, should be passed as a Tuple or Vector in the same order as passed to fit!, i.e.:

  • data=(X, y) for classification and regression problems
  • data=(X, deaths, times) for survival problems
  • data=(X, treatments, outcomes) for prescription problems
  • data=(X, rewards) for policy problems

  Refer to the Tree Visualization documentation for more information.

Example

Save tree to mytree.html:

IAI.write_html("mytree.html", lnr)

show_in_browser(lnr::TreeLearner; keyword_arguments...)
show_in_browser(grid::GridSearch; keyword_arguments...)

Show interactive visualization of lnr or grid in default browser.

Supports the same keyword arguments as write_html.

write_questionnaire(f, lnr::TreeLearner; keyword_arguments...)
write_questionnaire(f, grid::GridSearch; keyword_arguments...)

Write interactive questionnaire based on lnr or grid to f in HTML format.

Keyword Arguments

Supports the same keyword arguments as write_html.

Example

Save questionnaire to questions.html:

IAI.write_questionnaire("myquestionnaire.html", lnr)

show_questionnaire(lnr::TreeLearner; keyword_arguments...)
show_questionnaire(grid::GridSearch; keyword_arguments...)

Show interactive questionnaire based on lnr or grid in default browser.

Supports the same keyword arguments as write_questionnaire.

TreePlot(lnr::TreeLearner; keyword_arguments...)

Specifies an interactive tree visualization of lnr.

Keyword Arguments

• feature_renames, level_renames and label_renames allow renaming different aspects of the data
• extra_content allows including additional output at each node in the visualization

Refer to the documentation on advanced visualization for more information on using these keyword arguments.

Questionnaire(lnr::TreeLearner; keyword_arguments...)

Specifies an interactive questionnaire based on lnr.

Supports the same keyword arguments as TreePlot.

MultiTreePlot(questions::Pair; keyword_arguments...)

Specifies an interactive tree visualization of multiple tree learners as specified by questions. Refer to the documentation on multi-learner visualizations for more details. The keyword arguments are the same as for TreePlot.

MultiTreePlot(grid::GridSearch; keyword_arguments...)

Constructs an interactive tree visualization containing the final fitted learner as well as the learner found for each parameter combination. The keyword arguments are the same as for TreePlot.

write_png(filename::AbstractString, lnr::TreeLearner; keyword_arguments...)

Write lnr to filename as a PNG image.

Requires GraphViz be installed and on the system PATH.

Keyword Arguments

• feature_renames, level_renames and label_renames: renaming different aspects of the data
• extra_content: including additional output at each node in the visualization
• font: the font for the text in the image. Defaults to "Arial"
• show_missing_direction: whether to include the missing data direction in the split criterion. Defaults to true if the data has missing observations, and false otherwise

Refer to the documentation on advanced visualization for more information on using these keyword arguments.

Example

Save tree to mytree.png:

IAI.write_png("mytree.png", lnr)

write_pdf(filename::AbstractString, lnr::TreeLearner; keyword_arguments...)

Write lnr to filename as a PDF image.

Supports the same keyword arguments and has the same requirement as write_png.

write_svg(filename::AbstractString, lnr::TreeLearner; keyword_arguments...)

Write lnr to filename as an SVG image.

Supports the same keyword arguments and has the same requirement as write_png.

write_dot(f, lnr::TreeLearner; keyword_arguments...)

Write the trained tree of lnr into .dot format to the stream f.

Supports the same keyword arguments as write_png.

Example

Save tree to mytree.dot:

IAI.write_dot("mytree.dot", lnr)

You can then convert mytree.dot to PNG image at the command line (requires GraphViz be installed):

$ dot -Tpng -o mytree.png mytree.dot

set_display_label!(lnr::ClassificationTreeLearner, display_label::Any)

Changes which predicted probability is displayed when visualizing lnr to show the probability of display_label.

set_display_label!(grid::GridSearch{<:ClassificationTreeLearner}, display_label::Any)

Changes which predicted probability is displayed when visualizing grid to show the probability of display_label.

reset_display_label!(lnr::ClassificationTreeLearner)

Resets the predicted probability displayed for lnr to be that of the predicted label.

reset_display_label!(grid::GridSearch{<:ClassificationTreeLearner})

Resets the predicted probability displayed for grid to be that of the predicted label.

compare_group_outcomes(lnr::TreeLearner, X::FeatureInput, y::AbstractVector,
                       group::AbstractVector; keyword_arguments...)

In each node of lnr, conduct between-group statistical comparisons of the outcomes for data X and y that fall into the node, where the groups are given by group.

Returns a Vector where each entry corresponds to a node in the tree, and is a NamedTuple with two fields:

• summary: A DataFrame summarizing the outcome by group in this node
• p_value: A Dict containing the p-values of the statistical tests conducted. There are four types of tests conducted:
  • "overall": A single p-value indicating whether there is an overall difference in outcomes between groups in this node (for regression, Welch's test; for classification, chi-squared test)
  • "vs-mean": A Dict with one p-value for each group indicating whether there is a difference between this group and the overall population (for regression, one-sample t-test; for classification, binomial test)
  • "vs-rest": A Dict with one p-value for each group indicating whether there is a difference between this group and all other groups (for regression, two-sample t-test; for classification, Fisher-exact test)
  • "pairwise": A Dict of Dicts, with one p-value for each pair of groups indicating whether there is a difference between these two groups (for regression, two-sample t-test; for classification, Fisher-exact test)

Keyword Arguments

• positive_label: For classification only, specify which label in y to treat as the positive label
• approx::Bool=false: Whether to use approximate comparisons, which can often be significantly faster. For classification, replaces Fisher-exact tests with chi-squared tests.