@@ -1666,10 +1666,24 @@ functions or non-estimator constructors.
1666
1666
in a subsequent call to :term: `fit `.
1667
1667
1668
1668
Note that this is only applicable for some models and some
1669
- parameters, and even some orders of parameter values. For example,
1670
- ``warm_start `` may be used when building random forests to add more
1671
- trees to the forest (increasing ``n_estimators ``) but not to reduce
1672
- their number.
1669
+ parameters, and even some orders of parameter values. In general, there
1670
+ is an interaction between ``warm_start `` and the parameter controlling
1671
+ the number of iterations of the estimator.
1672
+
1673
+ For estimators imported from :mod: `ensemble `,
1674
+ ``warm_start `` will interact with ``n_estimators `` or ``max_iter ``.
1675
+ For these models, the number of iterations, reported via
1676
+ ``len(estimators_) `` or ``n_iter_ ``, corresponds the total number of
1677
+ estimators/iterations learnt since the initialization of the model.
1678
+ Thus, if a model was already initialized with `N`` estimators, and `fit `
1679
+ is called with ``n_estimators `` or ``max_iter `` set to `M `, the model
1680
+ will train `M - N ` new estimators.
1681
+
1682
+ Other models, usually using gradient-based solvers, have a different
1683
+ behavior. They all expose a ``max_iter `` parameter. The reported
1684
+ ``n_iter_ `` corresponds to the number of iteration done during the last
1685
+ call to ``fit `` and will be at most ``max_iter ``. Thus, we do not
1686
+ consider the state of the estimator since the initialization.
1673
1687
1674
1688
:term: `partial_fit ` also retains the model between calls, but differs:
1675
1689
with ``warm_start `` the parameters change and the data is
0 commit comments