fixed small issues jorvisvandenbossche noted

Author: Nick Eubank

doc/source/indexing.rst

@@ -516,29 +516,29 @@ A random selection of rows or columns from a Series, DataFrame, or Panel with th
 
 .. ipython :: python
 
-   s = Series([0,1,2,3,4,5])
+    s = Series([0,1,2,3,4,5])
 
-   # When no arguments are passed, returns 1 row.
-   s.sample()
-   
-   # One may specify either a number of rows:
-   s.sample(n = 3)
+    # When no arguments are passed, returns 1 row.
+    s.sample()
+    
+    # One may specify either a number of rows:
+    s.sample(n=3)
    
-   # Or a fraction of the rows:
-   s.sample(frac = 0.5)
+    # Or a fraction of the rows:
+    s.sample(frac=0.5)
 
 By default, ``sample`` will return each row at most once, but one can also sample with replacement
 using the ``replace`` option:
 
 .. ipython :: python
 
    s = Series([0,1,2,3,4,5])
-		
-   # Without replacement (default):
-   s.sample(n = 6, replace = False)
-	
-   # With replacement:
-   s.sample(n = 6, replace = True)
+
+    # Without replacement (default):
+    s.sample(n=6, replace=False)
+
+    # With replacement:
+    s.sample(n=6, replace=True)
 
 
 By default, each row has an equal probability of being selected, but if you want rows
@@ -549,37 +549,37 @@ to have different probabilities, you can pass the ``sample`` function sampling w
 
     s = Series([0,1,2,3,4,5])
     example_weights = [0, 0, 0.2, 0.2, 0.2, 0.4]
-    s.sample(n=3, weights = example_weights)
-	
-	# Weights will be re-normalized automatically
-	example_weights2 = [0.5, 0, 0, 0, 0, 0]
-	s.sample(n=1, weights= example_weights2)
+    s.sample(n=3, weights=example_weights)
+    
+    # Weights will be re-normalized automatically
+    example_weights2 = [0.5, 0, 0, 0, 0, 0]
+    s.sample(n=1, weights=example_weights2)
 
 When applied to a DataFrame, you can use a column of the DataFrame as sampling weights
 (provided you are sampling rows and not columns) by simply passing the name of the column 
 as a string.
-	
+    
 .. ipython :: python
 
-   df2 = DataFrame({'col1':[9,8,7,6], 'weight_column':[0.5, 0.4, 0.1, 0]})
-   df2.sample(n = 3, weights = 'weight_column')
+    df2 = DataFrame({'col1':[9,8,7,6], 'weight_column':[0.5, 0.4, 0.1, 0]})
+    df2.sample(n = 3, weights = 'weight_column')
 
 ``sample`` also allows users to sample columns instead of rows using the ``axis`` argument. 
 
 .. 	ipython :: python
 
-	df3 = DataFrame({'col1':[1,2,3], 'col2':[2,3,4]})
-	df3.sample(n=1, axis = 1)
+    df3 = DataFrame({'col1':[1,2,3], 'col2':[2,3,4]})
+    df3.sample(n=1, axis=1)
 
 Finally, one can also set a seed for ``sample``'s random number generator using the ``random_state`` argument, which will accept either an integer (as a seed) or a numpy RandomState object. 
 
 .. 	ipython :: python
 
-	df4 = DataFrame({'col1':[1,2,3], 'col2':[2,3,4]})
+    df4 = DataFrame({'col1':[1,2,3], 'col2':[2,3,4]})
 
-	# With a given seed, the sample will always draw the same rows. 
-	df4.sample(n=2, random_state = 2)
-	df4.sample(n=2, random_state = 2)
+    # With a given seed, the sample will always draw the same rows. 
+    df4.sample(n=2, random_state=2)
+    df4.sample(n=2, random_state=2)
 
 
 

doc/source/whatsnew/v0.16.1.txt

@@ -20,7 +20,6 @@ Highlights include:
 
 Enhancements
 ~~~~~~~~~~~~
