API Reference

Documentation for the IAITrees public interface.

Index

Types

IAI.TreeLearnerType

Abstract type encompassing all tree-based learners.

Tree Structure

These functions can be used to query the structure of a TreeLearner. The examples make use of the following tree:

Optimal Trees Visualization
IAI.get_num_nodesFunction
get_num_nodes(lnr::TreeLearner)

Return the number of nodes in the trained lnr.

Example

IAI.get_num_nodes(lnr)
7
IAI.is_leafFunction
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
IAI.get_depthFunction
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
IAI.get_num_samplesFunction
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)
78
IAI.get_parentFunction
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
IAI.get_lower_childFunction
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
IAI.get_upper_childFunction
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
IAI.is_parallel_splitFunction
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
IAI.is_hyperplane_splitFunction
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
IAI.is_categoric_splitFunction
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
IAI.is_ordinal_splitFunction
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
IAI.is_mixed_parallel_splitFunction
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
IAI.is_mixed_ordinal_splitFunction
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
IAI.missing_goes_lowerFunction
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
IAI.get_split_featureFunction
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
IAI.get_split_thresholdFunction
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)
60.04421
IAI.get_split_categoriesFunction
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" => 1
  "A" => 1
  "C" => 0
  "D" => 0
  "E" => 0
IAI.get_split_weightsFunction
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 => 1.20415
  :score2 => 0.0189015
categoric_weights
Dict{Symbol, Dict{Any, Float64}} with 1 entry:
  :region => Dict("E"=>1.47922)

Classification

These functions can be used to query the structure of a ClassificationTreeLearner. The examples make use of the following tree:

Optimal Trees Visualization
IAI.get_classification_labelFunction
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"
IAI.get_classification_probaFunction
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
IAI.get_regression_constantMethod
get_regression_constant(lnr::ClassificationTreeLearner, node_index::Int;
                        check_leaf::Bool=true)

Return the constant term in the logistic regression prediction at node node_index in the trained lnr, or NaN if the node does not contain a logistic regression model.

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.

IAI.get_regression_weightsMethod
get_regression_weights(lnr::ClassificationTreeLearner, node_index::Int;
                       check_leaf::Bool=true)

Return the weights for each feature in the logistic 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.

Regression

These functions can be used to query the structure of a RegressionTreeLearner. The examples make use of the following tree:

Optimal Trees Visualization
IAI.get_regression_constantMethod
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
IAI.get_regression_weightsMethod
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}}()

Survival

These functions can be used to query the structure of a SurvivalTreeLearner. The examples make use of the following tree:

Optimal Trees Visualization
IAI.get_survival_curveFunction
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
IAI.get_survival_expected_timeFunction
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)
23443.187287749995
IAI.get_survival_hazardFunction
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.8880508
IAI.get_regression_constantMethod
get_regression_constant(lnr::SurvivalTreeLearner, node_index::Int;
                        check_leaf::Bool=true)

Return the constant term in the Cox regression prediction at node node_index in the trained lnr, or NaN if the node does not contain a Cox regression model.

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.

IAI.get_regression_weightsMethod
get_regression_weights(lnr::SurvivalTreeLearner, node_index::Int;
                       check_leaf::Bool=true)

Return the weights for each feature in the Cox 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.

Prescription

These functions can be used to query the structure of a PrescriptionTreeLearner. The examples make use of the following tree:

Optimal Trees Visualization
IAI.get_prescription_treatment_rankFunction
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, 2)
2-element Vector{String}:
 "A"
 "B"
IAI.get_regression_constantMethod
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, 2, "A")
28.68282
IAI.get_regression_weightsMethod
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, 2, "A")
numeric_weights
Dict{Symbol, Float64} with 1 entry:
  :SystolicBP => -1.37769
categoric_weights
Dict{Symbol, Dict{Any, Float64}}()

Policy

These functions can be used to query the structure of a PolicyTreeLearner. The examples make use of the following tree:

Optimal Trees Visualization
IAI.get_policy_treatment_rankFunction
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 Vector{String}:
 "A"
 "C"
 "B"
IAI.get_policy_treatment_outcomeFunction
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.827778  1.70248  1.09849
outcome.A
0.8277784

Learners

IAI.applyFunction
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.