ENH: add data hashing routines

xref dask/dask#1807

Author: jreback

doc/source/whatsnew/v0.19.2.txt

@@ -16,6 +16,14 @@ Highlights include:
     :backlinks: none
 
 
+.. _whatsnew_0192.enhancements:
+
+Enhancements
+~~~~~~~~~~~~
+
+- ``Series/DataFrame/Index`` gain a ``.hash()`` method to provide a data hash (:issue:`14729`)
+
+
 .. _whatsnew_0192.performance:
 
 Performance Improvements

pandas/core/base.py

@@ -795,7 +795,53 @@ def __unicode__(self):
         return "%s(%s, dtype='%s')" % (type(self).__name__, prepr, self.dtype)
 
 
-class IndexOpsMixin(object):
+class HashableMixin(object):
+    """ provide methods for hashable pandas objects """
+
+    def hash(self, index=True):
+        """
+        Return a data hash of the Series/DataFrame
+        This is a 1-d array of unique hashses of all of the elements in that
+        row, including the Index if desired.
+
+        Parameters
+        ----------
+        index : boolean, default True
+            include the index in the hash (if Series/DataFrame)
+
+        Returns
+        -------
+        1d uint64 numpy array of hash values, same length as the
+        object
+
+        Examples
+        --------
+        >>> pd.Index([1, 2, 3]).hash()
+        array([6238072747940578789, 15839785061582574730,
+               2185194620014831856], dtype=uint64)
+
+        >>>  pd.Series([1, 2, 3]).hash()
+        array([267474170112184751, 16863939785269199747,
+               3948624847917518682], dtype=uint64)
+
+        >>> pd.Series([1, 2, 3]).hash(index=False)
+        array([6238072747940578789, 15839785061582574730,
+               2185194620014831856], dtype=uint64)
+
+        >>> pd.DataFrame({'A': [1, 2, 3]}).hash()
+        array([267474170112184751, 16863939785269199747,
+               3948624847917518682], dtype=uint64)
+
+        >>> pd.DataFrame({'A': [1, 2, 3], 'B': ['foo', 'bar', 'baz']}).hash()
+        array([10443389771536978168, 14762841401800935363,
+               9751253963311919054], dtype=uint64)
+
+        """
+        from pandas.tools.hashing import hash_pandas_object
+        return hash_pandas_object(self, index=index)
+
+
+class IndexOpsMixin(HashableMixin):
     """ common ops mixin to support a unified inteface / docs for Series /
     Index
     """

pandas/core/frame.py

@@ -201,7 +201,7 @@
 # DataFrame class
 
 
