diff options
Diffstat (limited to 'numpy/lib/arraysetops.py')
| -rw-r--r-- | numpy/lib/arraysetops.py | 98 |
1 files changed, 72 insertions, 26 deletions
diff --git a/numpy/lib/arraysetops.py b/numpy/lib/arraysetops.py index c5e7822f2..b1a730efa 100644 --- a/numpy/lib/arraysetops.py +++ b/numpy/lib/arraysetops.py @@ -46,23 +46,45 @@ def ediff1d(ary, to_end=None, to_begin=None): ---------- ary : array This array will be flattened before the difference is taken. - to_end : number, optional - If provided, this number will be tacked onto the end of the returned + to_end : array_like, optional + If provided, this number will be appended to the end of the returned differences. - to_begin : number, optional - If provided, this number will be taked onto the beginning of the + to_begin : array_like, optional + If provided, this array will be appended to the beginning of the returned differences. Returns ------- ed : array - The differences. Loosely, this will be (ary[1:] - ary[:-1]). + The differences. Loosely, this will be ``ary[1:] - ary[:-1]``. + + See Also + -------- + diff, gradient Notes ----- When applied to masked arrays, this function drops the mask information if the `to_begin` and/or `to_end` parameters are used + Examples + -------- + >>> x = np.array([1, 2, 4, 7, 0]) + >>> np.ediff1d(x) + array([ 1, 2, 3, -7]) + + >>> np.ediff1d(x, to_begin=-99, to_end=np.array([88, 99])) + array([-99, 1, 2, 3, -7, 88, 99]) + + The returned array is always 1D. + + >>> y = np.array([[1, 2, 4], [1, 6, 24]]) + >>> y + array([[ 1, 2, 4], + [ 1, 6, 24]]) + >>> np.ediff1d(y) + array([ 1, 2, -3, 5, 18]) + """ ary = np.asanyarray(ary).flat ed = ary[1:] - ary[:-1] @@ -168,28 +190,41 @@ def unique1d(ar1, return_index=False, return_inverse=False): def intersect1d(ar1, ar2): """ - Intersection returning repeated or unique elements common to both arrays. + Find elements that are common to two arrays. + + For speed, it is assumed the two input arrays do not have any + repeated elements. To find the intersection of two arrays that + have repeated elements, use `intersect1d_nu`. Parameters ---------- ar1,ar2 : array_like - Input arrays. + Input arrays. These must be 1D and must not have repeated elements. Returns ------- out : ndarray, shape(N,) - Sorted 1D array of common elements with repeating elements. + Sorted array of common elements. See Also -------- - intersect1d_nu : Returns only unique common elements. + intersect1d_nu : Find the intersection for input arrays with + repeated elements. numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Examples -------- - >>> np.intersect1d([1,3,3],[3,1,1]) - array([1, 1, 3, 3]) + >>> np.intersect1d([1, 2, 3], [2, 3, 4]) + array([2, 3]) + >>> np.intersect1d(['a','b','c'], ['b','c','d']) + array(['b', 'c'], + dtype='|S1') + + This function fails if the input arrays have repeated elements. + + >>> np.intersect1d([1, 1, 2, 3, 3, 4], [1, 4]) + array([1, 1, 3, 4]) """ aux = np.concatenate((ar1,ar2)) @@ -198,7 +233,11 @@ def intersect1d(ar1, ar2): def intersect1d_nu(ar1, ar2): """ - Intersection returning unique elements common to both arrays. + Find elements common to two arrays. + + Returns an array of unique elements that represents the intersection + of the two input arrays. Unlike `intersect1d`, the input arrays can + have repeated elements. Parameters ---------- @@ -208,17 +247,18 @@ def intersect1d_nu(ar1, ar2): Returns ------- out : ndarray, shape(N,) - Sorted 1D array of common and unique elements. + Sorted 1D array of common, unique elements. See Also -------- - intersect1d : Returns repeated or unique common elements. + intersect1d : Faster version of `intersect1d_nu` for 1D input arrays + without repeated elements. numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Examples -------- - >>> np.intersect1d_nu([1,3,3],[3,1,1]) + >>> np.intersect1d_nu([1, 3 ,3], [3, 3, 1, 1]) array([1, 3]) """ @@ -265,43 +305,49 @@ def setxor1d(ar1, ar2): def setmember1d(ar1, ar2): """ - Return a boolean array set True where first element is in second array. + Test whether elements of one array are also present in a second array. - Boolean array is the shape of `ar1` containing True where the elements - of `ar1` are in `ar2` and False otherwise. - - Use unique1d() to generate arrays with only unique elements to use as - inputs to this function. + Returns a boolean array the same length as `ar1` that is True where an + element of `ar1` is also in `ar2` and False otherwise. The input arrays + must not contain any repeated elements. If they do, unique arrays can + be created using `unique1d()` to use as inputs to this function. Parameters ---------- ar1 : array_like - Input array. + Input array. It must not have any repeated elements ar2 : array_like - Input array. + Input array. Again, it must not have any repeated elements. Returns ------- mask : ndarray, bool The values `ar1[mask]` are in `ar2`. - See Also -------- setmember1d_nu : Works for arrays with non-unique elements. numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. + unique1d : Find unique elements in an array. Examples -------- - >>> test = np.arange(5) + >>> test = [0, 1, 2, 3, 4, 5] >>> states = [0, 2] - >>> mask = np.setmember1d(test,states) + >>> mask = np.setmember1d(test, states) >>> mask array([ True, False, True, False, False], dtype=bool) >>> test[mask] array([0, 2]) + This function fails if there are repeated elements in the input arrays: + + >>> test = [0, 1, 1, 2, 3, 3] + >>> states = [0, 2] + >>> np.setmember1d(test,states) + array([ True, True, False, True, True, False], dtype=bool) # Wrong! + """ # We need this to be a stable sort, so always use 'mergesort' here. The # values from the first array should always come before the values from the |