-.. _whatsnew_0161.enhancements.sample:
 
 - Added ``StringMethods.capitalize()`` and ``swapcase`` which behave as the same as standard ``str`` (:issue:`9766`)
 - Added ``StringMethods`` (.str accessor) to ``Index`` (:issue:`9068`)
@@ -136,10 +135,12 @@ values NOT in the categories, similarly to how you can reindex ANY pandas index.
 
 See the :ref:`documentation <advanced.categoricalindex>` for more. (:issue:`7629`)
 
+.. _whatsnew_0161.enhancements.sample:
+
 Sample
 ^^^^^^^^^^^^^^^^
 
-Series, DataFrames, and Panels now have a new method: :meth:`~pandas.core.sample`.
+Series, DataFrames, and Panels now have a new method: :meth:`~pandas.DataFrame.sample`.
 The method accepts a specific number of rows or columns to return, or a fraction of the 
 total number or rows or columns. It also has options for sampling with or without replacement, 
 for passing in a column for weights for non-uniform sampling, and for setting seed values to facilitate replication. 
@@ -148,23 +149,23 @@ for passing in a column for weights for non-uniform sampling, and for setting se
 
    example_series = Series([0,1,2,3,4,5])
 
-   # When no arguments are passed, returns 5 rows like .head() or .tail()
+   # When no arguments are passed, returns 1
    example_series.sample()
 
    # One may specify either a number of rows:
-   example_series.sample(n = 3)
+   example_series.sample(n=3)
 
    # Or a fraction of the rows:
-   example_series.sample(frac = 0.5)
+   example_series.sample(frac=0.5)
 
    # weights are accepted. 
    example_weights = [0, 0, 0.2, 0.2, 0.2, 0.4]
-   example_series.sample(n=3, weights = example_weights)
+   example_series.sample(n=3, weights=example_weights)
 
    # weights will also be normalized if they do not sum to one, 
    # and missing values will be treated as zeros. 
    example_weights2 = [0.5, 0, 0, 0, None, np.nan]
-   example_series.sample(n=1, weights = example_weights2)
+   example_series.sample(n=1, weights=example_weights2)
 
 
 When applied to a DataFrame, one may pass the name of a column to specify sampling weights,
@@ -173,7 +174,7 @@ although note that the value of the weights column must sum to one.
 .. ipython :: python
 
    df = DataFrame({'col1':[9,8,7,6], 'weight_column':[0.5, 0.4, 0.1, 0]})
-   df.sample(n = 3, weights = 'weight_column')
+   df.sample(n=3, weights='weight_column')
 
 .. _whatsnew_0161.api:
 

pandas/core/generic.py

@@ -1959,7 +1959,7 @@ def sample(self, n=None, frac=None, replace=False, weights=None, random_state=No
             Number of rows to return. Cannot be used with `frac`.
             Default = 1 if `frac` = None. 
         frac : float, optional
-            Share of rows to return. Cannot be used with `n`. 
+            Fraction of rows to return. Cannot be used with `n`. 
         replace : boolean, optional
             Sample with or without replacement. Default = False. 
         weights : str or ndarray-like, optional
@@ -2010,7 +2010,7 @@ def sample(self, n=None, frac=None, replace=False, weights=None, random_state=No
                     try:
                         weights = self[weights]
                     except KeyError:
-                        raise KeyError("String passed to weights not a valid column name")
+                        raise KeyError("String passed to weights not a valid name for an item in specified axis")
 
                 else:
                     raise ValueError("Strings cannot be passed as weights when sampling from a Series.")
@@ -2022,8 +2022,7 @@ def sample(self, n=None, frac=None, replace=False, weights=None, random_state=No
             if len(weights) != axis_length:
                 raise ValueError("Weights and axis to be sampled must be of same length")
 
-            # No infs allowed. The np.nan_to_num() command below would make these large values
-            # which is pretty unintuitive. 
+            # No infs allowed.
             if (weights == np.inf).any() or (weights == -np.inf).any():
                 raise ValueError("weight vector may not include `inf` values")