API Removes the use of fit_ and partial_fit_ in Birch (scikit-learn#19297)

thomasjpfan · web-flow · commit aa1e69a38f1b · 2021-01-30T09:05:10.000+01:00
* API Removes the use of fit_ and partial_fit_ in Birch

* DOC Adds whats new

* ENH Adjust names

* CLN Uses a verbose name
diff --git a/doc/whats_new/v1.0.rst b/doc/whats_new/v1.0.rst
@@ -56,6 +56,9 @@ Changelog
   in multicore settings. :pr:`19052` by
   :user:`Yusuke Nagasaka <YusukeNagasaka>`.
 
+- |API| :class:`cluster.Birch` attributes, `fit_` and `partial_fit_`, are
+  deprecated and will be removed in 1.2. :pr:`19297` by `Thomas Fan`_.
+
 - |Fix| Fixes incorrect multiple data-conversion warnings when clustering
   boolean data. :pr:`19046` by :user:`Surya Prakash <jdsurya>`.
 
diff --git a/sklearn/cluster/_birch.py b/sklearn/cluster/_birch.py
@@ -13,6 +13,7 @@
 from ..metrics.pairwise import euclidean_distances
 from ..base import TransformerMixin, ClusterMixin, BaseEstimator
 from ..utils.extmath import row_norms
+from ..utils import deprecated
 from ..utils.validation import check_is_fitted, _deprecate_positional_args
 from ..exceptions import ConvergenceWarning
 from . import AgglomerativeClustering
@@ -440,6 +441,24 @@ def __init__(self, *, threshold=0.5, branching_factor=50, n_clusters=3,
         self.compute_labels = compute_labels
         self.copy = copy
 
+    # TODO: Remove in 1.2
+    # mypy error: Decorated property not supported
+    @deprecated(  # type: ignore
+        "fit_ is deprecated in 1.0 and will be removed in 1.2"
+    )
+    @property
+    def fit_(self):
+        return self._deprecated_fit
+
+    # TODO: Remove in 1.2
+    # mypy error: Decorated property not supported
+    @deprecated(  # type: ignore
+        "partial_fit_ is deprecated in 1.0 and will be removed in 1.2"
+    )
+    @property
+    def partial_fit_(self):
+        return self._deprecated_partial_fit
+
     def fit(self, X, y=None):
         """
         Build a CF Tree for the input data.
@@ -457,12 +476,13 @@ def fit(self, X, y=None):
         self
             Fitted estimator.
         """
-        self.fit_, self.partial_fit_ = True, False
-        return self._fit(X)
+        # TODO: Remove deprected flags in 1.2
+        self._deprecated_fit, self._deprecated_partial_fit = True, False
+        return self._fit(X, partial=False)
 
-    def _fit(self, X):
+    def _fit(self, X, partial):
         has_root = getattr(self, 'root_', None)
-        first_call = self.fit_ or (self.partial_fit_ and not has_root)
+        first_call = not (partial and has_root)
 
         X = self._validate_data(X, accept_sparse='csr', copy=self.copy,
                                 reset=first_call)
@@ -552,13 +572,14 @@ def partial_fit(self, X=None, y=None):
         self
             Fitted estimator.
         """
-        self.partial_fit_, self.fit_ = True, False
+        # TODO: Remove deprected flags in 1.2
+        self._deprecated_partial_fit, self._deprecated_fit = True, False
         if X is None:
             # Perform just the final global clustering step.
             self._global_clustering()
             return self
         else:
-            return self._fit(X)
+            return self._fit(X, partial=True)
 
     def _check_fit(self, X):
         check_is_fitted(self)
diff --git a/sklearn/cluster/tests/test_birch.py b/sklearn/cluster/tests/test_birch.py
@@ -179,3 +179,15 @@ def test_birch_n_clusters_long_int():
     X, _ = make_blobs(random_state=0)
     n_clusters = np.int64(5)
     Birch(n_clusters=n_clusters).fit(X)
+
+
+# TODO: Remove in 1.2
+@pytest.mark.parametrize("attribute", ["fit_", "partial_fit_"])
+def test_birch_fit_attributes_deprecated(attribute):
+    """Test that fit_ and partial_fit_ attributes are deprecated."""
+    msg = f"{attribute} is deprecated in 1.0 and will be removed in 1.2"
+    X, y = make_blobs(n_samples=10)
+    brc = Birch().fit(X, y)
+
+    with pytest.warns(FutureWarning, match=msg):
+        getattr(brc, attribute)
