DOC: Improved the docstring of pandas.Series.filter

Author: ottiP

pandas/core/generic.py

@@ -3525,46 +3525,45 @@ def filter(self, items=None, like=None, regex=None, axis=None):
         Parameters
         ----------
         items : list-like
-            List of info axis to restrict to (must not all be present)
+            List of info axis to restrict to (must not all be present).
         like : string
-            Keep info axis where "arg in col == True"
+            Keep info axis where "arg in col == True".
         regex : string (regular expression)
-            Keep info axis with re.search(regex, col) == True
+            Keep info axis with re.search(regex, col) == True.
         axis : int or string axis name
             The axis to filter on.  By default this is the info axis,
-            'index' for Series, 'columns' for DataFrame
+            'index' for Series, 'columns' for DataFrame.
 
         Returns
         -------
         same type as input object
 
         Examples
         --------
-        >>> df
-        one  two  three
-        mouse     1    2      3
-        rabbit    4    5      6
+        >>> df = pd.DataFrame(np.array(([1,2,3],[4,5,6])),
+        ...                   index=['mouse', 'rabbit'],
+        ...                   columns=['one', 'two', 'three'])
 
         >>> # select columns by name
         >>> df.filter(items=['one', 'three'])
-        one  three
+                 one  three
         mouse     1      3
         rabbit    4      6
 
         >>> # select columns by regular expression
         >>> df.filter(regex='e$', axis=1)
-        one  three
+                 one  three
         mouse     1      3
         rabbit    4      6
 
         >>> # select rows containing 'bbi'
         >>> df.filter(like='bbi', axis=0)
-        one  two  three
+                 one  two  three
         rabbit    4    5      6
 
         See Also
         --------
-        pandas.DataFrame.loc
+        pandas.DataFrame.loc : Purely label-location based indexer for selection by label.
 
         Notes
         -----
@@ -3794,6 +3793,19 @@ def sample(self, n=None, frac=None, replace=False, weights=None,
         40  0.823173 -0.078816  1.009536  1.015108
         15  1.421154 -0.055301 -1.922594 -0.019696
         6  -0.148339  0.832938  1.787600 -1.383767
+        
+        You can use `random state` for reproducibility:
+        
+        >>> df.sample(random_state=1)
+                   A         B         C         D
+        37 -2.027662  0.103611  0.237496 -0.165867
+        43 -0.259323 -0.583426  1.516140 -0.479118
+        12 -1.686325 -0.579510  0.985195 -0.460286
+        8   1.167946  0.429082  1.215742 -1.636041
+        9   1.197475 -0.864188  1.554031 -1.505264
+
+
+
         """
 
         if axis is None: