DOC, TST: Add more tests for mode()

Updates documentation to describe the "values"
parameter in the signature.

Adds tests for properly identifying the mode in a
np.uint64 array. The algorithm currently will
convert uint64 to int64, but that is not an issue
since all elements in the uint64 range are unique
in int64 as well. In addition, the result is
ultimately cast to the correct type at the end.

Author: gfyoung

pandas/core/algorithms.py

@@ -540,7 +540,19 @@ def duplicated(values, keep='first'):
 
 
 def mode(values):
-    """Returns the mode or mode(s) of the passed Series or ndarray (sorted)"""
+    """
+    Returns the mode(s) of an array.
+
+    Parameters
+    ----------
+    values : array-like
+        Array over which to check for duplicate values.
+
+    Returns
+    -------
+    mode : Series
+    """
+
     # must sort because hash order isn't necessarily defined.
     from pandas.core.series import Series
 
@@ -553,6 +565,9 @@ def mode(values):
 
     dtype = values.dtype
     if is_integer_dtype(values):
+        # This also works if dtype is uint64 because there is a 1-1
+        # correspondence between int64 and uint64, and we will cast
+        # all elements back to their correct uint64 values.
         values = _ensure_int64(values)
         result = constructor(sorted(htable.mode_int64(values)), dtype=dtype)
 

pandas/tests/test_algos.py

@@ -1211,6 +1211,20 @@ def test_int64_add_overflow():
                                        b_mask=np.array([False, True]))
 
 
+def test_mode_uint64():
+    s = Series([1, 2**63, 2**63], dtype=np.uint64)
+    exp = Series([2**63], dtype=np.uint64)
+
+    tm.assert_series_equal(algos.mode(s), exp)
+    tm.assert_series_equal(s.mode(), exp)
+
+    s = Series([1, 2**63], dtype=np.uint64)
+    exp = Series([], dtype=np.uint64)
+
+    tm.assert_series_equal(algos.mode(s), exp)
+    tm.assert_series_equal(s.mode(), exp)
+
+
 if __name__ == '__main__':
     import nose
     nose.runmodule(argv=[__file__, '-vvs', '-x', '--pdb', '--pdb-failure'],