arkouda.numeric =============== .. py:module:: arkouda.numeric Classes ------- .. autoapisummary:: arkouda.numeric.ErrorMode Functions --------- .. autoapisummary:: arkouda.numeric.abs arkouda.numeric.arccos arkouda.numeric.arccosh arkouda.numeric.arcsin arkouda.numeric.arcsinh arkouda.numeric.arctan arkouda.numeric.arctan2 arkouda.numeric.arctanh arkouda.numeric.array_equal arkouda.numeric.cast arkouda.numeric.ceil arkouda.numeric.clip arkouda.numeric.cos arkouda.numeric.cosh arkouda.numeric.count_nonzero arkouda.numeric.cumprod arkouda.numeric.cumsum arkouda.numeric.deg2rad arkouda.numeric.exp arkouda.numeric.expm1 arkouda.numeric.eye arkouda.numeric.floor arkouda.numeric.hash arkouda.numeric.histogram arkouda.numeric.histogram2d arkouda.numeric.histogramdd arkouda.numeric.isfinite arkouda.numeric.isinf arkouda.numeric.isnan arkouda.numeric.log arkouda.numeric.log10 arkouda.numeric.log1p arkouda.numeric.log2 arkouda.numeric.matmul arkouda.numeric.median arkouda.numeric.putmask arkouda.numeric.rad2deg arkouda.numeric.round arkouda.numeric.sign arkouda.numeric.sin arkouda.numeric.sinh arkouda.numeric.square arkouda.numeric.tan arkouda.numeric.tanh arkouda.numeric.transpose arkouda.numeric.tril arkouda.numeric.triu arkouda.numeric.trunc arkouda.numeric.value_counts arkouda.numeric.vecdot arkouda.numeric.where Module Contents --------------- .. py:class:: ErrorMode Bases: :py:obj:`enum.Enum` Generic enumeration. Derive from this class to define new enumerations. .. py:attribute:: ignore :value: 'ignore' .. py:attribute:: return_validity :value: 'return_validity' .. py:attribute:: strict :value: 'strict' .. py:function:: abs(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise absolute value of the array. :param pda: :type pda: pdarray :returns: A pdarray containing absolute values of the input array elements :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Examples >>> ak.abs(ak.arange(-5,-1)) array([5, 4, 3, 2]) >>> ak.abs(ak.linspace(-5,-1,5)) array([5, 4, 3, 2, 1]) .. py:function:: arccos(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise inverse cosine of the array. The result is between 0 and pi. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the inverse cosine will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing inverse cosine for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: arccosh(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise inverse hyperbolic cosine of the array. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the inverse hyperbolic cosine will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing inverse hyperbolic cosine for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: arcsin(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise inverse sine of the array. The result is between -pi/2 and pi/2. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the inverse sine will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing inverse sine for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: arcsinh(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise inverse hyperbolic sine of the array. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the inverse hyperbolic sine will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing inverse hyperbolic sine for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: arctan(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise inverse tangent of the array. The result is between -pi/2 and pi/2. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the inverse tangent will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing inverse tangent for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: arctan2(num: Union[arkouda.pdarrayclass.pdarray, arkouda.numpy.dtypes.numeric_scalars], denom: Union[arkouda.pdarrayclass.pdarray, arkouda.numpy.dtypes.numeric_scalars], where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise inverse tangent of the array pair. The result chosen is the signed angle in radians between the ray ending at the origin and passing through the point (1,0), and the ray ending at the origin and passing through the point (denom, num). The result is between -pi and pi. :param num: Numerator of the arctan2 argument. :type num: Union[numeric_scalars, pdarray] :param denom: Denominator of the arctan2 argument. :type denom: Union[numeric_scalars, pdarray] :param where: This condition is broadcast over the input. At locations where the condition is True, the inverse tangent will be applied to the corresponding values. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing inverse tangent for each corresponding element pair of the original pdarray, using the signed values or the numerator and denominator to get proper placement on unit circle. :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: arctanh(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise inverse hyperbolic tangent of the array. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the inverse hyperbolic tangent will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing inverse hyperbolic tangent for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameters are not a pdarray or numeric scalar. .. py:function:: array_equal(pda_a: arkouda.pdarrayclass.pdarray, pda_b: arkouda.pdarrayclass.pdarray, equal_nan: bool = False) Compares two pdarrays for equality. If neither array has any nan elements, then if all elements are pairwise equal, it returns True. If equal_Nan is False, then any nan element in either array gives a False return. If equal_Nan is True, then pairwise-corresponding nans are considered equal. :param pda_a: :type pda_a: pdarray :param pda_b: :type pda_b: pdarray :param equal_nan: :type equal_nan: boolean to determine how to handle nans, default False :returns: With string data: False if one array is type ak.str_ & the other isn't, True if both are ak.str_ & they match. With numeric data: True if neither array has any nan elements, and all elements pairwise equal. True if equal_Nan True, all non-nans pairwise equal & nans in pda_a correspond to nans in pda_b False if equal_Nan False, & either array has any nan element. :rtype: boolean .. rubric:: Examples >>> a = ak.randint(0,10,10,dtype=ak.float64) >>> b = a >>> ak.array_equal(a,b) True >>> b[9] = np.nan >>> ak.array_equal(a,b) False >>> a[9] = np.nan >>> ak.array_equal(a,b) False >>> ak.array_equal(a,b,True) True .. py:function:: cast(pda: Union[arkouda.pdarrayclass.pdarray, arkouda.strings.Strings, arkouda.categorical.Categorical], dt: Union[numpy.dtype, type, str, arkouda.numpy.dtypes.bigint], errors: ErrorMode = ErrorMode.strict) -> Union[Union[arkouda.pdarrayclass.pdarray, arkouda.strings.Strings, arkouda.categorical.Categorical], Tuple[arkouda.pdarrayclass.pdarray, arkouda.pdarrayclass.pdarray]] Cast an array to another dtype. :param pda: The array of values to cast :type pda: pdarray or Strings :param dt: The target dtype to cast values to :type dt: np.dtype, type, or str :param errors: Controls how errors are handled when casting strings to a numeric type (ignored for casts from numeric types). - strict: raise RuntimeError if *any* string cannot be converted - ignore: never raise an error. Uninterpretable strings get converted to NaN (float64), -2**63 (int64), zero (uint64 and uint8), or False (bool) - return_validity: in addition to returning the same output as "ignore", also return a bool array indicating where the cast was successful. :type errors: {strict, ignore, return_validity} :returns: * *pdarray or Strings* -- Array of values cast to desired dtype * **[validity** (*pdarray(bool)]*) -- If errors="return_validity" and input is Strings, a second array is returned with True where the cast succeeded and False where it failed. .. rubric:: Notes The cast is performed according to Chapel's casting rules and is NOT safe from overflows or underflows. The user must ensure that the target dtype has the precision and capacity to hold the desired result. .. rubric:: Examples >>> ak.cast(ak.linspace(1.0,5.0,5), dt=ak.int64) array([1, 2, 3, 4, 5]) >>> ak.cast(ak.arange(0,5), dt=ak.float64).dtype dtype('float64') >>> ak.cast(ak.arange(0,5), dt=ak.bool_) array([False, True, True, True, True]) >>> ak.cast(ak.linspace(0,4,5), dt=ak.bool_) array([False, True, True, True, True]) .. py:function:: ceil(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise ceiling of the array. :param pda: :type pda: pdarray :returns: A pdarray containing ceiling values of the input array elements :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Examples >>> ak.ceil(ak.linspace(1.1,5.5,5)) array([2, 3, 4, 5, 6]) .. py:function:: clip(pda: arkouda.pdarrayclass.pdarray, lo: Union[arkouda.numpy.dtypes.numeric_scalars, arkouda.pdarrayclass.pdarray], hi: Union[arkouda.numpy.dtypes.numeric_scalars, arkouda.pdarrayclass.pdarray]) -> arkouda.pdarrayclass.pdarray Clip (limit) the values in an array to a given range [lo,hi] Given an array a, values outside the range are clipped to the range edges, such that all elements lie in the range. There is no check to enforce that lo < hi. If lo > hi, the corresponding value of the array will be set to hi. If lo or hi (or both) are pdarrays, the check is by pairwise elements. See examples. :param pda: the array of values to clip :type pda: pdarray, int64 or float64 :param lo: the lower value of the clipping range :type lo: scalar or pdarray, int64 or float64 :param hi: the higher value of the clipping range :type hi: scalar or pdarray, int64 or float64 :param If lo or hi (or both) are pdarrays: See examples. :param the check is by pairwise elements.: See examples. :returns: A pdarray matching pda, except that element x remains x if lo <= x <= hi, or becomes lo if x < lo, or becomes hi if x > hi. :rtype: arkouda.pdarrayclass.pdarray .. rubric:: Examples >>> a = ak.array([1,2,3,4,5,6,7,8,9,10]) >>> ak.clip(a,3,8) array([3,3,3,4,5,6,7,8,8,8]) >>> ak.clip(a,3,8.0) array([3.00000000000000000 3.00000000000000000 3.00000000000000000 4.00000000000000000 5.00000000000000000 6.00000000000000000 7.00000000000000000 8.00000000000000000 8.00000000000000000 8.00000000000000000]) >>> ak.clip(a,None,7) array([1,2,3,4,5,6,7,7,7,7]) >>> ak.clip(a,5,None) array([5,5,5,5,5,6,7,8,9,10]) >>> ak.clip(a,None,None) ValueError : either min or max must be supplied >>> ak.clip(a,ak.array([2,2,3,3,8,8,5,5,6,6],8)) array([2,2,3,4,8,8,7,8,8,8]) >>> ak.clip(a,4,ak.array([10,9,8,7,6,5,5,5,5,5])) array([4,4,4,4,5,5,5,5,5,5]) .. rubric:: Notes Either lo or hi may be None, but not both. If lo > hi, all x = hi. If all inputs are int64, output is int64, but if any input is float64, output is float64. :raises ValueError: Raised if both lo and hi are None .. py:function:: cos(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise cosine of the array. :param pda: :type pda: pdarray :param where: 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. :type where: Boolean or pdarray :returns: A pdarray containing cosine for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: cosh(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise hyperbolic cosine of the array. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the hyperbolic cosine will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing hyperbolic cosine for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: count_nonzero(pda) Compute the nonzero count of a given array. 1D case only, for now. :param pda: The input data, in pdarray form, numeric, bool, or str :type pda: pdarray :returns: The nonzero count of the entire pdarray :rtype: np.int64 .. rubric:: Examples >>> pda = ak.array([0,4,7,8,1,3,5,2,-1]) >>> ak.count_nonzero(pda) 9 >>> pda = ak.array([False,True,False,True,False]) >>> ak.count_nonzero(pda) 3 >>> pda = ak.array(["hello","","there"]) >>> ak.count_nonzero(pda) 2 .. py:function:: cumprod(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray 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``. :param pda: :type pda: pdarray :returns: A pdarray containing cumulative products for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Examples >>> ak.cumprod(ak.arange(1,5)) array([1, 2, 6, 24])) >>> ak.cumprod(ak.uniform(5,1.0,5.0)) array([1.5728783400481925, 7.0472855509390593, 33.78523998586553, 134.05309592737584, 450.21589865655358]) .. py:function:: cumsum(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray 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``. :param pda: :type pda: pdarray :returns: A pdarray containing cumulative sums for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Examples >>> ak.cumsum(ak.arange([1,5])) array([1, 3, 6]) >>> ak.cumsum(ak.uniform(5,1.0,5.0)) array([3.1598310770203937, 5.4110385860243131, 9.1622479306453748, 12.710615785506533, 13.945880905466208]) >>> ak.cumsum(ak.randint(0, 1, 5, dtype=ak.bool_)) array([0, 1, 1, 2, 3]) .. py:function:: deg2rad(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Converts angles element-wise from degrees to radians. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the corresponding value will be converted from degrees to radians. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing an angle converted to radians, from degrees, for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: exp(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise exponential of the array. :param pda: :type pda: pdarray :returns: A pdarray containing exponential values of the input array elements :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Examples >>> ak.exp(ak.arange(1,5)) array([2.7182818284590451, 7.3890560989306504, 20.085536923187668, 54.598150033144236]) >>> ak.exp(ak.uniform(5,1.0,5.0)) array([11.84010843172504, 46.454368507659211, 5.5571769623557188, 33.494295836924771, 13.478894913238722]) .. py:function:: expm1(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise exponential of the array minus one. :param pda: :type pda: pdarray :returns: A pdarray containing exponential values of the input array elements minus one :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Examples >>> ak.exp1m(ak.arange(1,5)) array([1.7182818284590451, 6.3890560989306504, 19.085536923187668, 53.598150033144236]) >>> ak.exp1m(ak.uniform(5,1.0,5.0)) array([10.84010843172504, 45.454368507659211, 4.5571769623557188, 32.494295836924771, 12.478894913238722]) .. py:function:: eye(rows: arkouda.numpy.dtypes.int_scalars, cols: arkouda.numpy.dtypes.int_scalars, diag: arkouda.numpy.dtypes.int_scalars = 0, dt: type = akint64) Return a pdarray with zeros everywhere except along a diagonal, which is all ones. The matrix need not be square. :param rows: :type rows: int_scalars :param cols: :type cols: int_scalars :param diag: if diag = 0, zeros start at element [0,0] and proceed along diagonal if diag > 0, zeros start at element [0,diag] and proceed along diagonal if diag < 0, zeros start at element [diag,0] and proceed along diagonal etc. :type diag: int_scalars :returns: an array of zeros with ones along the specified diagonal :rtype: pdarray .. rubric:: Examples >>> ak.eye(rows=4,cols=4,diag=0,dt=ak.int64) array([array([1 0 0 0]) array([0 1 0 0]) array([0 0 1 0]) array([0 0 0 1])]) >>> ak.eye(rows=3,cols=3,diag=1,dt=ak.float64) array([array([0.00000000000000000 1.00000000000000000 0.00000000000000000]) array([0.00000000000000000 0.00000000000000000 1.00000000000000000]) array([0.00000000000000000 0.00000000000000000 0.00000000000000000])]) >>> ak.eye(rows=4,cols=4,diag=-1,dt=ak.bool_) array([array([False False False False]) array([True False False False]) array([False True False False]) array([False False True False])] .. rubric:: Notes if rows = cols and diag = 0, the result is an identity matrix Server returns an error if rank of pda < 2 .. py:function:: floor(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Alias of arkouda.numpy.floor .. py:function:: hash(pda: Union[Union[arkouda.pdarrayclass.pdarray, arkouda.strings.Strings, arkouda.segarray.SegArray, arkouda.categorical.Categorical], List[Union[arkouda.pdarrayclass.pdarray, arkouda.strings.Strings, arkouda.segarray.SegArray, arkouda.categorical.Categorical]]], full: bool = True) -> Union[Tuple[arkouda.pdarrayclass.pdarray, arkouda.pdarrayclass.pdarray], arkouda.pdarrayclass.pdarray] Return an element-wise hash of the array or list of arrays. :param pda: List[Union[pdarray, Strings, Segarray, Categorical]]] :type pda: Union[pdarray, Strings, Segarray, Categorical], :param full: This is only used when a single pdarray is passed into hash By default, a 128-bit hash is computed and returned as two int64 arrays. If full=False, then a 64-bit hash is computed and returned as a single int64 array. :type full: bool :returns: If full=True or a list of pdarrays is passed, a 2-tuple of pdarrays containing the high and low 64 bits of each hash, respectively. If full=False and a single pdarray is passed, a single pdarray containing a 64-bit hash :rtype: hashes :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Notes In the case of a single pdarray being passed, this function uses the SIPhash algorithm, which can output either a 64-bit or 128-bit hash. However, the 64-bit hash runs a significant risk of collisions when applied to more than a few million unique values. Unless the number of unique values is known to be small, the 128-bit hash is strongly recommended. Note that this hash should not be used for security, or for any cryptographic application. Not only is SIPhash not intended for such uses, but this implementation employs a fixed key for the hash, which makes it possible for an adversary with control over input to engineer collisions. In the case of a list of pdrrays, Strings, Categoricals, or Segarrays being passed, a non-linear function must be applied to each array since hashes of subsequent arrays cannot be simply XORed because equivalent values will cancel each other out, hence we do a rotation by the ordinal of the array. .. py:function:: histogram(pda: arkouda.pdarrayclass.pdarray, bins: arkouda.numpy.dtypes.int_scalars = 10) -> Tuple[arkouda.pdarrayclass.pdarray, arkouda.pdarrayclass.pdarray] Compute a histogram of evenly spaced bins over the range of an array. :param pda: The values to histogram :type pda: pdarray :param bins: The number of equal-size bins to use (default: 10) :type bins: int_scalars :returns: Bin edges and The number of values present in each bin :rtype: (pdarray, Union[pdarray, int64 or float64]) :raises TypeError: Raised if the parameter is not a pdarray or if bins is not an int. :raises ValueError: Raised if bins < 1 :raises NotImplementedError: Raised if pdarray dtype is bool or uint8 .. seealso:: :obj:`value_counts`, :obj:`histogram2d` .. rubric:: Notes The bins are evenly spaced in the interval [pda.min(), pda.max()]. .. rubric:: Examples >>> import matplotlib.pyplot as plt >>> A = ak.arange(0, 10, 1) >>> nbins = 3 >>> h, b = ak.histogram(A, bins=nbins) >>> h array([3, 3, 4]) >>> b array([0., 3., 6., 9.]) # To plot, export the left edges and the histogram to NumPy >>> plt.plot(b.to_ndarray()[::-1], h.to_ndarray()) .. py:function:: histogram2d(x: arkouda.pdarrayclass.pdarray, y: arkouda.pdarrayclass.pdarray, bins: Union[arkouda.numpy.dtypes.int_scalars, Sequence[arkouda.numpy.dtypes.int_scalars]] = 10) -> Tuple[arkouda.pdarrayclass.pdarray, arkouda.pdarrayclass.pdarray, arkouda.pdarrayclass.pdarray] Compute the bi-dimensional histogram of two data samples with evenly spaced bins :param x: A pdarray containing the x coordinates of the points to be histogrammed. :type x: pdarray :param y: A pdarray containing the y coordinates of the points to be histogrammed. :type y: pdarray :param bins: The number of equal-size bins to use. If int, the number of bins for the two dimensions (nx=ny=bins). If [int, int], the number of bins in each dimension (nx, ny = bins). Defaults to 10 :type bins: int_scalars or [int, int] = 10 :returns: * **hist** (*ArrayView, shape(nx, ny)*) -- The bi-dimensional histogram of samples x and y. Values in x are histogrammed along the first dimension and values in y are histogrammed along the second dimension. * **x_edges** (*pdarray*) -- The bin edges along the first dimension. * **y_edges** (*pdarray*) -- The bin edges along the second dimension. :raises TypeError: Raised if x or y parameters are not pdarrays or if bins is not an int or (int, int). :raises ValueError: Raised if bins < 1 :raises NotImplementedError: Raised if pdarray dtype is bool or uint8 .. seealso:: :obj:`histogram` .. rubric:: Notes The x bins are evenly spaced in the interval [x.min(), x.max()] and y bins are evenly spaced in the interval [y.min(), y.max()]. .. rubric:: Examples >>> x = ak.arange(0, 10, 1) >>> y = ak.arange(9, -1, -1) >>> nbins = 3 >>> h, x_edges, y_edges = ak.histogram2d(x, y, bins=nbins) >>> h array([[0, 0, 3], [0, 2, 1], [3, 1, 0]]) >>> x_edges array([0.0 3.0 6.0 9.0]) >>> x_edges array([0.0 3.0 6.0 9.0]) .. py:function:: histogramdd(sample: Sequence[arkouda.pdarrayclass.pdarray], bins: Union[arkouda.numpy.dtypes.int_scalars, Sequence[arkouda.numpy.dtypes.int_scalars]] = 10) -> Tuple[arkouda.pdarrayclass.pdarray, Sequence[arkouda.pdarrayclass.pdarray]] Compute the multidimensional histogram of data in sample with evenly spaced bins. :param sample: A sequence of pdarrays containing the coordinates of the points to be histogrammed. :type sample: Sequence[pdarray] :param bins: The number of equal-size bins to use. If int, the number of bins for all dimensions (nx=ny=...=bins). If [int, int, ...], the number of bins in each dimension (nx, ny, ... = bins). Defaults to 10 :type bins: int_scalars or Sequence[int_scalars] = 10 :returns: * **hist** (*ArrayView, shape(nx, ny, ..., nd)*) -- The multidimensional histogram of pdarrays in sample. Values in first pdarray are histogrammed along the first dimension. Values in second pdarray are histogrammed along the second dimension and so on. * **edges** (*List[pdarray]*) -- A list of pdarrays containing the bin edges for each dimension. :raises ValueError: Raised if bins < 1 :raises NotImplementedError: Raised if pdarray dtype is bool or uint8 .. seealso:: :obj:`histogram` .. rubric:: Notes The bins for each dimension, m, are evenly spaced in the interval [m.min(), m.max()] .. rubric:: Examples >>> x = ak.arange(0, 10, 1) >>> y = ak.arange(9, -1, -1) >>> z = ak.where(x % 2 == 0, x, y) >>> h, edges = ak.histogramdd((x, y,z), bins=(2,2,5)) >>> h array([[[0, 0, 0, 0, 0], [1, 1, 1, 1, 1]], [[1, 1, 1, 1, 1], [0, 0, 0, 0, 0]]]) >>> edges [array([0.0 4.5 9.0]), array([0.0 4.5 9.0]), array([0.0 1.6 3.2 4.8 6.4 8.0])] .. py:function:: isfinite(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise isfinite check applied to the array. :param pda: :type pda: pdarray :returns: A pdarray containing boolean values indicating whether the input array elements are finite :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray :raises RuntimeError: if the underlying pdarray is not float-based .. rubric:: Examples >>> ak.isfinite(ak.array[1.0, 2.0, ak.inf]) array([True, True, False]) .. py:function:: isinf(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise isinf check applied to the array. :param pda: :type pda: pdarray :returns: A pdarray containing boolean values indicating whether the input array elements are infinite :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray :raises RuntimeError: if the underlying pdarray is not float-based .. rubric:: Examples >>> ak.isinf(ak.array[1.0, 2.0, ak.inf]) array([False, False, True]) .. py:function:: isnan(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise isnan check applied to the array. :param pda: :type pda: pdarray :returns: A pdarray containing boolean values indicating whether the input array elements are NaN :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray :raises RuntimeError: if the underlying pdarray is not float-based .. rubric:: Examples >>> ak.isnan(ak.array[1.0, 2.0, 1.0 / 0.0]) array([False, False, True]) .. py:function:: log(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise natural log of the array. :param pda: :type pda: pdarray :returns: A pdarray containing natural log values of the input array elements :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Notes Logarithms with other bases can be computed as follows: .. rubric:: Examples >>> A = ak.array([1, 10, 100]) # Natural log >>> ak.log(A) array([0, 2.3025850929940459, 4.6051701859880918]) # Log base 10 >>> ak.log(A) / np.log(10) array([0, 1, 2]) # Log base 2 >>> ak.log(A) / np.log(2) array([0, 3.3219280948873626, 6.6438561897747253]) .. py:function:: log10(x: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise base 10 log of the array. :param x: array to compute on :type x: pdarray :rtype: pdarray contain values of the base 10 log .. py:function:: log1p(x: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise natural log of one plus the array. :param x: array to compute on :type x: pdarray :rtype: pdarray contain values of the natural log of one plus the array .. py:function:: log2(x: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise base 2 log of the array. :param x: array to compute on :type x: pdarray :rtype: pdarray contain values of the base 2 log .. py:function:: matmul(pdaLeft: arkouda.pdarrayclass.pdarray, pdaRight: arkouda.pdarrayclass.pdarray) Compute the product of two matrices. :param pdaLeft: :type pdaLeft: pdarray :param pdaRight: :type pdaRight: pdarray :returns: the matrix product pdaLeft x pdaRight :rtype: pdarray .. rubric:: Examples >>> a = ak.array([[1,2,3,4,5],[1,2,3,4,5]]) >>> b = ak.array(([1,1],[2,2],[3,3],[4,4],[5,5]]) >>> ak.matmul(a,b) array([array([30 30]) array([45 45])]) >>> x = ak.array([[1,2,3],[1.1,2.1,3.1]]) >>> y = ak.array([[1,1,1],[0,2,2],[0,0,3]]) >>> ak.matmul(x,y) array([array([1.00000000000000000 5.00000000000000000 14.00000000000000000]) array([1.1000000000000001 5.3000000000000007 14.600000000000001])]) .. rubric:: Notes Server returns an error if shapes of pdaLeft and pdaRight are incompatible with matrix multiplication. .. py:function:: median(pda) Compute the median of a given array. 1d case only, for now. :param pda: The input data, in pdarray form, numeric type or boolean :type pda: pdarray :returns: The median of the entire pdarray The array is sorted, and then if the number of elements is odd, the return value is the middle element. If even, then the mean of the two middle elements. :rtype: np.float64 .. rubric:: Examples >>> import arkouda as ak >>> arkouda.connect() >>> pda = ak.array ([0,4,7,8,1,3,5,2,-1]) >>> ak.median(pda) 3 >>> pda = ak.array([0,1,3,3,1,2,3,4,2,3]) 2.5 .. py:function:: putmask(pda: arkouda.pdarrayclass.pdarray, mask: Union[bool, arkouda.pdarrayclass.pdarray], values: arkouda.pdarrayclass.pdarray) Overwrite elements of a pdarray at indices where mask is True :param pda: pda = input where mask is False, = values where mask is True :type pda: pdarray, source data, also output data :param mask: :type mask: a scalar boolean, or a pdarray of booleans :param values: :type values: pdarray, replacement data :rtype: None - pda is modified in-place .. rubric:: Notes If values.size != a.size, values is repeated and/or pruned as needed to make sizes match, because ak.where requires matching sizes. .. rubric:: Examples >>> a = ak.array(np.arange(10)) >>> ak.putmask (a,a>2,a**2) array ([0,1,2,9,16,25,36,49,64,81]) >>> values = ak.array([3,2]) >>> ak.putmask (a,a>2,values) array ([0,1,2,2,3,2,3,2,3,2]) :raises TypeError: Raised if a and values are not the same type .. py:function:: rad2deg(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Converts angles element-wise from radians to degrees. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the corresponding value will be converted from radians to degrees. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing an angle converted to degrees, from radians, for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: round(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise rounding of the array. :param pda: :type pda: pdarray :returns: A pdarray containing input array elements rounded to the nearest integer :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Examples >>> ak.round(ak.array([1.1, 2.5, 3.14159])) array([1, 3, 3]) .. py:function:: sign(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise sign of the array. :param pda: :type pda: pdarray :returns: A pdarray containing sign values of the input array elements :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Examples >>> ak.sign(ak.array([-10, -5, 0, 5, 10])) array([-1, -1, 0, 1, 1]) .. py:function:: sin(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise sine of the array. :param pda: :type pda: pdarray :param where: 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. :type where: Boolean or pdarray :returns: A pdarray containing sin for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: sinh(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise hyperbolic sine of the array. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the hyperbolic sine will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing hyperbolic sine for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: square(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise square of the array. :param pda: :type pda: pdarray :returns: A pdarray containing square values of the input array elements :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Examples >>> ak.square(ak.arange(1,5)) array([1, 4, 9, 16]) .. py:function:: tan(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise tangent of the array. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the tangent will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing tangent for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: tanh(pda: arkouda.pdarrayclass.pdarray, where: Union[bool, arkouda.pdarrayclass.pdarray] = True) -> arkouda.pdarrayclass.pdarray Return the element-wise hyperbolic tangent of the array. :param pda: :type pda: pdarray :param where: This condition is broadcast over the input. At locations where the condition is True, the hyperbolic tangent will be applied to the corresponding value. Elsewhere, it will retain its original value. Default set to True. :type where: Boolean or pdarray :returns: A pdarray containing hyperbolic tangent for each element of the original pdarray :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. py:function:: transpose(pda: arkouda.pdarrayclass.pdarray) Compute the transpose of a matrix. :param pda: :type pda: pdarray :returns: the transpose of the input matrix :rtype: pdarray .. rubric:: Examples >>> a = ak.array([[1,2,3,4,5],[1,2,3,4,5]]) >>> ak.transpose(a) array([array([1 1]) array([2 2]) array([3 3]) array([4 4]) array([5 5])]) .. rubric:: Notes Server returns an error if rank of pda < 2 .. py:function:: tril(pda: arkouda.pdarrayclass.pdarray, diag: arkouda.numpy.dtypes.int_scalars = 0) Return a copy of the pda with the upper triangle zeroed out :param pda: :type pda: pdarray :param diag: if diag = 0, zeros start just below the main diagonal if diag = 1, zeros start at the main diagonal if diag = 2, zeros start just above the main diagonal etc. :type diag: int_scalars :returns: a copy of pda with zeros in the upper triangle :rtype: pdarray .. rubric:: Examples >>> a = ak.array([[1,2,3,4,5],[2,3,4,5,6],[3,4,5,6,7],[4,5,6,7,8],[5,6,7,8,9]]) >>> ak.tril(a,diag=4) array([array([1 2 3 4 5]) array([2 3 4 5 6]) array([3 4 5 6 7]) array([4 5 6 7 8]) array([5 6 7 8 9])]) >>> ak.tril(a,diag=3) array([array([1 2 3 4 0]) array([2 3 4 5 6]) array([3 4 5 6 7]) array([4 5 6 7 8]) array([5 6 7 8 9])]) >>> ak.tril(a,diag=2) array([array([1 2 3 0 0]) array([2 3 4 5 0]) array([3 4 5 6 7]) array([4 5 6 7 8]) array([5 6 7 8 9])]) >>> ak.tril(a,diag=1) array([array([1 2 0 0 0]) array([2 3 4 0 0]) array([3 4 5 6 0]) array([4 5 6 7 8]) array([5 6 7 8 9])]) >>> ak.tril(a,diag=0) array([array([1 0 0 0 0]) array([2 3 0 0 0]) array([3 4 5 0 0]) array([4 5 6 7 0]) array([5 6 7 8 9])]) .. rubric:: Notes Server returns an error if rank of pda < 2 .. py:function:: triu(pda: arkouda.pdarrayclass.pdarray, diag: arkouda.numpy.dtypes.int_scalars = 0) Return a copy of the pda with the lower triangle zeroed out :param pda: :type pda: pdarray :param diag: if diag = 0, zeros start just above the main diagonal if diag = 1, zeros start at the main diagonal if diag = 2, zeros start just below the main diagonal etc. :type diag: int_scalars :returns: a copy of pda with zeros in the lower triangle :rtype: pdarray .. rubric:: Examples >>> a = ak.array([[1,2,3,4,5],[2,3,4,5,6],[3,4,5,6,7],[4,5,6,7,8],[5,6,7,8,9]]) >>> ak.triu(a,diag=0) array([array([1 2 3 4 5]) array([0 3 4 5 6]) array([0 0 5 6 7]) array([0 0 0 7 8]) array([0 0 0 0 9])]) >>> ak.triu(a,diag=1) array([array([0 2 3 4 5]) array([0 0 4 5 6]) array([0 0 0 6 7]) array([0 0 0 0 8]) array([0 0 0 0 0])]) >>> ak.triu(a,diag=2) array([array([0 0 3 4 5]) array([0 0 0 5 6]) array([0 0 0 0 7]) array([0 0 0 0 0]) array([0 0 0 0 0])]) >>> ak.triu(a,diag=3) array([array([0 0 0 4 5]) array([0 0 0 0 6]) array([0 0 0 0 0]) array([0 0 0 0 0]) array([0 0 0 0 0])]) >>> ak.triu(a,diag=4) array([array([0 0 0 0 5]) array([0 0 0 0 0]) array([0 0 0 0 0]) array([0 0 0 0 0]) array([0 0 0 0 0])]) .. rubric:: Notes Server returns an error if rank of pda < 2 .. py:function:: trunc(pda: arkouda.pdarrayclass.pdarray) -> arkouda.pdarrayclass.pdarray Return the element-wise truncation of the array. :param pda: :type pda: pdarray :returns: A pdarray containing input array elements truncated to the nearest integer :rtype: pdarray :raises TypeError: Raised if the parameter is not a pdarray .. rubric:: Examples >>> ak.trunc(ak.array([1.1, 2.5, 3.14159])) array([1, 2, 3]) .. py:function:: value_counts(pda: arkouda.pdarrayclass.pdarray) -> Tuple[Union[Union[arkouda.pdarrayclass.pdarray, arkouda.strings.Strings, arkouda.categorical.Categorical], Sequence[Union[arkouda.pdarrayclass.pdarray, arkouda.strings.Strings, arkouda.categorical.Categorical]]], arkouda.pdarrayclass.pdarray] Count the occurrences of the unique values of an array. :param pda: The array of values to count :type pda: pdarray, int64 :returns: * **unique_values** (*pdarray, int64 or Strings*) -- The unique values, sorted in ascending order * **counts** (*pdarray, int64*) -- The number of times the corresponding unique value occurs :raises TypeError: Raised if the parameter is not a pdarray .. seealso:: :obj:`unique`, :obj:`histogram` .. rubric:: Notes This function differs from ``histogram()`` in that it only returns counts for values that are present, leaving out empty "bins". This function delegates all logic to the unique() method where the return_counts parameter is set to True. .. rubric:: Examples >>> A = ak.array([2, 0, 2, 4, 0, 0]) >>> ak.value_counts(A) (array([0, 2, 4]), array([3, 2, 1])) .. py:function:: vecdot(x1: arkouda.pdarrayclass.pdarray, x2: arkouda.pdarrayclass.pdarray) Compute the generalized dot product of two vectors along the given axis. Assumes that both tensors have already been broadcast to the same shape. :param x1: :type x1: pdarray :param x2: :type x2: pdarray :returns: x1 vecdot x2 :rtype: pdarray .. rubric:: Examples >>> a = ak.array([[1,2,3,4,5],[1,2,3,4,5]]) >>> b = ak.array(([2,2,2,2,2],[2,2,2,2,2]]) >>> ak.vecdot(a,b) array([5 10 15 20 25]) >>> ak.vecdot(b,a) array([5 10 15 20 25]) :raises ValueTypeError: Raised if x1 and x2 are not of matching shape or if rank of x1 < 2 .. py:function:: where(condition: arkouda.pdarrayclass.pdarray, A: Union[str, arkouda.numpy.dtypes.numeric_scalars, arkouda.pdarrayclass.pdarray, arkouda.strings.Strings, arkouda.categorical.Categorical], B: Union[str, arkouda.numpy.dtypes.numeric_scalars, arkouda.pdarrayclass.pdarray, arkouda.strings.Strings, arkouda.categorical.Categorical]) -> Union[arkouda.pdarrayclass.pdarray, arkouda.strings.Strings, arkouda.categorical.Categorical] Returns 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. :param condition: Used to choose values from A or B :type condition: pdarray :param A: Value(s) used when condition is True :type A: Union[numeric_scalars, str, pdarray, Strings, Categorical] :param B: Value(s) used when condition is False :type B: Union[numeric_scalars, str, pdarray, Strings, Categorical] :returns: Values chosen from A where the condition is True and B where the condition is False :rtype: 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, pdarray, str, Strings, Categorical if pdarray dtypes are not supported or do not match, or multiple condition clauses (see Notes section) are applied :raises ValueError: Raised if the shapes of the condition, A, and B pdarrays are unequal .. rubric:: Examples >>> 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']) .. rubric:: 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