[MRG + 1] More versionadded everywhere! (scikit-learn#7403)

* insert versionadded versionchanged directives in docstrings for 0.18

indicate where exception classes were moved from

* moved versionadded in the proper places

Author: amueller

sklearn/datasets/kddcup99.py

@@ -116,6 +116,8 @@ def fetch_kddcup99(subset=None, shuffle=False, random_state=None,
     Targets               str, 'normal.' or name of the anomaly type
     ================      ==========================================
 
+    .. versionadded:: 0.18
+
     Parameters
     ----------
     subset : None, 'SA', 'SF', 'http', 'smtp'
@@ -156,6 +158,7 @@ def fetch_kddcup99(subset=None, shuffle=False, random_state=None,
     .. [2] A Geometric Framework for Unsupervised Anomaly Detection: Detecting
            Intrusions in Unlabeled Data (2002) by Eleazar Eskin, Andrew Arnold,
            Michael Prerau, Leonid Portnoy, Sal Stolfo
+
     """
     kddcup99 = _fetch_brute_kddcup99(shuffle=shuffle, percent10=percent10,
                                      download_if_missing=download_if_missing)

sklearn/decomposition/kernel_pca.py

@@ -78,15 +78,21 @@ class KernelPCA(BaseEstimator, TransformerMixin):
         A pseudo random number generator used for the initialization of the
         residuals when eigen_solver == 'arpack'.
 
+        .. versionadded:: 0.18
+
     n_jobs : int, default=1
         The number of parallel jobs to run.
         If `-1`, then the number of jobs is set to the number of CPU cores.
 
+        .. versionadded:: 0.18
+
     copy_X : boolean, default=True
         If True, input X is copied and stored by the model in the `X_fit_`
         attribute. If no further changes will be done to X, setting
         `copy_X=False` saves memory by storing a reference.
 
+        .. versionadded:: 0.18
+
     Attributes
     ----------
     lambdas_ : array, (n_components,)

sklearn/decomposition/pca.py

@@ -194,6 +194,8 @@ class PCA(_BasePCA):
     explained_variance_ : array, [n_components]
         The amount of variance explained by each of the selected components.
 
+        .. versionadded:: 0.18
+
     explained_variance_ratio_ : array, [n_components]
         Percentage of variance explained by each of the selected components.
 

sklearn/ensemble/forest.py

@@ -73,13 +73,15 @@ class calls the ``fit`` method of each sub-estimator on random samples
 
 MAX_INT = np.iinfo(np.int32).max
 
+
 def _generate_sample_indices(random_state, n_samples):
     """Private function used to _parallel_build_trees function."""
     random_instance = check_random_state(random_state)
     sample_indices = random_instance.randint(0, n_samples, n_samples)
 
     return sample_indices
 
+
 def _generate_unsampled_indices(random_state, n_samples):
     """Private function used to forest._set_oob_score function."""
     sample_indices = _generate_sample_indices(random_state, n_samples)
@@ -90,6 +92,7 @@ def _generate_unsampled_indices(random_state, n_samples):
 
     return unsampled_indices
 
+
 def _parallel_build_trees(tree, forest, X, y, sample_weight, tree_idx, n_trees,
                           verbose=0, class_weight=None):
     """Private function used to fit a single tree in parallel."""
@@ -181,6 +184,8 @@ def apply(self, X):
     def decision_path(self, X):
         """Return the decision path in the forest
 
+        .. versionadded:: 0.18
+
         Parameters
         ----------
         X : array-like or sparse matrix, shape = [n_samples, n_features]
@@ -197,6 +202,7 @@ def decision_path(self, X):
         n_nodes_ptr : array of size (n_estimators + 1, )
             The columns from indicator[n_nodes_ptr[i]:n_nodes_ptr[i+1]]
             gives the indicator value for the i-th estimator.
+
         """
         X = self._validate_X_predict(X)
         indicators = Parallel(n_jobs=self.n_jobs, verbose=self.verbose,
@@ -786,6 +792,9 @@ class RandomForestClassifier(ForestClassifier):
           `ceil(min_samples_split * n_samples)` are the minimum
           number of samples for each split.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_samples_leaf : int, float, optional (default=1)
         The minimum number of samples required to be at a leaf node:
 
@@ -794,6 +803,9 @@ class RandomForestClassifier(ForestClassifier):
           `ceil(min_samples_leaf * n_samples)` are the minimum
           number of samples for each node.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_weight_fraction_leaf : float, optional (default=0.)
         The minimum weighted fraction of the input samples required to be at a
         leaf node.
@@ -991,6 +1003,9 @@ class RandomForestRegressor(ForestRegressor):
           `ceil(min_samples_split * n_samples)` are the minimum
           number of samples for each split.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_samples_leaf : int, float, optional (default=1)
         The minimum number of samples required to be at a leaf node:
 
@@ -999,6 +1014,9 @@ class RandomForestRegressor(ForestRegressor):
           `ceil(min_samples_leaf * n_samples)` are the minimum
           number of samples for each node.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_weight_fraction_leaf : float, optional (default=0.)
         The minimum weighted fraction of the input samples required to be at a
         leaf node.
@@ -1156,6 +1174,9 @@ class ExtraTreesClassifier(ForestClassifier):
           `ceil(min_samples_split * n_samples)` are the minimum
           number of samples for each split.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_samples_leaf : int, float, optional (default=1)
         The minimum number of samples required to be at a leaf node:
 
@@ -1164,6 +1185,9 @@ class ExtraTreesClassifier(ForestClassifier):
           `ceil(min_samples_leaf * n_samples)` are the minimum
           number of samples for each node.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_weight_fraction_leaf : float, optional (default=0.)
         The minimum weighted fraction of the input samples required to be at a
         leaf node.
@@ -1360,6 +1384,9 @@ class ExtraTreesRegressor(ForestRegressor):
           `ceil(min_samples_split * n_samples)` are the minimum
           number of samples for each split.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_samples_leaf : int, float, optional (default=1)
         The minimum number of samples required to be at a leaf node:
 
@@ -1368,6 +1395,9 @@ class ExtraTreesRegressor(ForestRegressor):
           `ceil(min_samples_leaf * n_samples)` are the minimum
           number of samples for each node.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_weight_fraction_leaf : float, optional (default=0.)
         The minimum weighted fraction of the input samples required to be at a
         leaf node.
@@ -1511,6 +1541,9 @@ class RandomTreesEmbedding(BaseForest):
           `ceil(min_samples_split * n_samples)` is the minimum
           number of samples for each split.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_samples_leaf : int, float, optional (default=1)
         The minimum number of samples required to be at a leaf node:
 
@@ -1519,6 +1552,9 @@ class RandomTreesEmbedding(BaseForest):
           `ceil(min_samples_leaf * n_samples)` is the minimum
           number of samples for each node.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_weight_fraction_leaf : float, optional (default=0.)
         The minimum weighted fraction of the input samples required to be at a
         leaf node.

sklearn/ensemble/gradient_boosting.py

@@ -1315,6 +1315,9 @@ class GradientBoostingClassifier(BaseGradientBoosting, ClassifierMixin):
           `ceil(min_samples_split * n_samples)` are the minimum
           number of samples for each split.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_samples_leaf : int, float, optional (default=1)
         The minimum number of samples required to be at a leaf node:
 
@@ -1323,6 +1326,8 @@ class GradientBoostingClassifier(BaseGradientBoosting, ClassifierMixin):
           `ceil(min_samples_leaf * n_samples)` are the minimum
           number of samples for each node.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
 
     min_weight_fraction_leaf : float, optional (default=0.)
         The minimum weighted fraction of the input samples required to be at a
@@ -1678,6 +1683,9 @@ class GradientBoostingRegressor(BaseGradientBoosting, RegressorMixin):
           `ceil(min_samples_split * n_samples)` are the minimum
           number of samples for each split.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_samples_leaf : int, float, optional (default=1)
         The minimum number of samples required to be at a leaf node:
 
@@ -1686,6 +1694,9 @@ class GradientBoostingRegressor(BaseGradientBoosting, RegressorMixin):
           `ceil(min_samples_leaf * n_samples)` are the minimum
           number of samples for each node.
 
+        .. versionchanged:: 0.18
+           Added float values for percentages.
+
     min_weight_fraction_leaf : float, optional (default=0.)
         The minimum weighted fraction of the input samples required to be at a
         leaf node.

sklearn/ensemble/iforest.py

@@ -44,6 +44,8 @@ class IsolationForest(BaseBagging):
 
     Read more in the :ref:`User Guide <isolation_forest>`.
 
+    .. versionadded:: 0.18
+
     Parameters
     ----------
     n_estimators : int, optional (default=100)
@@ -106,6 +108,7 @@ class IsolationForest(BaseBagging):
     .. [2] Liu, Fei Tony, Ting, Kai Ming and Zhou, Zhi-Hua. "Isolation-based
            anomaly detection." ACM Transactions on Knowledge Discovery from
            Data (TKDD) 6.1 (2012): 3.
+
     """
 
     def __init__(self,

sklearn/exceptions.py

@@ -30,15 +30,26 @@ class NotFittedError(ValueError, AttributeError):
     ...     print(repr(e))
     ...                        # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
     NotFittedError('This LinearSVC instance is not fitted yet',)
+
+    .. versionchanged:: 0.18
+       Moved from sklearn.utils.validation.
     """
 
 
 class ChangedBehaviorWarning(UserWarning):
-    """Warning class used to notify the user of any change in the behavior."""
+    """Warning class used to notify the user of any change in the behavior.
+
+    .. versionchanged:: 0.18
+       Moved from sklearn.base.
+    """
 
 
 class ConvergenceWarning(UserWarning):
-    """Custom warning to capture convergence problems"""
+    """Custom warning to capture convergence problems
+
+    .. versionchanged:: 0.18
+       Moved from sklearn.utils.
+    """
 
 
 class DataConversionWarning(UserWarning):
@@ -53,6 +64,9 @@ class DataConversionWarning(UserWarning):
         - requests a non-copying operation, but a copy is required to meet the
           implementation's data-type expectations;
         - passes an input whose shape can be interpreted ambiguously.
+
+    .. versionchanged:: 0.18
+       Moved from sklearn.utils.validation.
     """
 
 
@@ -64,6 +78,9 @@ class DataDimensionalityWarning(UserWarning):
     projection space, is higher than the number of features, which quantifies
     the dimensionality of the original source space, to imply that the
     dimensionality of the problem will not be reduced.
+
+    .. versionchanged:: 0.18
+       Moved from sklearn.utils.
     """
 
 
@@ -73,6 +90,8 @@ class EfficiencyWarning(UserWarning):
     This warning notifies the user that the efficiency may not be optimal due
     to some reason which may be included as a part of the warning message.
     This may be subclassed into a more specific Warning class.
+
+    .. versionadded:: 0.18
     """
 
 
@@ -102,6 +121,9 @@ class FitFailedWarning(RuntimeWarning):
     FitFailedWarning("Classifier fit failed. The score on this train-test
     partition for these parameters will be set to 0.000000. Details:
     \\nValueError('Penalty term must be positive; got (C=-2)',)",)
+
+    .. versionchanged:: 0.18
+       Moved from sklearn.cross_validation.
     """
 
 
@@ -110,8 +132,15 @@ class NonBLASDotWarning(EfficiencyWarning):
 
     This warning is used to notify the user that BLAS was not used for dot
     operation and hence the efficiency may be affected.
+
+    .. versionchanged:: 0.18
+       Moved from sklearn.utils.validation, extends EfficiencyWarning.
     """
 
 
 class UndefinedMetricWarning(UserWarning):
-    """Warning used when the metric is invalid"""
+    """Warning used when the metric is invalid
+
+    .. versionchanged:: 0.18
+       Moved from sklearn.base.
+    """

sklearn/gaussian_process/gpc.py

@@ -45,6 +45,8 @@ class _BinaryGaussianProcessClassifierLaplace(BaseEstimator):
     Currently, the implementation is restricted to using the logistic link
     function.
 
+    .. versionadded:: 0.18
+
     Parameters
     ----------
     kernel : kernel object
@@ -138,6 +140,7 @@ def optimizer(obj_func, initial_theta, bounds):
 
     log_marginal_likelihood_value_: float
         The log-marginal-likelihood of ``self.kernel_.theta``
+
     """
     def __init__(self, kernel=None, optimizer="fmin_l_bfgs_b",
                  n_restarts_optimizer=0, max_iter_predict=100,
@@ -546,6 +549,8 @@ def optimizer(obj_func, initial_theta, bounds):
 
     n_classes_ : int
         The number of classes in the training data
+
+    .. versionadded:: 0.18
     """
     def __init__(self, kernel=None, optimizer="fmin_l_bfgs_b",
                  n_restarts_optimizer=0, max_iter_predict=100,

sklearn/gaussian_process/gpr.py

@@ -35,6 +35,8 @@ class GaussianProcessRegressor(BaseEstimator, RegressorMixin):
 
     Read more in the :ref:`User Guide <gaussian_process>`.
 
+    .. versionadded:: 0.18
+
     Parameters
     ----------
     kernel : kernel object
@@ -125,6 +127,7 @@ def optimizer(obj_func, initial_theta, bounds):
 
     log_marginal_likelihood_value_: float
         The log-marginal-likelihood of ``self.kernel_.theta``
+
     """
     def __init__(self, kernel=None, alpha=1e-10,
                  optimizer="fmin_l_bfgs_b", n_restarts_optimizer=0,