Updates to sinhrks comments,test for _random_state

Author: Nick Eubank

doc/source/api.rst

@@ -714,7 +714,6 @@ Indexing, iteration
    DataFrame.where
    DataFrame.mask
    DataFrame.query
-   DataFrame.sample
 
 For more information on ``.at``, ``.iat``, ``.ix``, ``.loc``, and
 ``.iloc``,  see the :ref:`indexing documentation <indexing>`.
@@ -1074,6 +1073,7 @@ Reindexing / Selection / Label manipulation
    Panel.reindex_axis
    Panel.reindex_like
    Panel.rename
+   Panel.sample
    Panel.select
    Panel.take
    Panel.truncate

doc/source/whatsnew/v0.16.1.txt

@@ -11,11 +11,12 @@ Highlights include:
 
 - Support for a ``CategoricalIndex``, a category based index, see :ref:`here <whatsnew_0161.enhancements.categoricalindex>`
 
+- New method ``sample`` for drawing random samples from Series, DataFrames and Panels. See :ref:`here <whatsnew_0161.enchancements.sample>` 
+
 .. contents:: What's new in v0.16.1
     :local:
     :backlinks: none
 
-
 .. _whatsnew_0161.enhancements:
 
 Enhancements

pandas/core/common.py

@@ -3320,17 +3320,18 @@ def _maybe_match_name(a, b):
         return a_name
     return None
 
-def _random_state(state):
+def _random_state(state=None):
     """
     Helper function for processing random_state arguments. 
  
     Parameters
     ----------
-    state : int, np.random.RandomState, None
+    state : int, np.random.RandomState, None. 
         If receives an int, passes to np.random.RandomState() as seed.
         If receives an np.random.RandomState object, just returns object.
         If receives `None`, returns an np.random.RandomState object. 
         If receives anything else, raises an informative ValueError.
+        Default None.
         
     Returns
     -------

pandas/core/generic.py

@@ -1951,15 +1951,15 @@ def tail(self, n=5):
 
     def sample(self, n=None, frac=None, replace=False, weights=None, random_state=None, axis = 0):
         """
-        Returns a random sample of rows from object. 
+        Returns a random sample of items from an axis of object. 
         
         Parameters
         ----------
         n : int, optional
-            Number of rows to return. Cannot be used with `frac`.
+            Number of items from axis to return. Cannot be used with `frac`.
             Default = 1 if `frac` = None. 
         frac : float, optional
-            Fraction of rows to return. Cannot be used with `n`. 
+            Fraction of axis items to return. Cannot be used with `n`. 
         replace : boolean, optional
             Sample with or without replacement. Default = False. 
         weights : str or ndarray-like, optional

pandas/tests/test_common.py

@@ -524,6 +524,26 @@ def test_is_recompilable():
     for f in fails:
         assert not com.is_re_compilable(f)
 
+def test_random_state():
+    import numpy.random as npr
+    # Check with seed
+    state = com._random_state(5)
+    assert_equal(state.uniform(), npr.RandomState(5).uniform())
+    
+    # Check with random state object
+    state2 = npr.RandomState(10)
+    assert_equal(com._random_state(state2).uniform(), npr.RandomState(10).uniform())    
+    
+    # check with no arg random state
+    assert isinstance(com._random_state(), npr.RandomState)
+    
+    # Error for floats or strings
+    with tm.assertRaises(ValueError):
+        com._random_state('test')
+
+    with tm.assertRaises(ValueError):
+        com._random_state(5.5)
+
 
 class TestTake(tm.TestCase):
     # standard incompatible fill error