From 608b5e4c3be93b7dd23d29f43e91333c1335faa6 Mon Sep 17 00:00:00 2001 From: Guillaume Lemaitre Date: Tue, 31 Jan 2023 15:48:19 +0100 Subject: [PATCH 1/4] DOC improve the glossary entry --- doc/glossary.rst | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/doc/glossary.rst b/doc/glossary.rst index 6f578836183fe..6430f8a8ab513 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -1666,10 +1666,24 @@ functions or non-estimator constructors. in a subsequent call to :term:`fit`. Note that this is only applicable for some models and some - parameters, and even some orders of parameter values. For example, - ``warm_start`` may be used when building random forests to add more - trees to the forest (increasing ``n_estimators``) but not to reduce - their number. + parameters, and even some orders of parameter values. In general, there + is an interaction between ``warm_start`` and the parameter controlling + the number of iterations of the estimator. + + With ensemble estimators (i.e. estimators imported from :mod:`ensemble`), + ``warm_start`` will interact with ``n_estimators`` or ``max_iter``. + For these models, the number of iterations, reported via + ``len(estiamtors_)`` or ``n_iter_``, corresponds the total number of + iterations/estimators learn since the intiailization of the model. + Thus, if a model was already initialized with `N`` estimators, and `fit` + is called with ``n_estimators`` or ``max_iter`` set to `M`, the model + will train `M - N` new estimators. + + Other models have a different behavior. They all expose a ``max_iter`` + parameter. The reported ``n_iter_`` corresponds to the number of + iteration done during the last call to ``fit`` and will be at most + ``max_iter``. Thus, we do not consider the state of the estimator since + the initialization. :term:`partial_fit` also retains the model between calls, but differs: with ``warm_start`` the parameters change and the data is From 117815f60b21ca31231b91cfa1d0e1bf5d13f891 Mon Sep 17 00:00:00 2001 From: Guillaume Lemaitre Date: Thu, 2 Feb 2023 11:01:33 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Thomas J. Fan --- doc/glossary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/glossary.rst b/doc/glossary.rst index 6430f8a8ab513..97c26cd88cfd6 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -1673,8 +1673,8 @@ functions or non-estimator constructors. With ensemble estimators (i.e. estimators imported from :mod:`ensemble`), ``warm_start`` will interact with ``n_estimators`` or ``max_iter``. For these models, the number of iterations, reported via - ``len(estiamtors_)`` or ``n_iter_``, corresponds the total number of - iterations/estimators learn since the intiailization of the model. + ``len(estimators_)`` or ``n_iter_``, corresponds the total number of + estimators/iterations learn since the initialization of the model. Thus, if a model was already initialized with `N`` estimators, and `fit` is called with ``n_estimators`` or ``max_iter`` set to `M`, the model will train `M - N` new estimators. From b3f6d8ac336b05f3e421e513a657abbb1d31bca0 Mon Sep 17 00:00:00 2001 From: Guillaume Lemaitre Date: Thu, 2 Feb 2023 11:05:21 +0100 Subject: [PATCH 3/4] DOC be more specific regarding ohther models --- doc/glossary.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/glossary.rst b/doc/glossary.rst index 97c26cd88cfd6..e0c950d13c466 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -1679,11 +1679,11 @@ functions or non-estimator constructors. is called with ``n_estimators`` or ``max_iter`` set to `M`, the model will train `M - N` new estimators. - Other models have a different behavior. They all expose a ``max_iter`` - parameter. The reported ``n_iter_`` corresponds to the number of - iteration done during the last call to ``fit`` and will be at most - ``max_iter``. Thus, we do not consider the state of the estimator since - the initialization. + Other models, usually using gradient-based solvers, have a different + behavior. They all expose a ``max_iter`` parameter. The reported + ``n_iter_`` corresponds to the number of iteration done during the last + call to ``fit`` and will be at most ``max_iter``. Thus, we do not + consider the state of the estimator since the initialization. :term:`partial_fit` also retains the model between calls, but differs: with ``warm_start`` the parameters change and the data is From 955da5943e408e3c544e1505b8dfe76cbea9e7c3 Mon Sep 17 00:00:00 2001 From: Guillaume Lemaitre Date: Mon, 20 Feb 2023 11:07:37 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Tim Head --- doc/glossary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/glossary.rst b/doc/glossary.rst index e0c950d13c466..0a249cf94ad22 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -1670,11 +1670,11 @@ functions or non-estimator constructors. is an interaction between ``warm_start`` and the parameter controlling the number of iterations of the estimator. - With ensemble estimators (i.e. estimators imported from :mod:`ensemble`), + For estimators imported from :mod:`ensemble`, ``warm_start`` will interact with ``n_estimators`` or ``max_iter``. For these models, the number of iterations, reported via ``len(estimators_)`` or ``n_iter_``, corresponds the total number of - estimators/iterations learn since the initialization of the model. + estimators/iterations learnt since the initialization of the model. Thus, if a model was already initialized with `N`` estimators, and `fit` is called with ``n_estimators`` or ``max_iter`` set to `M`, the model will train `M - N` new estimators.