Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 40 ยท Hyperparameter Tuning

Tree Complexity Parameters

Learn which parameters limit tree size in XGBoost and LightGBM: max_depth, min_child_weight, gamma, num_leaves and min_child_samples, and how to tune them in the right order.

Once the learning rate is fixed and early stopping picks the number of trees, the next biggest lever is how complex each tree is. Deep trees with tiny leaves can describe almost any pattern in the training data, including its noise. Shallow trees with big leaves are stable but may miss interactions between features.

Both libraries expose the same idea through different names. This lesson maps the names to each other, shows how each parameter changes the fit, and ends with a sensible order for tuning them. The learning rate and early stopping are covered in Learning Rate and the Number of Trees.

The parameters that limit tree size

Idea XGBoost LightGBM Typical range
Maximum depth of a tree max_depth max_depth 3 to 10 (LightGBM: -1 = no limit)
Maximum number of leaves max_leaves (needs grow_policy="lossguide") num_leaves 8 to 256
Minimum evidence in a leaf min_child_weight (sum of hessians) min_child_samples (row count), min_sum_hessian_in_leaf 1 to 100
Minimum gain to split gamma (min_split_loss) min_split_gain 0 to 5

Two of these are worth understanding well.

Depth versus leaves. A tree of depth d can have up to 2^d leaves. XGBoost grows level by level, so max_depth is its natural limit. LightGBM grows leaf by leaf (always splitting the leaf with the largest gain), so num_leaves is the natural limit and max_depth is only a safety cap. If you set max_depth=6 in LightGBM, keep num_leaves well below 2^6 = 64, or the leaf limit never binds. A common rule of thumb is num_leaves at most 2^max_depth - 1, and often far lower.

Minimum child weight. For squared error the hessian of each row is 1, so min_child_weight=20 simply means "at least 20 rows in a leaf". For log loss the hessian of a row is p * (1 - p), which is at most 0.25, so the same setting needs many more rows once the model is confident. That is why min_child_weight in XGBoost behaves less predictably than min_child_samples in LightGBM, which counts rows.

flowchart LR
  A["Few leaves, large min child weight"] --> B["Underfit: simple, stable"]
  C["Many leaves, small min child weight"] --> D["Overfit: memorizes noise"]
  B --- E["Sweet spot in between,<br/>found on validation data"]
  D --- E

Tree size controls the bias and variance trade-off of every tree in the ensemble.

Experiment: sweeping max_depth

The data below has real interactions between features, plus label noise. We fix the learning rate, let early stopping choose the number of rounds, and compare depths:

Python Validation AUC as trees get deeper

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

On one run the output looked like this (your numbers can differ slightly):

TEXT
depth= 1 rounds= 237 train AUC=0.879 valid AUC=0.807
depth= 2 rounds=  85 train AUC=0.931 valid AUC=0.836
depth= 3 rounds=  61 train AUC=0.964 valid AUC=0.846
depth= 5 rounds=  52 train AUC=0.999 valid AUC=0.848
depth= 8 rounds=  82 train AUC=1.000 valid AUC=0.850

Look at three things. First, the training AUC climbs to 1.0, because deep trees fit the training rows perfectly, even though 15% of the labels are random noise. Second, the validation AUC gains a lot from depth 1 to 3 (interactions matter here) and then barely moves. Third, the number of rounds falls as trees get deeper, because each deep tree learns more. The gap between the train and validation columns is the overfitting, and it keeps widening while validation gains nothing. Choose the depth where validation stops improving (here 3 to 5), not the one where training is best. Shallower trees are also faster and give smaller models.

Because the labels are noisy, no model can reach a validation AUC near 1.0. The training AUC can, which is exactly why you must never judge a model by it.

Experiment: minimum evidence per leaf

Raising min_child_weight (or LightGBM's min_child_samples) forbids splits that would create a leaf with too few rows. It acts like a smoother: noisy tiny groups can no longer get their own prediction.

Python LightGBM: min_child_samples on a deep tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

One run printed:

TEXT
min_child_samples=  2  train AUC=1.000  valid AUC=0.853
min_child_samples= 10  train AUC=1.000  valid AUC=0.848
min_child_samples= 30  train AUC=1.000  valid AUC=0.847
min_child_samples=100  train AUC=0.964  valid AUC=0.844
min_child_samples=300  train AUC=0.840  valid AUC=0.800

With num_leaves=63 the trees are large, so a small min_child_samples lets them memorize the training set (train AUC 1.000). Here the validation score hardly reacts to values from 2 to 100, which is typical: gradient boosting is fairly forgiving, and many settings work equally well. The value 300 is too strict for 1,200 training rows: leaves can no longer isolate real structure, and both scores fall. The lesson is that this parameter is a safety limit rather than a fine knob. Raise it when the model is unstable or the data is very noisy, and check that validation does not fall.

The gamma parameter

gamma (XGBoost) or min_split_gain (LightGBM) is the minimum loss reduction needed to make a split. A candidate split whose gain is below it is discarded, which prunes weak branches. It interacts with reg_lambda: both act on the same gain formula, which is explained in Regularization and Subsampling. In practice many people leave gamma=0 and control size with depth and child weight instead, then try gamma between 0.5 and 5 only when overfitting persists.

Counting what you built

You can inspect the trees to see how big they really are. XGBoost's trees_to_dataframe() lists every node:

Python How many leaves did the trees get?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A run gave about 7.8 leaves per tree for depth 3, about 35 for depth 6, and only about 6.4 for depth 6 with min_child_weight=40. Larger max_depth allows more leaves, while a large min_child_weight forbids small ones, so the same depth can produce much smaller trees.

A tuning order that works

  1. Fix a learning rate around 0.05 to 0.1 and a large n_estimators with early stopping.
  2. Tune tree size first: max_depth (3, 4, 6, 8) or num_leaves (15, 31, 63), and the minimum evidence per leaf.
  3. Add row and column subsampling (subsample, colsample_bytree) and the L1/L2 penalties.
  4. Lower the learning rate at the end and let early stopping find the new tree count.

Depth is usually the most sensitive of these. Many tabular problems peak between depth 3 and 8. When data is small or noisy, shallow trees (depth 2 to 4) often win. See A Sensible Tuning Workflow for how to organize the search itself.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In LightGBM, which parameter is the primary limit on tree size because trees grow leaf-wise?

    LightGBM always splits the leaf with the largest gain, so the number of leaves is the natural size limit. max_depth is only a safety cap.
  2. 2. You raise max_depth and see train AUC go up while validation AUC goes down. What does that indicate?

    A growing gap between train and validation scores is the signature of overfitting: the extra depth is memorizing noise.
  3. 3. Why is min_child_weight in XGBoost less intuitive for classification than min_child_samples in LightGBM?

    For log loss each row's hessian is p(1-p), at most 0.25 and often much smaller, so a given min_child_weight can require many rows.
  4. 4. What does the gamma (min_split_loss) parameter do?

    gamma is the minimum gain a split must achieve. Splits below it are pruned, which keeps trees smaller.

Summary

  • Tree complexity is controlled by depth or leaf count, the minimum evidence per leaf, and a minimum split gain.
  • XGBoost thinks in depth (level-wise), LightGBM thinks in leaves (leaf-wise); keep num_leaves below 2^max_depth.
  • min_child_weight sums hessians, min_child_samples counts rows.
  • Overfitting shows as a widening gap between training and validation scores.
  • Tune tree size first, subsampling and penalties next, and lower the learning rate last.

Next: Bayesian Search with Optuna