arkouda.testing =============== .. py:module:: arkouda.testing Functions --------- .. autoapisummary:: arkouda.testing.assert_almost_equal arkouda.testing.assert_almost_equivalent arkouda.testing.assert_arkouda_array_equal arkouda.testing.assert_arkouda_array_equivalent arkouda.testing.assert_arkouda_pdarray_equal arkouda.testing.assert_arkouda_segarray_equal arkouda.testing.assert_arkouda_strings_equal arkouda.testing.assert_attr_equal arkouda.testing.assert_categorical_equal arkouda.testing.assert_class_equal arkouda.testing.assert_contains_all arkouda.testing.assert_copy arkouda.testing.assert_dict_equal arkouda.testing.assert_equal arkouda.testing.assert_equivalent arkouda.testing.assert_frame_equal arkouda.testing.assert_frame_equivalent arkouda.testing.assert_index_equal arkouda.testing.assert_index_equivalent arkouda.testing.assert_is_sorted arkouda.testing.assert_series_equal arkouda.testing.assert_series_equivalent Package Contents ---------------- .. py:function:: assert_almost_equal(left, right, rtol: float = 1e-05, atol: float = 1e-08, **kwargs) -> None Check that the left and right objects are approximately equal. By approximately equal, we refer to objects that are numbers or that contain numbers which may be equivalent to specific levels of precision. :param left: :type left: object :param right: :type right: object :param rtol: Relative tolerance. :type rtol: float, default 1e-5 :param atol: Absolute tolerance. :type atol: float, default 1e-8 .. warning:: This function cannot be used on pdarray of size > ak.client.maxTransferBytes because it converts pdarrays to numpy arrays and calls np.allclose. .. py:function:: assert_almost_equivalent(left, right, rtol: float = 1e-05, atol: float = 1e-08) -> None Check that two objects are approximately equal. By approximately equal, we refer to objects that are numbers or that contain numbers which may be equivalent to specific levels of precision. If the objects are pandas or numpy objects, they are converted to Arkouda objects. Then assert_almost_equal is applied to the result. :param left: First object to compare. :type left: object :param right: Second object to compare. :type right: object :param rtol: Relative tolerance. Default is 1e-5. :type rtol: float :param atol: Absolute tolerance. Default is 1e-8. :type atol: float :raises TypeError: If either input is not a supported numeric-like type. .. warning:: This function cannot be used on pdarrays of size > ak.client.maxTransferBytes because it converts pdarrays to numpy arrays and calls np.allclose. .. seealso:: :py:obj:`assert_almost_equal` .. rubric:: Examples >>> import arkouda as ak >>> from arkouda.testing import assert_almost_equivalent >>> assert_almost_equivalent(0.123456, 0.123457, rtol=1e-4) .. py:function:: assert_arkouda_array_equal(left: arkouda.pdarray | arkouda.Strings | arkouda.Categorical | arkouda.SegArray, right: arkouda.pdarray | arkouda.Strings | arkouda.Categorical | arkouda.SegArray, check_dtype: bool = True, err_msg=None, check_same=None, obj: str = 'pdarray', index_values=None) -> None Check that 'ak.pdarray' or 'ak.Strings', 'ak.Categorical', or 'ak.SegArray' is equivalent. :param left: The two arrays to be compared. :type left: pdarray or Strings or Categorical or SegArray :param right: The two arrays to be compared. :type right: pdarray or Strings or Categorical or SegArray :param check_dtype: Check dtype if both a and b are ak.pdarray. :type check_dtype: bool, default True :param err_msg: If provided, used as assertion message. :type err_msg: str, default None :param check_same: Ensure left and right refer/do not refer to the same memory area. :type check_same: None|'copy'|'same', default None :param obj: Specify object name being compared, internally used to show appropriate assertion message. :type obj: str, default 'numpy array' :param index_values: optional index (shared by both left and right), used in output. :type index_values: Index | arkouda.pdarray, default None .. py:function:: assert_arkouda_array_equivalent(left: arkouda.pdarray | arkouda.Strings | arkouda.Categorical | arkouda.SegArray | numpy.ndarray | pandas.Categorical, right: arkouda.pdarray | arkouda.Strings | arkouda.Categorical | arkouda.SegArray | numpy.ndarray | pandas.Categorical, check_dtype: bool = True, err_msg=None, check_same=None, obj: str = 'pdarray', index_values=None) -> None Check that two Arkouda-compatible arrays are equal. Supported types include numpy arrays, pandas Categorical, and Arkouda arrays. :param left: First array to compare. :type left: pdarray, Strings, Categorical, SegArray, np.ndarray, or pd.Categorical :param right: Second array to compare. :type right: pdarray, Strings, Categorical, SegArray, np.ndarray, or pd.Categorical :param check_dtype: Whether to verify that dtypes match. Default is True. :type check_dtype: bool :param err_msg: Optional message to display on failure. :type err_msg: str or None :param check_same: Whether to ensure identity or separation in memory. Default is None. :type check_same: None or {"copy", "same"} :param obj: Object label for error messages. Default is "pdarray". :type obj: str :param index_values: Shared index used in error output. Default is None. :type index_values: Index or pdarray, optional :raises TypeError: If either input is not a supported array type. .. seealso:: :py:obj:`assert_arkouda_array_equal` .. rubric:: Examples >>> import arkouda as ak >>> from arkouda import Strings >>> from arkouda.testing import assert_arkouda_array_equivalent >>> a = ak.array([1, 2, 3]) >>> b = ak.array([1, 2, 3]) >>> assert_arkouda_array_equivalent(a, b) >>> s1 = ak.array(['x', 'y']) >>> s2 = ak.array(['x', 'y']) >>> assert_arkouda_array_equivalent(s1, s2) .. py:function:: assert_arkouda_pdarray_equal(left: arkouda.pdarray, right: arkouda.pdarray, check_dtype: bool = True, err_msg=None, check_same=None, obj: str = 'pdarray', index_values=None) -> None Check that the two 'ak.pdarray's are equivalent. :param left: The two arrays to be compared. :type left: arkouda.pdarray :param right: The two arrays to be compared. :type right: arkouda.pdarray :param check_dtype: Check dtype if both a and b are ak.pdarray. :type check_dtype: bool, default True :param err_msg: If provided, used as assertion message. :type err_msg: str, default None :param check_same: Ensure left and right refer/do not refer to the same memory area. :type check_same: None|'copy'|'same', default None :param obj: Specify object name being compared, internally used to show appropriate assertion message. :type obj: str, default 'pdarray' :param index_values: optional index (shared by both left and right), used in output. :type index_values: Index | arkouda.pdarray, default None .. py:function:: assert_arkouda_segarray_equal(left: arkouda.SegArray, right: arkouda.SegArray, check_dtype: bool = True, err_msg=None, check_same=None, obj: str = 'segarray') -> None Check that the two 'ak.SegArray's are equivalent. :param left: The two segarrays to be compared. :type left: arkouda.numpy.SegArray :param right: The two segarrays to be compared. :type right: arkouda.numpy.SegArray :param check_dtype: Check dtype if both a and b are ak.pdarray. :type check_dtype: bool, default True :param err_msg: If provided, used as assertion message. :type err_msg: str, default None :param check_same: Ensure left and right refer/do not refer to the same memory area. :type check_same: None|'copy'|'same', default None :param obj: Specify object name being compared, internally used to show appropriate assertion message. :type obj: str, default 'pdarray' .. py:function:: assert_arkouda_strings_equal(left, right, err_msg=None, check_same=None, obj: str = 'Strings', index_values=None) -> None Check that 'ak.Strings' is equivalent. :param left: The two Strings to be compared. :type left: arkouda.numpy.Strings :param right: The two Strings to be compared. :type right: arkouda.numpy.Strings :param err_msg: If provided, used as assertion message. :type err_msg: str, default None :param check_same: Ensure left and right refer/do not refer to the same memory area. :type check_same: None|'copy'|'same', default None :param obj: Specify object name being compared, internally used to show appropriate assertion message. :type obj: str, default 'Strings' :param index_values: optional index (shared by both left and right), used in output. :type index_values: Index | arkouda.pdarray, default None .. py:function:: assert_attr_equal(attr: str, left, right, obj: str = 'Attributes') -> None Check attributes are equal. Both objects must have attribute. :param attr: Attribute name being compared. :type attr: str :param left: :type left: object :param right: :type right: object :param obj: Specify object name being compared, internally used to show appropriate assertion message :type obj: str, default 'Attributes' .. py:function:: assert_categorical_equal(left, right, check_dtype: bool = True, check_category_order: bool = True, obj: str = 'Categorical') -> None Test that Categoricals are equivalent. :param left: :type left: Categorical :param right: :type right: Categorical :param check_dtype: Check that integer dtype of the codes are the same. :type check_dtype: bool, default True :param check_category_order: Whether the order of the categories should be compared, which implies identical integer codes. If False, only the resulting values are compared. The ordered attribute is checked regardless. :type check_category_order: bool, default True :param obj: Specify object name being compared, internally used to show appropriate assertion message. :type obj: str, default 'Categorical' .. py:function:: assert_class_equal(left, right, exact: bool = True, obj: str = 'Input') -> None Check classes are equal. .. py:function:: assert_contains_all(iterable, dic) -> None Assert that a dictionary contains all the elements of an iterable. :param iterable: :type iterable: iterable :param dic: :type dic: dict .. py:function:: assert_copy(iter1, iter2, **eql_kwargs) -> None Check that the elements are equal, but not the same object. (Does not check that items in sequences are also not the same object.) :param iter1: Iterables that produce elements comparable with assert_almost_equal. :type iter1: iterable :param iter2: Iterables that produce elements comparable with assert_almost_equal. :type iter2: iterable .. py:function:: assert_dict_equal(left, right, compare_keys: bool = True) -> None Assert that two dictionaries are equal. Values must be arkouda objects. :param left: The dictionaries to be compared. :type left: dict :param right: The dictionaries to be compared. :type right: dict :param compare_keys: Whether to compare the keys. If False, only the values are compared. :type compare_keys: bool, default = True .. py:function:: assert_equal(left, right, **kwargs) -> None Wrapper for tm.assert_*_equal to dispatch to the appropriate test function. :param left: The two items to be compared. :type left: Index, Series, DataFrame, or pdarray :param right: The two items to be compared. :type right: Index, Series, DataFrame, or pdarray :param \*\*kwargs: All keyword arguments are passed through to the underlying assert method. .. py:function:: assert_equivalent(left, right, **kwargs) -> None Dispatch to the appropriate assertion function depending on object types. :param left: First object to compare. Type determines which assertion function is used. :type left: Any :param right: Second object to compare. :type right: Any :param \*\*kwargs: Keyword arguments passed to the specific assertion function. :type \*\*kwargs: dict :raises AssertionError: If values are not equivalent. .. rubric:: Examples >>> import arkouda as ak >>> import pandas as pd >>> from arkouda.testing import assert_equivalent >>> ak_series = ak.Series([1, 2, 3]) >>> pd_series = pd.Series([1, 2, 3]) >>> assert_equivalent(ak_series, pd_series) .. py:function:: assert_frame_equal(left: arkouda.DataFrame, right: arkouda.DataFrame, check_dtype: bool = True, check_index_type: bool = True, check_column_type: bool = True, check_frame_type: bool = True, check_names: bool = True, check_exact: bool = True, check_categorical: bool = True, check_like: bool = False, rtol: float = 1e-05, atol: float = 1e-08, obj: str = 'DataFrame') -> None Check that left and right DataFrame are equal. This function is intended to compare two DataFrames and output any differences. It is mostly intended for use in unit tests. Additional parameters allow varying the strictness of the equality checks performed. :param left: First DataFrame to compare. :type left: DataFrame :param right: Second DataFrame to compare. :type right: DataFrame :param check_dtype: Whether to check the DataFrame dtype is identical. :type check_dtype: bool, default True :param check_index_type: Whether to check the Index class, dtype and inferred_type are identical. :type check_index_type: bool, default = True :param check_column_type: Whether to check the columns class, dtype and inferred_type are identical. Is passed as the ``exact`` argument of :func:`assert_index_equal`. :type check_column_type: bool or {'equiv'}, default 'equiv' :param check_frame_type: Whether to check the DataFrame class is identical. :type check_frame_type: bool, default True :param check_names: Whether to check that the `names` attribute for both the `index` and `column` attributes of the DataFrame is identical. :type check_names: bool, default True :param check_exact: Whether to compare number exactly. :type check_exact: bool, default False :param check_categorical: Whether to compare internal Categorical exactly. :type check_categorical: bool, default True :param check_like: If True, ignore the order of index & columns. Note: index labels must match their respective rows (same as in columns) - same labels must be with the same data. :type check_like: bool, default False :param rtol: Relative tolerance. Only used when check_exact is False. :type rtol: float, default 1e-5 :param atol: Absolute tolerance. Only used when check_exact is False. :type atol: float, default 1e-8 :param obj: Specify object name being compared, internally used to show appropriate assertion message. :type obj: str, default 'DataFrame' .. seealso:: :py:obj:`assert_series_equal` Equivalent method for asserting Series equality. .. rubric:: Examples >>> import arkouda as ak This example shows comparing two DataFrames that are equal but with columns of differing dtypes. >>> from arkouda.testing import assert_frame_equal >>> df1 = ak.DataFrame({'a': [1, 2], 'b': [3, 4]}) >>> df2 = ak.DataFrame({'a': [1, 2], 'b': [3.0, 4.0]}) df1 equals itself. >>> assert_frame_equal(df1, df1) df1 differs from df2 as column 'b' is of a different type. >>> assert_frame_equal(df1, df2) # doctest: +SKIP Traceback (most recent call last): ... AssertionError: Attributes of DataFrame.iloc[:, 1] (column name="b") are different Attribute "dtype" are different [left]: int64 [right]: float64 Ignore differing dtypes in columns with check_dtype. >>> assert_frame_equal(df1, df2, check_dtype=False) .. py:function:: assert_frame_equivalent(left: arkouda.DataFrame | pandas.DataFrame, right: arkouda.DataFrame | pandas.DataFrame, check_dtype: bool = True, check_index_type: bool = True, check_column_type: bool = True, check_frame_type: bool = True, check_names: bool = True, check_exact: bool = True, check_categorical: bool = True, check_like: bool = False, rtol: float = 1e-05, atol: float = 1e-08, obj: str = 'DataFrame') -> None Check that two DataFrames are equal. This function compares two DataFrames and raises an assertion if they differ. It is intended primarily for use in unit tests. pandas DataFrames are converted to Arkouda equivalents before comparison. :param left: First DataFrame to compare. :type left: DataFrame or pd.DataFrame :param right: Second DataFrame to compare. :type right: DataFrame or pd.DataFrame :param check_dtype: Whether to check that dtypes are identical. Default is True. :type check_dtype: bool :param check_index_type: Whether to check that index class, dtype, and inferred type are identical. Default is True. :type check_index_type: bool :param check_column_type: Whether to check that column class, dtype, and inferred type are identical. Default is True. :type check_column_type: bool :param check_frame_type: Whether to check that the DataFrame class is identical. Default is True. :type check_frame_type: bool :param check_names: Whether to check that the index and column names are identical. Default is True. :type check_names: bool :param check_exact: Whether to compare values exactly. Default is True. :type check_exact: bool :param check_categorical: Whether to compare internal categoricals exactly. Default is True. :type check_categorical: bool :param check_like: Whether to ignore the order of index and columns. Labels must still match their data. / Default is False. :type check_like: bool :param rtol: Relative tolerance used when check_exact is False. Default is 1e-5. :type rtol: float :param atol: Absolute tolerance used when check_exact is False. Default is 1e-8. :type atol: float :param obj: Object name used in error messages. Default is "DataFrame". :type obj: str :raises TypeError: If either input is not a DataFrame or pd.DataFrame. .. seealso:: :py:obj:`assert_frame_equal` .. rubric:: Examples >>> import arkouda as ak >>> import pandas as pd >>> from arkouda.testing import assert_frame_equivalent >>> df1 = ak.DataFrame({'a': [1, 2], 'b': [3, 4]}) >>> df2 = pd.DataFrame({'a': [1, 2], 'b': [3.0, 4.0]}) Fails because dtypes are different: >>> assert_frame_equivalent(df1, df2) # doctest: +SKIP .. py:function:: assert_index_equal(left: arkouda.Index, right: arkouda.Index, exact: bool = True, check_names: bool = True, check_exact: bool = True, check_categorical: bool = True, check_order: bool = True, rtol: float = 1e-05, atol: float = 1e-08, obj: str = 'Index') -> None Check that left and right Index are equal. :param left: :type left: Index :param right: :type right: Index :param exact: Whether to check the Index class, dtype and inferred_type are identical. :type exact: True :param check_names: Whether to check the names attribute. :type check_names: bool, default True :param check_exact: Whether to compare number exactly. :type check_exact: bool, default True :param check_categorical: Whether to compare internal Categorical exactly. :type check_categorical: bool, default True :param check_order: Whether to compare the order of index entries as well as their values. If True, both indexes must contain the same elements, in the same order. If False, both indexes must contain the same elements, but in any order. :type check_order: bool, default True :param rtol: Relative tolerance. Only used when check_exact is False. :type rtol: float, default 1e-5 :param atol: Absolute tolerance. Only used when check_exact is False. :type atol: float, default 1e-8 :param obj: Specify object name being compared, internally used to show appropriate assertion message. :type obj: str, default 'Index' .. rubric:: Examples >>> import arkouda as ak >>> from arkouda import testing as tm >>> a = ak.Index([1, 2, 3]) >>> b = ak.Index([1, 2, 3]) >>> tm.assert_index_equal(a, b) .. py:function:: assert_index_equivalent(left: arkouda.Index | pandas.Index, right: arkouda.Index | pandas.Index, exact: bool = True, check_names: bool = True, check_exact: bool = True, check_categorical: bool = True, check_order: bool = True, rtol: float = 1e-05, atol: float = 1e-08, obj: str = 'Index') -> None Check that two Index objects are equal. If the objects are pandas Index, they are converted to Arkouda Index. Then assert_index_equal is applied to the result. :param left: First Index to compare. :type left: Index or pd.Index :param right: Second Index to compare. :type right: Index or pd.Index :param exact: Whether to check that class, dtype, and inferred type are identical. Default is True. :type exact: bool :param check_names: Whether to check the names attribute. Default is True. :type check_names: bool :param check_exact: Whether to compare values exactly. Default is True. :type check_exact: bool :param check_categorical: Whether to compare internal Categoricals exactly. Default is True. :type check_categorical: bool :param check_order: Whether to require identical order in index values. Default is True. :type check_order: bool :param rtol: Relative tolerance used when check_exact is False. Default is 1e-5. :type rtol: float :param atol: Absolute tolerance used when check_exact is False. Default is 1e-8. :type atol: float :param obj: Object name used in error messages. Default is "Index". :type obj: str :raises TypeError: If either input is not an Index or pd.Index. .. seealso:: :py:obj:`assert_index_equal` .. rubric:: Examples >>> import arkouda as ak >>> from arkouda import testing as tm >>> import pandas as pd >>> a = ak.Index([1, 2, 3]) >>> b = pd.Index([1, 2, 3]) >>> tm.assert_index_equivalent(a, b) .. py:function:: assert_is_sorted(seq) -> None Assert that the sequence is sorted. .. py:function:: assert_series_equal(left, right, check_dtype: bool = True, check_index_type: bool = True, check_series_type: bool = True, check_names: bool = True, check_exact: bool = False, check_categorical: bool = True, check_category_order: bool = True, rtol: float = 1e-05, atol: float = 1e-08, obj: str = 'Series', *, check_index: bool = True, check_like: bool = False) -> None Check that left and right Series are equal. :param left: :type left: Series :param right: :type right: Series :param check_dtype: Whether to check the Series dtype is identical. :type check_dtype: bool, default True :param check_index_type: Whether to check the Index class, dtype and inferred_type are identical. :type check_index_type: bool, default True :param check_series_type: Whether to check the Series class is identical. :type check_series_type: bool, default True :param check_names: Whether to check the Series and Index names attribute. :type check_names: bool, default True :param check_exact: Whether to compare number exactly. :type check_exact: bool, default False :param check_categorical: Whether to compare internal Categorical exactly. :type check_categorical: bool, default True :param check_category_order: Whether to compare category order of internal Categoricals. :type check_category_order: bool, default True :param rtol: Relative tolerance. Only used when check_exact is False. :type rtol: float, default 1e-5 :param atol: Absolute tolerance. Only used when check_exact is False. :type atol: float, default 1e-8 :param obj: Specify object name being compared, internally used to show appropriate assertion message. :type obj: str, default 'Series' :param check_index: Whether to check index equivalence. If False, then compare only values. :type check_index: bool, default True :param check_like: If True, ignore the order of the index. Must be False if check_index is False. Note: same labels must be with the same data. :type check_like: bool, default False .. rubric:: Examples >>> import arkouda as ak >>> from arkouda import testing as tm >>> a = ak.Series([1, 2, 3, 4]) >>> b = ak.Series([1, 2, 3, 4]) >>> tm.assert_series_equal(a, b) .. py:function:: assert_series_equivalent(left: arkouda.Series | pandas.Series, right: arkouda.Series | pandas.Series, check_dtype: bool = True, check_index_type: bool = True, check_series_type: bool = True, check_names: bool = True, check_exact: bool = False, check_categorical: bool = True, check_category_order: bool = True, rtol: float = 1e-05, atol: float = 1e-08, obj: str = 'Series', *, check_index: bool = True, check_like: bool = False) -> None Check that two Series are equal. This function compares two Series and raises an assertion if they differ. pandas Series are converted to Arkouda equivalents before comparison. The comparison can be customized using the provided keyword arguments. :param left: First Series to compare. :type left: Series or pd.Series :param right: Second Series to compare. :type right: Series or pd.Series :param check_dtype: Whether to check that dtypes are identical. Default is True. :type check_dtype: bool :param check_index_type: Whether to check that index class, dtype, and inferred type are identical. Default is True. :type check_index_type: bool :param check_series_type: Whether to check that the Series class is identical. Default is True. :type check_series_type: bool :param check_names: Whether to check that the Series and Index name attributes are identical. Default is True. :type check_names: bool :param check_exact: Whether to compare numbers exactly. Default is False. :type check_exact: bool :param check_categorical: Whether to compare internal Categoricals exactly. Default is True. :type check_categorical: bool :param check_category_order: Whether to compare category order in internal Categoricals. Default is True. :type check_category_order: bool :param rtol: Relative tolerance used when check_exact is False. Default is 1e-5. :type rtol: float :param atol: Absolute tolerance used when check_exact is False. Default is 1e-8. :type atol: float :param obj: Object name used in error messages. Default is "Series". :type obj: str :param check_index: Whether to check index equivalence. If False, only values are compared. Default is True. :type check_index: bool :param check_like: If True, ignore the order of the index. Must be False if check_index is False. Note: identical labels must still correspond to the same data. Default is False. :type check_like: bool :raises TypeError: If either input is not a Series or pd.Series. .. seealso:: :py:obj:`assert_series_equal` .. rubric:: Examples >>> import arkouda as ak >>> from arkouda import testing as tm >>> import pandas as pd >>> a = ak.Series([1, 2, 3, 4]) >>> b = pd.Series([1, 2, 3, 4]) >>> tm.assert_series_equivalent(a, b)