Add "See also" for selectors and scoring funs

Details:
- Reference uni variate selectors and scoring funcs
- Indicate chi2 is only for non-negative features
- Add "See also" formatting rules to contributing
- Add example of good "References" in docstrings
- Misc small doc updates for uni feature selection
  - Add missing periods (for consistency)
  - Anova -> ANOVA (for consistency)
  - Make a numbered list render per item per line (for readability)
  - Capitalize the first letter of a numbered list (for readability)

Author: martin0258

doc/developers/index.rst

@@ -256,12 +256,28 @@ intuition.
 
 Next, one or two small code examples to show its use can be added.
 
-Finally, any math and equations, followed by references,
+Next, any math and equations, followed by references,
 can be added to further the documentation. Not starting the
 documentation with the maths makes it more friendly towards
 users that are just interested in what the feature will do, as
 opposed to how it works "under the hood".
 
+Finally, follow the formatting rules below to make it consistently good:
+
+    * Add "See also" in docstrings for related classes/functions.
+    
+    * "See also" in docstrings should be one line per reference, 
+      with a colon and an explanation, for example::
+
+        See also
+        --------
+        SelectKBest: Select features based on the k highest scores.
+        SelectFpr: Select features based on a false positive rate test.
+
+    * For unwritten formatting rules, try to follow existing good works:
+    
+        * For "References" in docstrings, see the Silhouette Coefficient
+          (:func:`sklearn.metrics.silhouette_score`).
 
 .. warning:: **Sphinx version**
 

sklearn/feature_selection/univariate_selection.py

@@ -117,7 +117,7 @@ def f_oneway(*args):
 
 
 def f_classif(X, y):
-    """Compute the Anova F-value for the provided sample
+    """Compute the ANOVA F-value for the provided sample.
 
     Parameters
     ----------
@@ -134,6 +134,11 @@ def f_classif(X, y):
 
     pval : array, shape = [n_features,]
         The set of p-values.
+
+    See also
+    --------
+    chi2: Chi-squared stats of non-negative features for classification tasks.
+    f_regression: F-value between label/feature for regression tasks.
     """
     X, y = check_X_y(X, y, ['csr', 'csc', 'coo'])
     args = [X[safe_mask(X, y == k)] for k in np.unique(y)]
@@ -159,12 +164,12 @@ def _chisquare(f_obs, f_exp):
 
 
 def chi2(X, y):
-    """Compute chi-squared statistic for each class/feature combination.
+    """Compute chi-squared stats between each non-negative feature and class.
 
     This score can be used to select the n_features features with the
     highest values for the test chi-squared statistic from X, which must
-    contain booleans or frequencies (e.g., term counts in document
-    classification), relative to the classes.
+    contain only non-negative features such as booleans or frequencies
+    (e.g., term counts in document classification), relative to the classes.
 
     Recall that the chi-square test measures dependence between stochastic
     variables, so using this function "weeds out" the features that are the
@@ -189,6 +194,11 @@ def chi2(X, y):
     Notes
     -----
     Complexity of this algorithm is O(n_classes * n_features).
+
+    See also
+    --------
+    f_classif: ANOVA F-value between labe/feature for classification tasks.
+    f_regression: F-value between label/feature for regression tasks.
     """
 
     # XXX: we might want to do some of the following in logspace instead for
@@ -211,16 +221,17 @@ def chi2(X, y):
 
 
 def f_regression(X, y, center=True):
-    """Univariate linear regression tests
+    """Univariate linear regression tests.
 
     Quick linear model for testing the effect of a single regressor,
     sequentially for many regressors.
 
     This is done in 3 steps:
-    1. the regressor of interest and the data are orthogonalized
-    wrt constant regressors
-    2. the cross correlation between data and regressors is computed
-    3. it is converted to an F score then to a p-value
+
+    1. The regressor of interest and the data are orthogonalized
+       wrt constant regressors.
+    2. The cross correlation between data and regressors is computed.
+    3. It is converted to an F score then to a p-value.
 
     Parameters
     ----------
@@ -240,6 +251,11 @@ def f_regression(X, y, center=True):
 
     pval : array, shape=(n_features,)
         p-values of F-scores.