-class DataFrame(NDFrame):
+class DataFrame(NDFrame, base.HashableMixin):
     """ Two-dimensional size-mutable, potentially heterogeneous tabular data
     structure with labeled axes (rows and columns). Arithmetic operations
     align on both row and column labels. Can be thought of as a dict-like

pandas/src/hash.pyx

@@ -0,0 +1,160 @@
+# cython: profile=False
+# Translated from the reference implementation at https://github.com/veorq/SipHash
+
+import cython
+cimport numpy as cnp
+import numpy as np
+from numpy cimport ndarray, uint8_t, uint32_t, uint64_t
+
+from cpython cimport (PyString_Check,
+                      PyBytes_Check,
+                      PyUnicode_Check)
+from libc.stdlib cimport malloc, free
+
+DEF cROUNDS = 2
+DEF dROUNDS = 4
+
+
+def hash_object_array(ndarray[object] arr, object key):
+    """
+    Parameters
+    ----------
+    arr : 1-d object ndarray of objects
+
+    Returns
+    -------
+    1-d uint64 ndarray of hashes
+
+    """
+    cdef:
+        Py_ssize_t i, n
+        ndarray[uint64_t] result
+        bytes data, k
+        uint8_t *kb
+        object val
+
+    k = <bytes>key.encode('utf8')
+    kb = <uint8_t *>k
+    n = len(arr)
+
+    # create an array of bytes
+    cdef uint8_t **vecs = <uint8_t**> malloc(n * sizeof(uint8_t*))
+    cdef uint8_t *lens = <uint8_t*> malloc(n * sizeof(uint8_t))
+
+    for i in range(n):
+        val = arr[i]
+        if PyString_Check(val):
+            data = <bytes>val.encode('utf8')
+        elif PyBytes_Check(val):
+            data = <bytes>val
+        elif PyUnicode_Check(val):
+            data = <bytes>val.encode('utf8')
+        else:
+            # non-strings
+            data = <bytes>str(val).encode('utf8')
+        vecs[i] = data
+        lens[i] = len(data)
+
+    result = np.empty(n, dtype=np.uint64)
+    with nogil:
+        for i in range(n):
+            result[i] = low_level_siphash(vecs[i], lens[i], kb)
+
+    free(vecs)
+    return result
+
+cdef inline uint64_t _rotl(uint64_t x, uint64_t b) nogil:
+    return (x << b) | (x >> (64 - b))
+
+cdef inline void u32to8_le(uint8_t* p, uint32_t v) nogil:
+    p[0] = <uint8_t>(v)
+    p[1] = <uint8_t>(v >> 8)
+    p[2] = <uint8_t>(v >> 16)
+    p[3] = <uint8_t>(v >> 24)
+
+cdef inline void u64to8_le(uint8_t* p, uint64_t v) nogil:
+    u32to8_le(p, <uint32_t>v)
+    u32to8_le(p + 4, <uint32_t>(v >> 32))
+
+cdef inline uint64_t u8to64_le(uint8_t* p) nogil:
+    return (<uint64_t>p[0] |
+            <uint64_t>p[1] <<  8 |
+            <uint64_t>p[2] << 16 |
+            <uint64_t>p[3] << 24 |
+            <uint64_t>p[4] << 32 |
+            <uint64_t>p[5] << 40 |
+            <uint64_t>p[6] << 48 |
+            <uint64_t>p[7] << 56)
+
+cdef inline void _sipround(uint64_t* v0, uint64_t* v1,
+                           uint64_t* v2, uint64_t* v3) nogil:
+    v0[0] += v1[0]
+    v1[0] = _rotl(v1[0], 13)
+    v1[0] ^= v0[0]
+    v0[0] = _rotl(v0[0], 32)
+    v2[0] += v3[0]
+    v3[0] = _rotl(v3[0], 16)
+    v3[0] ^= v2[0]
+    v0[0] += v3[0]
+    v3[0] = _rotl(v3[0], 21)
+    v3[0] ^= v0[0]
+    v2[0] += v1[0]
+    v1[0] = _rotl(v1[0], 17)
+    v1[0] ^= v2[0]
+    v2[0] = _rotl(v2[0], 32)
+
+cpdef uint64_t siphash(bytes data, bytes key) except? 0:
+    if len(key) != 16:
+        raise ValueError(
+            'key should be a 16-byte bytestring, got {!r} (len {})'.format(
+                key, len(key)))
+    return low_level_siphash(data, len(data), key)
+
+@cython.cdivision(True)
+cdef uint64_t low_level_siphash(uint8_t* data, size_t datalen,
+                                uint8_t* key) nogil:
+    cdef uint64_t v0 = 0x736f6d6570736575ULL
+    cdef uint64_t v1 = 0x646f72616e646f6dULL
+    cdef uint64_t v2 = 0x6c7967656e657261ULL
+    cdef uint64_t v3 = 0x7465646279746573ULL
+    cdef uint64_t b
+    cdef uint64_t k0 = u8to64_le(key)
+    cdef uint64_t k1 = u8to64_le(key + 8)
+    cdef uint64_t m
+    cdef int i
+    cdef uint8_t* end = data + datalen - (datalen % sizeof(uint64_t))
+    cdef int left = datalen & 7
+    cdef int left_byte
+
+    b = (<uint64_t>datalen) << 56
+    v3 ^= k1
+    v2 ^= k0
+    v1 ^= k1
+    v0 ^= k0
+
+    while (data != end):
+        m = u8to64_le(data)
+        v3 ^= m
+        for i in range(cROUNDS):
+            _sipround(&v0, &v1, &v2, &v3)
+        v0 ^= m
+
+        data += sizeof(uint64_t)
+
+    for i in range(left-1, -1, -1):
+        b |= (<uint64_t>data[i]) << (i * 8)
+
+    v3 ^= b
+
+    for i in range(cROUNDS):
+        _sipround(&v0, &v1, &v2, &v3)
+
+    v0 ^= b
+    v2 ^= 0xff
+
+    for i in range(dROUNDS):
+        _sipround(&v0, &v1, &v2, &v3)
+
+    b = v0 ^ v1 ^ v2 ^ v3
+
+    return b

pandas/tools/hashing.py

@@ -0,0 +1,91 @@
+"""
+data hash pandas / numpy objects
+"""
+
+import numpy as np
+from pandas import Series
+from pandas import _hash
+from pandas.lib import infer_dtype
+from pandas.types.generic import ABCIndexClass, ABCSeries, ABCDataFrame
+from pandas.types.common import is_categorical_dtype
+
+# 16 byte long hashing key
+_hash_key = '0123456789123456'
+
+def hash_pandas_object(obj, index=True):
+    """
+    Return a data hash of the Index/Series/DataFrame
+
+    Parameters
+    ----------
+    index : boolean, default True
+    include the index in the hash (if Series/DataFrame)
+
+    Returns
+    -------
+    1d uint64 numpy array of hash values, same length as the
+    object
+    """
+
+    def adder(h, hashed_to_add):
+        h = np.multiply(h, np.uint(3), h)
+        return np.add(h, hashed_to_add, h)
+
+    if isinstance(obj, ABCIndexClass):
+        h = hash_array(obj.values).astype('uint64')
+    elif isinstance(obj, ABCSeries):
+        h = hash_array(obj.values).astype('uint64')
+        if index:
+            h = adder(h, hash_pandas_object(obj.index))
+    elif isinstance(obj, ABCDataFrame):
+        cols = obj.iteritems()
+        first_series = next(cols)[1]
+        h = hash_array(first_series.values).astype('uint64')
+        for _, col in cols:
+            h = adder(h, hash_array(col.values))
+        if index:
+            h = adder(h, hash_pandas_object(obj.index))
+    else:
+        raise TypeError("Unexpected type %s" % type(obj))
+    return h
+
+
+def hash_array(vals):
+    """Given a 1d array, return an array of deterministic integers."""
+    # work with cagegoricals as ints. (This check is above the complex
+    # check so that we don't ask numpy if categorical is a subdtype of
+    # complex, as it will choke.
+    if is_categorical_dtype(vals.dtype):
+        vals = vals.codes
+
+    # we'll be working with everything as 64-bit values, so handle this
+    # 128-bit value early
+    if np.issubdtype(vals.dtype, np.complex128):
+        return hash_array(vals.real) + 23 * hash_array(vals.imag)
+
+    # MAIN LOGIC:
+    inferred = infer_dtype(vals)
+
+    # First, turn whatever array this is into unsigned 64-bit ints, if we can
+    # manage it.
+    if inferred == 'boolean':
+        vals = vals.astype('u8')
+
+    if (np.issubdtype(vals.dtype, np.datetime64) or
+       np.issubdtype(vals.dtype, np.timedelta64) or
+       np.issubdtype(vals.dtype, np.number)) and vals.dtype.itemsize <= 8:
+
+        vals = vals.view('u{}'.format(vals.dtype.itemsize)).astype('u8')
+    else:
+
+        # we want to stringify
+        # then apply a consistent hashing scheme
+        vals = _hash.hash_object_array(vals, _hash_key)
+
+    # Then, redistribute these 64-bit ints within the space of 64-bit ints
+    vals ^= vals >> 30
+    vals *= np.uint64(0xbf58476d1ce4e5b9)
+    vals ^= vals >> 27
+    vals *= np.uint64(0x94d049bb133111eb)
+    vals ^= vals >> 31
+    return vals