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 (Union[bool, pdarray]) – 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 (Union[bool, pdarray]) – 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 (Optional[int]) – 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 (Optional[int]) – 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:
Returns:

Indicates if any pdarray element evaluates to True.

Return type:

Union[float, float64, float32, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, bool, pdarray]

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:
Returns:

Indicates if all pdarray elements evaluate to True.

Return type:

Union[float, float64, float32, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, bool, pdarray]

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:
Returns:

Indicates if the array is monotonically non-decreasing.

Return type:

Union[float, float64, float32, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, bool, pdarray]

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:
Returns:

The sum of all elements in the array.

Return type:

Union[float, float64, float32, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, bool, pdarray]

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:
Returns:

The product calculated from the pda.

Return type:

Union[float, float64, float32, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, bool, pdarray]

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:
Returns:

The min calculated from the pda.

Return type:

Union[float, float64, float32, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, bool, pdarray]

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:
Returns:

The max calculated from the pda.

Return type:

Union[float, float64, float32, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, bool, pdarray]

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 (Union[int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, 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) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

This argmin of the array.

Return type:

Union[uint64, int64, pdarray]

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 (Union[int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, 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) – Whether to keep the singleton dimension(s) along axis in the result.

Returns:

This argmax of the array.

Return type:

Union[uint64, int64, pdarray]

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:
Returns:

The product calculated from the pda.

Return type:

Union[float, float64, float32, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, bool, 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:
Returns:

The product calculated from the pda.

Return type:

Union[float64, float32, int8, int16, int32, int64, bool, str_, uint8, uint16, uint32, uint64, 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:
Returns:

The product calculated from the pda.

Return type:

Union[float64, float32, int8, int16, int32, int64, bool, str_, uint8, uint16, uint32, uint64, 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:
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:
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.

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.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:
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.

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 degradation has been observed.

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:
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.

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 degradation has been observed.

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]
Overloads:

  • condition (pdarray), A (Union[numeric_and_bool_scalars, pdarray]), B (Union[numeric_and_bool_scalars, pdarray]) → pdarray

  • condition (pdarray), A (Union[str_scalars, Strings]), B (Union[str_scalars, Strings]) → Strings

  • condition (pdarray), A (Categorical), B (Categorical) → Categorical

  • condition (bool_scalars), A (numeric_and_bool_scalars), B (numeric_and_bool_scalars) → numeric_and_bool_scalars

  • condition (bool_scalars), A (pdarray), B (Union[numeric_and_bool_scalars, pdarray]) → pdarray

  • condition (bool_scalars), A (Union[numeric_and_bool_scalars, pdarray]), B (pdarray) → pdarray

  • condition (bool_scalars), A (str_scalars), B (str_scalars) → str_scalars

  • condition (bool_scalars), A (Strings), B (Union[str_scalars, Strings]) → Strings

  • condition (bool_scalars), A (Union[str_scalars, Strings]), B (Strings) → Strings

  • condition (bool_scalars), A (Categorical), B (Categorical) → Categorical

  • condition (pdarray), A (Union[str_scalars, numeric_and_bool_scalars, pdarray, Strings, Categorical]), B (Union[str_scalars, numeric_and_bool_scalars, pdarray, Strings, Categorical]) → Union[str_scalars, numeric_and_bool_scalars, pdarray, Strings, Categorical]

  • condition (bool_scalars), A (Union[str_scalars, numeric_and_bool_scalars, pdarray, Strings, Categorical]), B (Union[str_scalars, numeric_and_bool_scalars, pdarray, Strings, Categorical]) → Union[str_scalars, numeric_and_bool_scalars, pdarray, Strings, Categorical]

Return values chosen from x and y depending on condition.

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.