Arithmetic and Numeric Operations¶

Vector and Scalar Arithmetic¶

A large subset of Python’s binary and in-place operators are supported on pdarray objects. Where supported, the behavior of these operators is identical to that of NumPy ndarray objects.

>>> A = ak.arange(10)
>>> A += 2
>>> A
array([2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
>>> A + A
array([4, 6, 8, 10, 12, 14, 16, 18, 20, 22])
>>> 2 * A
array([4, 6, 8, 10, 12, 14, 16, 18, 20, 22])
>>> A == A
array([True, True, True, True, True, True, True, True, True, True])

Operations that are not implemented will raise a RuntimeError. In-place operations that would change the dtype of the pdarray are not implemented.

Element-wise Functions¶

Arrays support several mathematical functions that operate element-wise and return a pdarray of the same length.

arkouda.abs(pda)[source]¶

Return the element-wise absolute value of the array.

Parameters:: pda (pdarray)
Returns:: A pdarray containing absolute values of the input array elements
Return type:: pdarray
Raises:: TypeError – Raised if the parameter is not a pdarray

Examples

>>> import arkouda as ak
>>> ak.abs(ak.arange(-5,-1))
array([5 4 3 2])

>>> ak.abs(ak.linspace(-5,-1,5))
array([5.00000000... 4.00000000... 3.00000000...
2.00000000... 1.00000000...])

arkouda.log(pda)[source]¶

Return the element-wise natural log of the array.

Parameters:: pda (pdarray)
Returns:: A pdarray containing natural log values of the input array elements
Return type:: pdarray
Raises:: TypeError – Raised if the parameter is not a pdarray

Notes

Logarithms with other bases can be computed as follows:

Examples

>>> import arkouda as ak
>>> A = ak.array([1, 10, 100])

Natural log >>> ak.log(A) array([0.00000000… 2.30258509… 4.60517018…])

Log base 10 >>> ak.log(A) / np.log(10) array([0.00000000… 1.00000000… 2.00000000…])

Log base 2 >>> ak.log(A) / np.log(2) array([0.00000000… 3.32192809… 6.64385618…])

arkouda.exp(pda)[source]¶

Return the element-wise exponential of the array.

Parameters:: pda (pdarray)
Returns:: A pdarray containing exponential values of the input array elements
Return type:: pdarray
Raises:: TypeError – Raised if the parameter is not a pdarray

Examples

>>> import arkouda as ak
>>> ak.exp(ak.arange(1,5))
array([2.71828182... 7.38905609... 20.0855369... 54.5981500...])

>>> ak.exp(ak.uniform(4, 1.0, 5.0, seed=1))
array([63.3448620... 3.80794671... 54.7254287... 36.2344168...])

arkouda.sin(pda, where=True)[source]¶

Return the element-wise sine of the array.

Parameters:

pda (pdarray)
where (bool or pdarray, default=True) – This condition is broadcast over the input. At locations where the condition is True, the sine will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True.

Returns:

A pdarray containing sin for each element of the original pdarray

Return type:

pdarray

Raises:

TypeError – Raised if the parameter is not a pdarray

Examples

>>> import arkouda as ak
>>> a = ak.linspace(-1.5,0.75,4)
>>> ak.sin(a)
array([-0.99749498... -0.68163876... 0.00000000... 0.68163876...])

arkouda.cos(pda, where=True)[source]¶

Return the element-wise cosine of the array.

Parameters:

pda (pdarray)
where (bool or pdarray, default=True) – This condition is broadcast over the input. At locations where the condition is True, the cosine will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True.

Returns:

A pdarray containing cosine for each element of the original pdarray

Return type:

pdarray

Raises:

TypeError – Raised if the parameter is not a pdarray

Examples

>>> import arkouda as ak
>>> a = ak.linspace(-1.5,0.75,4)
>>> ak.cos(a)
array([0.07073720... 0.73168886... 1.00000000... 0.73168886...])

Scans¶

Scans perform a cumulative reduction over a pdarray, returning a pdarray of the same size.

arkouda.cumsum(pda)[source]¶

Return the cumulative sum over the array.

The sum is inclusive, such that the i th element of the result is the sum of elements up to and including i.

Parameters:: pda (pdarray)
Returns:: A pdarray containing cumulative sums for each element of the original pdarray
Return type:: pdarray
Raises:: TypeError – Raised if the parameter is not a pdarray

Examples

>>> import arkouda as ak
>>> ak.cumsum(ak.arange(1,5))
array([1 3 6 10])

>>> ak.cumsum(ak.uniform(5,1.0,5.0, seed=1))
array([4.14859379... 5.48568392... 9.48801240... 13.0780218... 16.8202747...])

>>> ak.cumsum(ak.randint(0, 1, 5, dtype=ak.bool_, seed=1))
array([1 1 2 3 4])

arkouda.cumprod(pda)[source]¶

Return the cumulative product over the array.

The product is inclusive, such that the i th element of the result is the product of elements up to and including i.

Parameters:: pda (pdarray)
Returns:: A pdarray containing cumulative products for each element of the original pdarray
Return type:: pdarray
Raises:: TypeError – Raised if the parameter is not a pdarray

Examples

>>> import arkouda as ak
>>> ak.cumprod(ak.arange(1,5))
array([1 2 6 24])

>>> ak.cumprod(ak.uniform(5,1.0,5.0, seed=1))
array([4.14859379... 5.54704379... 22.2010913...
    79.7021268... 298.265515...])

Reductions¶

Reductions return a scalar value.

arkouda.any(pda, axis=None, keepdims=False)¶

Return True iff any element of the array evaluates to True.

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
axis (int or Tuple[int, ...], optional, default = None) – The axis or axes along which to compute the function. If None, the computation is done across the entire array.
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

Indicates if any pdarray element evaluates to True.

Return type:

pdarray or bool

Raises:

TypeError – Raised if pda is not a pdarray instance
RuntimeError – Raised if there’s a server-side error thrown

arkouda.all(pda, axis=None, keepdims=False)¶

Return True iff all elements of the array evaluate to True.

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
axis (int or Tuple[int, ...], optional, default = None) – The axis or axes along which to compute the function. If None, the computation is done across the entire array.
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

Indicates if all pdarray elements evaluate to True.

Return type:

pdarray or bool

Raises:

TypeError – Raised if pda is not a pdarray instance
RuntimeError – Raised if there’s a server-side error thrown

arkouda.is_sorted(pda, axis=None, keepdims=False)¶

Return True iff the array is monotonically non-decreasing.

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
axis (int or Tuple[int, ...], optional, default = None) – The axis or axes along which to compute the function. If None, the computation is done across the entire array.
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

Indicates if the array is monotonically non-decreasing.

Return type:

pdarray or bool

Raises:

TypeError – Raised if pda is not a pdarray instance
RuntimeError – Raised if there’s a server-side error thrown

arkouda.sum(pda, axis=None, keepdims=False)¶

Return the sum of all elements in the array.

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
axis (int or Tuple[int, ...], optional, default = None) – The axis or axes along which to compute the function. If None, the computation is done across the entire array.
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

The sum of all elements in the array.

Return type:

pdarray or float64

Raises:

TypeError – Raised if pda is not a pdarray instance
RuntimeError – Raised if there’s a server-side error thrown

arkouda.prod(pda, axis=None, keepdims=False)¶

Return the product of all elements in the array. Return value is always a np.float64 or np.int64

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
axis (int or Tuple[int, ...], optional, default = None) – The axis or axes along which to compute the function. If None, the computation is done across the entire array.
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

The product calculated from the pda.

Return type:

pdarray or numeric_scalars

Raises:

TypeError – Raised if pda is not a pdarray instance
RuntimeError – Raised if there’s a server-side error thrown

arkouda.min(pda, axis=None, keepdims=False)¶

Return the minimum value of the array.

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
axis (int or Tuple[int, ...], optional, default = None) – The axis or axes along which to compute the function. If None, the computation is done across the entire array.
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

The min calculated from the pda.

Return type:

pdarray or numeric_scalars

Raises:

TypeError – Raised if pda is not a pdarray instance
RuntimeError – Raised if there’s a server-side error thrown

arkouda.max(pda, axis=None, keepdims=False)¶

Return the maximum value of the array.

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
axis (int or Tuple[int, ...], optional, default = None) – The axis or axes along which to compute the function. If None, the computation is done across the entire array.
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

The max calculated from the pda.

Return type:

pdarray or numeric_scalars

Raises:

TypeError – Raised if pda is not a pdarray instance
RuntimeError – Raised if there’s a server-side error thrown

arkouda.argmin(pda, axis=None, keepdims=False)¶

Return the argmin of the array along the specified axis. This is returned as the ordered index.

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
axis (int, optional, default = None) – The axis along which to compute the index reduction. If None, the reduction of the entire array is computed (returning a scalar).
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

This argmin of the array.

Return type:

pdarray or int64, uint64

Raises:

TypeError – Raised if pda is not a pdarray instance. Raised axis is not an int.
RuntimeError – Raised if there’s a server-side error thrown.

arkouda.argmax(pda, axis=None, keepdims=False)¶

Return the argmax of the array along the specified axis. This is returned as the ordered index.

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
axis (int, optional, default = None) – The axis along which to compute the index reduction. If None, the reduction of the entire array is computed (returning a scalar).
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

This argmax of the array.

Return type:

pdarray or int64, uint64

Raises:

TypeError – Raised if pda is not a pdarray instance. Raised axis is not an int.
RuntimeError – Raised if there’s a server-side error thrown.

arkouda.mean(pda, axis=None, keepdims=False)¶

Return the mean of all elements in the array. Return value is always a np.float64 or pdarray

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
axis (int or Tuple[int, ...], optional, default = None) – The axis or axes along which to compute the function. If None, the computation is done across the entire array.
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

The product calculated from the pda.

Return type:

pdarray or numpy_scalars, pdarray

Raises:

TypeError – Raised if pda is not a pdarray instance
RuntimeError – Raised if there’s a server-side error thrown

arkouda.var(pda, ddof=0, axis=None, keepdims=False)¶

Return the variance of all elements in the array. Return value is always a np.float64 or pdarray

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
ddof (the delta degrees of freedom argument for var or std)
axis (int or Tuple[int, ...], optional, default = None) – The axis or axes along which to compute the function. If None, the computation is done across the entire array.
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

The product calculated from the pda.

Return type:

pdarray or numpy_scalars, pdarray

Raises:

TypeError – Raised if pda is not a pdarray instance
RuntimeError – Raised if there’s a server-side error thrown

arkouda.std(pda, ddof=0, axis=None, keepdims=False)¶

Return the standard deviation of all elements in the array. Return value is always a np.float64 or pdarray

Parameters:

pda (pdarray) – The pdarray instance to be evaluated.
ddof (the delta degrees of freedom argument for var or std)
axis (int or Tuple[int, ...], optional, default = None) – The axis or axes along which to compute the function. If None, the computation is done across the entire array.
keepdims (bool, optional, default = False) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

The product calculated from the pda.

Return type:

pdarray or numpy_scalars, pdarray

Raises:

TypeError – Raised if pda is not a pdarray instance
RuntimeError – Raised if there’s a server-side error thrown

arkouda.mink(pda, k)[source]¶

Find the k minimum values of an array.

Returns the smallest k values of an array, sorted

Parameters:

pda (pdarray) – Input array.
k (int_scalars) – The desired count of minimum values to be returned by the output.

Returns:

The minimum k values from pda, sorted

Return type:

pdarray

Raises:

TypeError – Raised if pda is not a pdarray
ValueError – Raised if the pda is empty, or pda.ndim > 1, or k < 1

Notes

This call is equivalent in value to a[ak.argsort(a)[:k]] and generally outperforms this operation.

This reduction will see a significant drop in performance as k grows beyond a certain value. This value is system dependent, but generally about a k of 5 million is where performance degredation has been observed.

Examples

>>> import arkouda as ak
>>> A = ak.array([10,5,1,3,7,2,9,0])
>>> ak.mink(A, 3)
array([0 1 2])
>>> ak.mink(A, 4)
array([0 1 2 3])

arkouda.maxk(pda, k)[source]¶

Find the k maximum values of an array.

Returns the largest k values of an array, sorted

Parameters:

pda (pdarray) – Input array.
k (int_scalars) – The desired count of maximum values to be returned by the output.

Returns:

The maximum k values from pda, sorted

Return type:

pdarray

Raises:

TypeError – Raised if pda is not a pdarray or k is not an integer
ValueError – Raised if the pda is empty, or pda.ndim > 1, or k < 1

Notes

This call is equivalent in value to a[ak.argsort(a)[k:]]

and generally outperforms this operation.

Examples

>>> import arkouda as ak
>>> A = ak.array([10,5,1,3,7,2,9,0])
>>> ak.maxk(A, 3)
array([7 9 10])
>>> ak.maxk(A, 4)
array([5 7 9 10])

arkouda.argmink(pda, k)[source]¶

Finds the indices corresponding to the k minimum values of an array.

Parameters:

pda (pdarray) – Input array.
k (int_scalars) – The desired count of indices corresponding to minimum array values

Returns:

The indices of the minimum k values from the pda, sorted

Return type:

pdarray

Raises:

TypeError – Raised if pda is not a pdarray or k is not an integer
ValueError – Raised if the pda is empty, or pda.ndim > 1, or k < 1

Notes

This call is equivalent in value to ak.argsort(a)[:k] and generally outperforms this operation.

Examples

>>> import arkouda as ak
>>> A = ak.array([10,5,1,3,7,2,9,0])
>>> ak.argmink(A, 3)
array([7 2 5])
>>> ak.argmink(A, 4)
array([7 2 5 3])

arkouda.argmaxk(pda, k)[source]¶

Find the indices corresponding to the k maximum values of an array.

Returns the largest k values of an array, sorted

Parameters:

pda (pdarray) – Input array.
k (int_scalars) – The desired count of indices corresponding to maxmum array values

Returns:

The indices of the maximum k values from the pda, sorted

Return type:

pdarray

Raises:

TypeError – Raised if pda is not a pdarray or k is not an integer
ValueError – Raised if the pda is empty, or pda.ndim > 1, or k < 1

Notes

This call is equivalent in value to ak.argsort(a)[k:] and generally outperforms this operation.

Examples

>>> import arkouda as ak
>>> A = ak.array([10,5,1,3,7,2,9,0])
>>> ak.argmaxk(A, 3)
array([4 6 0])
>>> ak.argmaxk(A, 4)
array([1 4 6 0])

Where¶

The where function is a way to multiplex two pdarray (or a pdarray and a scalar) based on a condition:

arkouda.where(condition, A, B)[source]¶

Return an array with elements chosen from A and B based upon a conditioning array. As is the case with numpy.where, the return array consists of values from the first array (A) where the conditioning array elements are True and from the second array (B) where the conditioning array elements are False.

Parameters:

condition (pdarray) – Used to choose values from A or B
A (str, numeric_scalars, pdarray, Strings, or Categorical) – Value(s) used when condition is True
B (str, numeric_scalars, pdarray, Strings, or Categorical) – Value(s) used when condition is False

Returns:

Values chosen from A where the condition is True and B where the condition is False

Return type:

pdarray

Raises:

TypeError – Raised if the condition object is not a pdarray, if A or B is not an int, np.int64, float, np.float64, bool, pdarray, str, Strings, Categorical if pdarray dtypes are not supported or do not match, or multiple condition clauses (see Notes section) are applied
ValueError – Raised if the shapes of the condition, A, and B pdarrays are unequal

Examples

>>> import arkouda as ak
>>> a1 = ak.arange(1,10)
>>> a2 = ak.ones(9, dtype=np.int64)
>>> cond = a1 < 5
>>> ak.where(cond,a1,a2)
array([1 2 3 4 1 1 1 1 1])

>>> a1 = ak.arange(1,10)
>>> a2 = ak.ones(9, dtype=np.int64)
>>> cond = a1 == 5
>>> ak.where(cond,a1,a2)
array([1 1 1 1 5 1 1 1 1])

>>> a1 = ak.arange(1,10)
>>> a2 = 10
>>> cond = a1 < 5
>>> ak.where(cond,a1,a2)
array([1 2 3 4 10 10 10 10 10])

>>> s1 = ak.array([f'str {i}' for i in range(10)])
>>> s2 = 'str 21'
>>> cond = (ak.arange(10) % 2 == 0)
>>> ak.where(cond,s1,s2)
array(['str 0', 'str 21', 'str 2', 'str 21', 'str 4',
'str 21', 'str 6', 'str 21', 'str 8', 'str 21'])

>>> c1 = ak.Categorical(ak.array([f'str {i}' for i in range(10)]))
>>> c2 = ak.Categorical(ak.array([f'str {i}' for i in range(9, -1, -1)]))
>>> cond = (ak.arange(10) % 2 == 0)
>>> ak.where(cond,c1,c2)
array(['str 0', 'str 8', 'str 2', 'str 6', 'str 4',
'str 4', 'str 6', 'str 2', 'str 8', 'str 0'])

Notes

A and B must have the same dtype and only one conditional clause is supported e.g., n < 5, n > 1, which is supported in numpy is not currently supported in Arkouda