[MRG+2] DOC framework for keeping API refs for deprecated classes/fun…

…cs (scikit-learn#7725)

* DOC framework for keeping API refs for deprecated classes/funcs

* DOC tagging deprecated for 0.20

* suggestion for LDA/QDA deprecation

* simplify deprecation message for GaussianProcess

* simplify deprecation messages

* fixup avoid import QuadraticDiscriminantAnalysis in qda.QDA (and similar for LDA).

* fixup test alias lda.LDA is instance of LinearDiscriminantAnalysis

doc/modules/classes.rst

@@ -186,6 +186,7 @@ Splitter Functions
  :template: function.rst
 
  model_selection.train_test_split
+ model_selection.check_cv
 
 Hyper-parameter optimizers
 --------------------------
@@ -201,6 +202,13 @@ Hyper-parameter optimizers
  model_selection.ParameterGrid
  model_selection.ParameterSampler
 
+
+.. autosummary::
+ :toctree: generated/
+ :template: function.rst
+
+ model_selection.fit_grid_point
+
 Model validation
 ----------------
 
@@ -315,7 +323,6 @@ Samples generator
  decomposition.PCA
  decomposition.IncrementalPCA
  decomposition.ProjectedGradientNMF
- decomposition.RandomizedPCA
  decomposition.KernelPCA
  decomposition.FactorAnalysis
  decomposition.FastICA
@@ -560,7 +567,6 @@ From text
 
  gaussian_process.GaussianProcessRegressor
  gaussian_process.GaussianProcessClassifier
- gaussian_process.GaussianProcess
 
 Kernels:
 
@@ -1349,3 +1355,67 @@ Low-level methods
  utils.estimator_checks.check_estimator
  utils.resample
  utils.shuffle
+
+
+Recently deprecated
+===================
+
+To be removed in 0.19
+---------------------
+
+.. autosummary::
+ :toctree: generated/
+ :template: deprecated_class.rst
+
+ lda.LDA
+ qda.QDA
+
+.. autosummary::
+ :toctree: generated/
+ :template: deprecated_function.rst
+
+ datasets.load_lfw_pairs
+ datasets.load_lfw_people
+
+
+To be removed in 0.20
+---------------------
+
+.. autosummary::
+ :toctree: generated/
+ :template: deprecated_class.rst
+
+ grid_search.ParameterGrid
+ grid_search.ParameterSampler
+ grid_search.GridSearchCV
+ grid_search.RandomizedSearchCV
+ cross_validation.LeaveOneOut
+ cross_validation.LeavePOut
+ cross_validation.KFold
+ cross_validation.LabelKFold
+ cross_validation.LeaveOneLabelOut
+ cross_validation.LeavePLabelOut
+ cross_validation.LabelShuffleSplit
+ cross_validation.StratifiedKFold
+ cross_validation.ShuffleSplit
+ cross_validation.StratifiedShuffleSplit
+ cross_validation.PredefinedSplit
+ decomposition.RandomizedPCA
+ gaussian_process.GaussianProcess
+ mixture.GMM
+ mixture.DPGMM
+ mixture.VBGMM
+
+
+.. autosummary::
+ :toctree: generated/
+ :template: deprecated_function.rst
+
+ grid_search.fit_grid_point
+ learning_curve.learning_curve
+ learning_curve.validation_curve
+ cross_validation.cross_val_predict
+ cross_validation.cross_val_score
+ cross_validation.check_cv
+ cross_validation.permutation_test_score
+ cross_validation.train_test_split

doc/templates/deprecated_class.rst

@@ -0,0 +1,23 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}==============
+
+.. meta::
+ :robots: noindex
+
+.. warning::
+ **DEPRECATED**
+
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+ {% block methods %}
+ .. automethod:: __init__
+ {% endblock %}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+ <div class="clearer"></div>

doc/templates/deprecated_class_with_call.rst

@@ -0,0 +1,24 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}===============
+
+.. meta::
+ :robots: noindex
+
+.. warning::
+ **DEPRECATED**
+
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+ {% block methods %}
+ .. automethod:: __init__
+ .. automethod:: __call__
+ {% endblock %}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+ <div class="clearer"></div>

doc/templates/deprecated_class_without_init.rst

@@ -0,0 +1,19 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}==============
+
+.. meta::
+ :robots: noindex
+
+.. warning::
+ **DEPRECATED**
+
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+ <div class="clearer"></div>

doc/templates/deprecated_function.rst

@@ -0,0 +1,19 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}====================
+
+.. meta::
+ :robots: noindex
+
+.. warning::
+ **DEPRECATED**
+
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+ <div class="clearer"></div>

