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, axis=None)[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)
axis (int, optional) – the axis along which to compute the sum

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
ValueError – Raised if an invalid axis is given

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, 2, 5, dtype=ak.bool_, seed=1))
array([1 1 2 3 4])

arkouda.cumprod(pda, axis=None)[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)
axis (int, optional) – the axis along which to compute the product

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
ValueError – Raised if an invalid axis is given

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.20109135... 79.7021268... 298.2655159...])

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

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, x, y)[source]¶

Return values chosen from x and y depending on condition.

Return type:: Union[str, str_, bool, bool, float, float64, float32, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, pdarray, Strings, Categorical]

Broadcasting rules (NumPy-style): - If condition is a boolean pdarray, the output shape is the broadcasted

shape of condition and any array-like operands among x and y.

If condition is a scalar bool:
- if any operand is array-like, broadcast the condition to the broadcasted shape of the array-like operands and return an array-like result
- if both operands are scalars, return a scalar

Notes

For numeric/bool pdarray inputs, Arkouda requires matching dtypes between array operands (server-side constraint).
Broadcasting is performed for pdarray operands via broadcast_to.
Strings and Categorical are treated as 1D; we validate broadcast compatibility but do not currently broadcast these objects.