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.core.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.core.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 two Arkouda arrays are equivalent. Supports pdarray, Strings, Categorical, and SegArray. :param left: The first array to compare. :type left: pdarray or Strings or Categorical or SegArray :param right: The second array to compare. :type right: pdarray or Strings or Categorical or SegArray :param check_dtype: Whether to check dtype if both `left` and `right` are ak.pdarray. Defaults to True. :type check_dtype: bool :param err_msg: Custom assertion message, if provided. Defaults to None. :type err_msg: str or None :param check_same: If not None, assert whether `left` and `right` share the same memory. - `'copy'`: assert that they do **not** share memory. - `'same'`: assert that they **do** share memory. Defaults to None. :type check_same: {'copy', 'same'} or None :param obj: Object name used in assertion error messages. Defaults to 'pdarray'. :type obj: str :param index_values: Optional index shared by both `left` and `right`, used to enhance output in error messages. Defaults to None. :type index_values: Index or pdarray or 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 two Arkouda pdarray objects are equivalent. :param left: The first array to compare. :type left: pdarray :param right: The second array to compare. :type right: pdarray :param check_dtype: Whether to check dtype if both arrays are pdarrays. Defaults to True. :type check_dtype: bool :param err_msg: Custom assertion message to display on failure. Defaults to None. :type err_msg: str or None :param check_same: If not None, asserts whether `left` and `right` share the same memory: - 'copy': assert they do **not** share memory - 'same': assert they **do** share memory Defaults to None. :type check_same: {'copy', 'same'} or None :param obj: A name for the object being compared, used in assertion messages. Defaults to 'pdarray'. :type obj: str :param index_values: Optional index shared by both arrays, used to enhance output on failure. Defaults to None. :type index_values: Index or pdarray or 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 two Arkouda SegArray objects are equivalent. :param left: The first SegArray to compare. :type left: SegArray :param right: The second SegArray to compare. :type right: SegArray :param check_dtype: Whether to check dtype if both arrays contain pdarrays. Defaults to True. :type check_dtype: bool :param err_msg: Custom assertion message. Defaults to None. :type err_msg: str or None :param check_same: If not None, asserts whether `left` and `right` share the same memory. - 'copy': assert that they do **not** share memory. - 'same': assert that they **do** share memory. Defaults to None. :type check_same: {'copy', 'same'} or None :param obj: Name of the object being compared (used in assertion messages). Defaults to 'segarray'. :type obj: str .. py:function:: assert_arkouda_strings_equal(left, right, err_msg=None, check_same=None, obj: str = 'Strings', index_values=None) -> None Check that two `ak.Strings` arrays are equivalent. :param left: The first Strings object to compare. :type left: Strings :param right: The second Strings object to compare. :type right: Strings :param err_msg: Custom assertion message. Defaults to None. :type err_msg: str or None :param check_same: If not None, assert whether `left` and `right` share the same memory. - 'copy': assert that they do **not** share memory - 'same': assert that they **do** share memory Defaults to None. :type check_same: {'copy', 'same'} or None :param obj: A name for the object being compared, used in assertion messages. Defaults to 'Strings'. :type obj: str :param index_values: Optional index shared by both arrays, used in output. Defaults to None. :type index_values: Index or pdarray or None .. py:function:: assert_attr_equal(attr: str, left, right, obj: str = 'Attributes') -> None Check that attributes are equal. Both objects must have the given attribute. :param attr: The name of the attribute being compared. :type attr: str :param left: The first object to compare. :type left: object :param right: The second object to compare. :type right: object :param obj: A name for the object being compared, used in assertion messages. Defaults to 'Attributes'. :type obj: str .. 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: The first Categorical to compare. :type left: Categorical :param right: The second Categorical to compare. :type right: Categorical :param check_dtype: Whether to check that the integer dtype of the codes is the same. Defaults to True. :type check_dtype: bool :param check_category_order: Whether to compare the order of the categories (which implies identical integer codes). If False, only the resulting values are compared. The `ordered` attribute is always checked. Defaults to True. :type check_category_order: bool :param obj: A name for the object being compared, used in assertion messages. Defaults to 'Categorical'. :type obj: str .. 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. Defaults to True. If False, only the values are compared. :type compare_keys: bool .. py:function:: assert_equal(left, right, **kwargs) -> None Wrap 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 | Literal['equiv'] = 'equiv', 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. Defaults to True. :type check_dtype: bool :param check_index_type: Whether to check the Index class, dtype, and inferred_type are identical. Defaults to True. :type check_index_type: bool :param check_column_type: Whether to check the column class, dtype, and inferred_type are identical. Passed as the ``exact`` argument of :func:`assert_index_equal`. Defaults to 'equiv'. :type check_column_type: bool or {'equiv'} :param check_frame_type: Whether to check the DataFrame class is identical. Defaults to True. :type check_frame_type: bool :param check_names: Whether to check that the `names` attribute for both the `index` and `column` attributes of the DataFrame is identical. Defaults to True. :type check_names: bool :param check_exact: Whether to compare numbers exactly. Defaults to False. :type check_exact: bool :param check_categorical: Whether to compare internal Categoricals exactly. Defaults to True. :type check_categorical: bool :param check_like: If True, ignore the order of index and columns. Note: index labels must match their respective rows (as in columns); same labels must be with the same data. Defaults to False. :type check_like: bool :param rtol: Relative tolerance. Only used when `check_exact` is False. Defaults to 1e-5. :type rtol: float :param atol: Absolute tolerance. Only used when `check_exact` is False. Defaults to 1e-8. :type atol: float :param obj: A name for the object being compared, used in assertion messages. Defaults to 'DataFrame'. :type obj: str .. 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: The first Index to compare. :type left: Index :param right: The second Index to compare. :type right: Index :param exact: Whether to check that the Index class, dtype, and inferred_type are identical. Defaults to True. :type exact: bool :param check_names: Whether to check the `name` attribute. Defaults to True. :type check_names: bool :param check_exact: Whether to compare numbers exactly. Defaults to True. :type check_exact: bool :param check_categorical: Whether to compare internal Categorical values exactly. Defaults to True. :type check_categorical: bool :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. Defaults to True. :type check_order: bool :param rtol: Relative tolerance. Only used when `check_exact` is False. Defaults to 1e-5. :type rtol: float :param atol: Absolute tolerance. Only used when `check_exact` is False. Defaults to 1e-8. :type atol: float :param obj: A name for the object being compared, used in assertion messages. Defaults to 'Index'. :type obj: str .. 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: First Series to compare. :type left: Series :param right: Second Series to compare. :type right: Series :param check_dtype: Whether to check the Series dtype is identical. Defaults to True. :type check_dtype: bool :param check_index_type: Whether to check the Index class, dtype, and inferred_type are identical. Defaults to True. :type check_index_type: bool :param check_series_type: Whether to check that the Series class is identical. Defaults to True. :type check_series_type: bool :param check_names: Whether to check the Series and Index `name` attribute. Defaults to True. :type check_names: bool :param check_exact: Whether to compare numbers exactly. Defaults to False. :type check_exact: bool :param check_categorical: Whether to compare internal Categoricals exactly. Defaults to True. :type check_categorical: bool :param check_category_order: Whether to compare the category order of internal Categoricals. Defaults to True. :type check_category_order: bool :param rtol: Relative tolerance. Only used when `check_exact` is False. Defaults to 1e-5. :type rtol: float :param atol: Absolute tolerance. Only used when `check_exact` is False. Defaults to 1e-8. :type atol: float :param obj: Name of the object being compared, used in assertion messages. Defaults to 'Series'. :type obj: str :param check_index: Whether to check index equivalence. If False, only the values are compared. Defaults to 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: same labels must be with the same data. Defaults to False. :type check_like: bool .. 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)