doc/templates/generate_deprecated.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+for f in [^d]*; do (head -n2 < $f; echo '
+.. meta::
+ :robots: noindex
+
+.. warning::
+ **DEPRECATED**
+'; tail -n+3 $f) > deprecated_$f; done

doc/themes/scikit-learn/static/nature.css_t

@@ -603,7 +603,7 @@ div.admonition {
  -moz-border-radius: 4px;
 }
 
-div.warning {
+div.warning, div.deprecated {
  color: #b94a48;
  background-color: #F3E5E5;
  border: 1px solid #eed3d7;

sklearn/cross_validation.py

@@ -109,6 +109,10 @@ def _empty_mask(self):
 class LeaveOneOut(_PartitionIterator):
  """Leave-One-Out cross validation iterator.
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :class:`sklearn.model_selection.LeaveOneOut` instead.
+
  Provides train/test indices to split data in train test sets. Each
  sample is used once as a test set (singleton) while the remaining
  samples form the training set.
@@ -171,6 +175,10 @@ def __len__(self):
 class LeavePOut(_PartitionIterator):
  """Leave-P-Out cross validation iterator
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :class:`sklearn.model_selection.LeavePOut` instead.
+
  Provides train/test indices to split data in train test sets. This results
  in testing on all distinct samples of size p, while the remaining n - p
  samples form the training set in each iteration.
@@ -266,6 +274,10 @@ def __init__(self, n, n_folds, shuffle, random_state):
 class KFold(_BaseKFold):
  """K-Folds cross validation iterator.
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :class:`sklearn.model_selection.KFold` instead.
+
  Provides train/test indices to split data in train test sets. Split
  dataset into k consecutive folds (without shuffling by default).
 
@@ -357,6 +369,10 @@ def __len__(self):
 class LabelKFold(_BaseKFold):
  """K-fold iterator variant with non-overlapping labels.
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :class:`sklearn.model_selection.GroupKFold` instead.
+
  The same label will not appear in two different folds (the number of
  distinct labels has to be at least equal to the number of folds).
 
@@ -459,6 +475,10 @@ def __len__(self):
 class StratifiedKFold(_BaseKFold):
  """Stratified K-Folds cross validation iterator
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :class:`sklearn.model_selection.StratifiedKFold` instead.
+
  Provides train/test indices to split data in train test sets.
 
  This cross-validation object is a variation of KFold that
@@ -581,6 +601,10 @@ def __len__(self):
 class LeaveOneLabelOut(_PartitionIterator):
  """Leave-One-Label_Out cross-validation iterator
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :class:`sklearn.model_selection.LeaveOneGroupOut` instead.
+
  Provides train/test indices to split data according to a third-party
  provided label. This label information can be used to encode arbitrary
  domain specific stratifications of the samples as integers.
@@ -651,6 +675,10 @@ def __len__(self):
 class LeavePLabelOut(_PartitionIterator):
  """Leave-P-Label_Out cross-validation iterator
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :class:`sklearn.model_selection.LeavePGroupsOut` instead.
+
  Provides train/test indices to split data according to a third-party
  provided label. This label information can be used to encode arbitrary
  domain specific stratifications of the samples as integers.
@@ -762,6 +790,10 @@ def _iter_indices(self):
 class ShuffleSplit(BaseShuffleSplit):
  """Random permutation cross-validation iterator.
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :class:`sklearn.model_selection.ShuffleSplit` instead.
+
  Yields indices to split data into training and test sets.
 
  Note: contrary to other cross-validation strategies, random splits
@@ -963,6 +995,10 @@ def _approximate_mode(class_counts, n_draws, rng):
 class StratifiedShuffleSplit(BaseShuffleSplit):
  """Stratified ShuffleSplit cross validation iterator
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :class:`sklearn.model_selection.StratifiedShuffleSplit` instead.
+
  Provides train/test indices to split data in train test sets.
 
  This cross-validation object is a merge of StratifiedKFold and
@@ -1085,6 +1121,10 @@ def __len__(self):
 class PredefinedSplit(_PartitionIterator):
  """Predefined split cross validation iterator
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :class:`sklearn.model_selection.PredefinedSplit` instead.
+
  Splits the data into training/test set folds according to a predefined
  scheme. Each sample can be assigned to at most one test set fold, as
  specified by the user through the ``test_fold`` parameter.
@@ -1140,6 +1180,10 @@ def __len__(self):
 class LabelShuffleSplit(ShuffleSplit):
  """Shuffle-Labels-Out cross-validation iterator
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :class:`sklearn.model_selection.GroupShuffleSplit` instead.
+
  Provides randomized train/test indices to split data according to a
  third-party provided label. This label information can be used to encode
  arbitrary domain specific stratifications of the samples as integers.
@@ -1241,6 +1285,10 @@ def cross_val_predict(estimator, X, y=None, cv=None, n_jobs=1,
  verbose=0, fit_params=None, pre_dispatch='2*n_jobs'):
  """Generate cross-validated estimates for each input data point
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :func:`sklearn.model_selection.cross_val_predict` instead.
+
  Read more in the :ref:`User Guide <cross_validation>`.
 
  Parameters
@@ -1421,6 +1469,10 @@ def cross_val_score(estimator, X, y=None, scoring=None, cv=None, n_jobs=1,
  verbose=0, fit_params=None, pre_dispatch='2*n_jobs'):
  """Evaluate a score by cross-validation
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :func:`sklearn.model_selection.cross_val_score` instead.
+
  Read more in the :ref:`User Guide <cross_validation>`.
 
  Parameters
@@ -1724,6 +1776,10 @@ def _shuffle(y, labels, random_state):
 def check_cv(cv, X=None, y=None, classifier=False):
  """Input checker utility for building a CV in a user friendly way.
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :func:`sklearn.model_selection.check_cv` instead.
+
  Parameters
  ----------
  cv : int, cross-validation generator or an iterable, optional
@@ -1781,6 +1837,10 @@ def permutation_test_score(estimator, X, y, cv=None,
  random_state=0, verbose=0, scoring=None):
  """Evaluate the significance of a cross-validated score with permutations
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :func:`sklearn.model_selection.permutation_test_score` instead.
+
  Read more in the :ref:`User Guide <cross_validation>`.
 
  Parameters
@@ -1882,6 +1942,10 @@ def permutation_test_score(estimator, X, y, cv=None,
 def train_test_split(*arrays, **options):
  """Split arrays or matrices into random train and test subsets
 
+ .. deprecated:: 0.18
+ This module will be removed in 0.20.
+ Use :func:`sklearn.model_selection.train_test_split` instead.
+
  Quick utility that wraps input validation and
  ``next(iter(ShuffleSplit(n_samples)))`` and application to input
  data into a single call for splitting (and optionally subsampling)