CreateDecisionTreeModel — Analysis Tool Box

Introduction

Some predictions need to be explained, not just made — a credit decision, a compliance flag, a manufacturing diagnosis all benefit from a model whose logic a human can actually read. CreateDecisionTreeModel builds a scikit-learn decision tree end-to-end for either classification or regression, and — unlike most models in this module — can render the tree diagram itself or print its decision rules as text, turning the model into a transparent, auditable set of if/then splits rather than a black box.

Teaching Note

Building decision tree models is essential for:

Segmenting customers into high and low risk categories for credit scoring
Identifying key predictive factors for equipment failure in manufacturing
Categorizing intelligence reports based on attributes like origin or severity
Forecasting numeric values like product prices or temperature readings
Creating transparent, human-readable decision rules for regulatory compliance
Mapping complex hierarchical decision paths in operational workflows
Selecting the most influential features for targeted marketing campaigns

Parameters

Parameter	Default	Description
`dataframe`required	—	The input pandas DataFrame containing the training and testing data.
`outcome_variable`required	—	The name of the target column to be predicted.
`list_of_predictor_variables`required	—	A list of column names used as features for the model.
`is_outcome_categorical`	`True`	If True, trains a DecisionTreeClassifier. If False, trains a DecisionTreeRegressor. Defaults to True.
`print_model_training_performance`	`False`	If True, prints evaluation metrics (e.g., Classification Report or MSE) to the console. Defaults to False.
`test_size`	`0.2`	The proportion of the dataset to include in the test split. Defaults to 0.2.
`categorical_splitting_criterion`	`'entropy'`	The function to measure the quality of a split for classification. Supported values are 'gini' and 'entropy'. Defaults to 'entropy'.
`numerical_splitting_criterion`	`'squared_error'`	The function to measure the quality of a split for regression. Supported values are 'squared_error', 'friedman_mse', 'absolute_error', and 'poisson'. Defaults to 'squared_error'.
`maximum_depth`	`None`	The maximum depth of the tree. If None, nodes are expanded until all leaves are pure. Defaults to None.
`minimum_impurity_decrease`	`0.0`	A node will be split if this split induces a decrease of the impurity greater than or equal to this value. Defaults to 0.0.
`random_seed`	`412`	Controls the randomness of the split and the estimator. Defaults to 412.
`filter_nulls`	`False`	Whether to drop rows containing any NaN values across the selected columns. Defaults to False.
`data_source_for_plot`	`None`	Source citation string displayed in the caption of all generated plots. Defaults to None.
`plot_model_test_performance`	`True`	Whether to generate a visualization of model performance on the test set (scatterplot for regression, heatmap for classification). Defaults to True.
`dot_fill_color`	`'#999999'`	Hex color for the scatterplot points in the regression performance plot. Defaults to '#999999'.
`fitted_line_type`	`None`	Line style for the fitted reference line in the regression performance plot. Defaults to None (matplotlib default).
`line_color`	`None`	Hex color for the fitted reference line in the regression performance plot. Defaults to None (matplotlib default).
`heatmap_color_palette`	`'Blues'`	Colormap name for the classification confusion matrix heatmap. Defaults to 'Blues'.
`figure_size_for_model_test_performance_plot`	`(8, 6)`	Dimensions (width, height) for the performance plot. Defaults to (8, 6).
`title_for_model_test_performance_plot`	`'Model Performance'`	Title text for the test-set performance plot.
`subtitle_for_model_test_performance_plot`	`'The predicted values vs. the actual values in the test dataset.'`	Subtitle text for the test-set performance plot.
`caption_for_model_test_performance_plot`	`None`	Optional caption text for the test-set performance plot.
`title_y_indent_for_model_test_performance_plot`	`1.09`	Vertical position of the title on the test-set performance plot. Defaults to 1.09.
`subtitle_y_indent_for_model_test_performance_plot`	`1.05`	Vertical position of the subtitle on the test-set performance plot. Defaults to 1.05.
`caption_y_indent_for_model_test_performance_plot`	`-0.215`	Vertical position of the caption on the test-set performance plot. Defaults to -0.215.
`x_indent_for_model_test_performance_plot`	`-0.115`	Horizontal starting position for text on the test-set performance plot. Defaults to -0.115.
`plot_feature_importance`	`True`	Whether to generate a horizontal bar chart showing the predictive weight of each variable. Defaults to True.
`top_n_to_highlight`	`3`	The number of top features to color differently in the importance plot. Defaults to 3.
`highlight_color`	`'#b0170c'`	Hex color for the top-N feature bars in the importance plot. Defaults to '#b0170c'.
`fill_transparency`	`0.8`	Alpha transparency for the feature importance bars. Defaults to 0.8.
`figure_size_for_feature_importance_plot`	`(8, 6)`	Dimensions (width, height) for the importance plot. Defaults to (8, 6).
`title_for_feature_importance_plot`	`'Feature Importance'`	Title text for the feature importance plot.
`subtitle_for_feature_importance_plot`	`'Shows the predictive power of each feature in the model.'`	Subtitle text for the feature importance plot.
`caption_for_feature_importance_plot`	`None`	Optional caption text for the feature importance plot.
`title_y_indent_for_feature_importance_plot`	`1.15`	Vertical position of the title on the feature importance plot. Defaults to 1.15.
`subtitle_y_indent_for_feature_importance_plot`	`1.1`	Vertical position of the subtitle on the feature importance plot. Defaults to 1.1.
`caption_y_indent_for_feature_importance_plot`	`-0.15`	Vertical position of the caption on the feature importance plot. Defaults to -0.15.
`plot_decision_tree`	`False`	If True, renders a visual diagram of the trained decision tree. Defaults to False.
`decision_tree_plot_size`	`(20, 20)`	Dimensions (width, height) for the tree structure diagram. Defaults to (20, 20).
`print_decision_rules`	`False`	If True, prints a text-based version of the decision logic to the console. Defaults to False.
`plot_training_and_test_performance`	`True`	If True, renders a bar chart comparing training vs. test MSE (for regression) or training vs. test error rate (for classification). Defaults to True.
`training_bar_color`	`'#3a86ff'`	Hex color for the training bar in the comparison chart. Defaults to '#3a86ff'.
`test_bar_color`	`'#b0170c'`	Hex color for the test bar in the comparison chart. Defaults to '#b0170c'.
`figure_size_for_performance_comparison_plot`	`(7, 5)`	Dimensions (width, height) for the comparison chart. Defaults to (7, 5).
`title_for_performance_comparison_plot`	`None`	Title text for the comparison chart. Defaults to a metric-appropriate string.
`subtitle_for_performance_comparison_plot`	`None`	Subtitle text for the comparison chart. Defaults to a metric-appropriate string.
`caption_for_performance_comparison_plot`	`None`	Optional caption text for the comparison chart. Defaults to None.
`title_y_indent_for_performance_comparison_plot`	`1.1`	Vertical position of the title in axes-fraction coordinates. Defaults to 1.10.
`subtitle_y_indent_for_performance_comparison_plot`	`1.05`	Vertical position of the subtitle in axes-fraction coordinates. Defaults to 1.05.
`caption_y_indent_for_performance_comparison_plot`	`-0.15`	Vertical position of the caption in axes-fraction coordinates. Defaults to -0.15.
`x_indent_for_performance_comparison_plot`	`-0.115`	Horizontal starting position for title/subtitle/caption text. Defaults to -0.115.

Returns

The fitted sklearn.tree.BaseDecisionTree model — a DecisionTreeClassifier or DecisionTreeRegressor, depending on is_outcome_categorical.

Example

python

from analysistoolbox.predictive_analytics import CreateDecisionTreeModel

# Classification: predict credit risk levels and show the tree
model = CreateDecisionTreeModel(
    df,
    outcome_variable='RiskLevel',
    list_of_predictor_variables=['CreditScore', 'Income'],
    is_outcome_categorical=True,
    plot_decision_tree=True,
)