+
+    See also
+    --------
+    f_classif: ANOVA F-value between labe/feature for classification tasks.
+    chi2: Chi-squared stats of non-negative features for classification tasks.
     """
     if issparse(X) and center:
         raise ValueError("center=True only allowed for dense data")
@@ -341,6 +357,16 @@ class SelectPercentile(_BaseFilter):
     Ties between features with equal scores will be broken in an unspecified
     way.
 
+    See also
+    --------
+    f_classif: ANOVA F-value between labe/feature for classification tasks.
+    chi2: Chi-squared stats of non-negative features for classification tasks.
+    f_regression: F-value between label/feature for regression tasks.
+    SelectKBest: Select features based on the k highest scores.
+    SelectFpr: Select features based on a false positive rate test.
+    SelectFdr: Select features based on an estimated false discovery rate.
+    SelectFwe: Select features based on family-wise error rate.
+    GenericUnivariateSelect: Univariate feature selector with configurable mode.
     """
 
     def __init__(self, score_func=f_classif, percentile=10):
@@ -399,6 +425,16 @@ class SelectKBest(_BaseFilter):
     Ties between features with equal scores will be broken in an unspecified
     way.
 
+    See also
+    --------
+    f_classif: ANOVA F-value between labe/feature for classification tasks.
+    chi2: Chi-squared stats of non-negative features for classification tasks.
+    f_regression: F-value between label/feature for regression tasks.
+    SelectPercentile: Select features based on percentile of the highest scores.
+    SelectFpr: Select features based on a false positive rate test.
+    SelectFdr: Select features based on an estimated false discovery rate.
+    SelectFwe: Select features based on family-wise error rate.
+    GenericUnivariateSelect: Univariate feature selector with configurable mode.
     """
 
     def __init__(self, score_func=f_classif, k=10):
@@ -450,6 +486,17 @@ class SelectFpr(_BaseFilter):
 
     pvalues_ : array-like, shape=(n_features,)
         p-values of feature scores.
+
+    See also
+    --------
+    f_classif: ANOVA F-value between labe/feature for classification tasks.
+    chi2: Chi-squared stats of non-negative features for classification tasks.
+    f_regression: F-value between label/feature for regression tasks.
+    SelectPercentile: Select features based on percentile of the highest scores.
+    SelectKBest: Select features based on the k highest scores.
+    SelectFdr: Select features based on an estimated false discovery rate.
+    SelectFwe: Select features based on family-wise error rate.
+    GenericUnivariateSelect: Univariate feature selector with configurable mode.
     """
 
     def __init__(self, score_func=f_classif, alpha=5e-2):
@@ -490,6 +537,16 @@ class SelectFdr(_BaseFilter):
     ----------
     http://en.wikipedia.org/wiki/False_discovery_rate
 
+    See also
+    --------
+    f_classif: ANOVA F-value between labe/feature for classification tasks.
+    chi2: Chi-squared stats of non-negative features for classification tasks.
+    f_regression: F-value between label/feature for regression tasks.
+    SelectPercentile: Select features based on percentile of the highest scores.
+    SelectKBest: Select features based on the k highest scores.
+    SelectFpr: Select features based on a false positive rate test.
+    SelectFwe: Select features based on family-wise error rate.
+    GenericUnivariateSelect: Univariate feature selector with configurable mode.
     """
 
     def __init__(self, score_func=f_classif, alpha=5e-2):
@@ -527,6 +584,17 @@ class SelectFwe(_BaseFilter):
 
     pvalues_ : array-like, shape=(n_features,)
         p-values of feature scores.
+
+    See also
+    --------
+    f_classif: ANOVA F-value between labe/feature for classification tasks.
+    chi2: Chi-squared stats of non-negative features for classification tasks.
+    f_regression: F-value between label/feature for regression tasks.
+    SelectPercentile: Select features based on percentile of the highest scores.
+    SelectKBest: Select features based on the k highest scores.
+    SelectFpr: Select features based on a false positive rate test.
+    SelectFdr: Select features based on an estimated false discovery rate.
+    GenericUnivariateSelect: Univariate feature selector with configurable mode.
     """
 
     def __init__(self, score_func=f_classif, alpha=5e-2):
@@ -567,6 +635,17 @@ class GenericUnivariateSelect(_BaseFilter):
 
     pvalues_ : array-like, shape=(n_features,)
         p-values of feature scores.
+
+    See also
+    --------
+    f_classif: ANOVA F-value between labe/feature for classification tasks.
+    chi2: Chi-squared stats of non-negative features for classification tasks.
+    f_regression: F-value between label/feature for regression tasks.
+    SelectPercentile: Select features based on percentile of the highest scores.
+    SelectKBest: Select features based on the k highest scores.
+    SelectFpr: Select features based on a false positive rate test.
+    SelectFdr: Select features based on an estimated false discovery rate.
+    SelectFwe: Select features based on family-wise error rate.
     """
 
     _selection_modes = {'percentile':   SelectPercentile,