[ENH] Improvements to categoricals (#930)

* Move all error checks to  as_categorical_checks; reduce complexity with a for loop; use hypothesis for tests

* lint formatting

* lint

* minor fix

* changelog

* edit to array check

* Update janitor/functions.py

Co-authored-by: Eric Ma <[email protected]>

* SEMBR fix

* reduce confusion in docs

* update based on review

* updates

* updates

* spelling fix

* add example code for conditional_join

* use python's naming convention for classes

Co-authored-by: Eric Ma <[email protected]>

Author: samukweku

CHANGELOG.md

@@ -1,7 +1,6 @@
 # Changelog
 
 ## [Unreleased]
--   [ENH] Deprecate `aggfunc` from `pivot_wider`; aggregation can be chained with pandas' `groupby`.
 -   [BUG] Fix conditional join issue for multiple conditions, where pd.eval fails to evaluate if numexpr is installed. #898 @samukweku
 -   [ENH] Added `case_when` to handle multiple conditionals and replacement values. Issue #736. @robertmitchellv
 -   [ENH] Deprecate `new_column_names` and `merge_frame` from `process_text`. Only existing columns are supported. @samukweku
@@ -10,6 +9,7 @@
 -   [INF] Simplify a bit linting, use pre-commit as the CI linting checker. @Zeroto521
 -   [ENH] Fix bug in `pivot_longer` for wrong output when `names_pattern` is a sequence with a single value. Issue #885 @samukweku
 -   [ENH] Deprecate `aggfunc` from `pivot_wider`; aggregation can be chained with pandas' `groupby`.
+-   [ENH] `As_Categorical` deprecated from `encode_categorical`; a tuple of `(categories, order)` suffices for **kwargs. @samukweku
 
 ## [v0.21.2] - 2021-09-01
 

janitor/functions.py

@@ -13,7 +13,6 @@
     Hashable,
     Iterable,
     List,
-    NamedTuple,
     Optional,
     Pattern,
     Set,
@@ -52,7 +51,6 @@
     _replace_original_empty_string_with_none,
     _select_columns,
     _strip_underscores,
-    asCategorical,
     check,
     check_column,
     deprecated_alias,
@@ -473,23 +471,6 @@ def get_dupes(
     return df[dupes == True]  # noqa: E712
 
 
-def As_Categorical(
-    categories: Optional[List] = None,
-    order: Optional[str] = None,
-) -> NamedTuple:
-    """
-    Helper function for `encode_categorical`. It makes creating the
-    `categories` and `order` more explicit. Inspired by pd.NamedAgg.
-    :param categories: list-like object to create new categorical column.
-    :param order: string object that can be either "sort" or "appearance".
-        If "sort", the `categories` argument will be sorted with np.sort;
-        if "apperance", the `categories` argument will be used as is.
-    :returns: A namedtuple of (`categories`, `order`).
-    """
-
-    return asCategorical(categories=categories, order=order)
-
-
 @pf.register_dataframe_method
 @deprecated_alias(columns="column_names")
 def encode_categorical(
@@ -503,9 +484,6 @@ def encode_categorical(
     Categories and order can be explicitly specified via the `kwargs` option, which is a
     pairing of column name and a tuple of (categories, order).
 
-    The `janitor.As_Categorical` function is provided to make it clearer what the arguments
-    to the function are.
-
     It is syntactic sugar around `pd.Categorical`.
 
     This method does not mutate the original DataFrame.
@@ -594,21 +572,6 @@ def encode_categorical(
     if the `order` is "sort", the categories argument is sorted in ascending order;
     if `order` is ``None``, then the categories argument is applied unordered.
 
-    The ``janitor.As_Categorical`` function can also be used to make clearer
-    what the arguments to the function are::
-
-        df = (pd.DataFrame(...)
-                .encode_categorical(
-                    col1 = As_Categorical(
-                                categories = [3, 2, 1, 4],
-                                order = "appearance"
-                                ),
-                    col2 = As_Categorical(
-                                categories = ['a','d','c','b'],
-                                order = "sort"
-                                )
-                    )
-            )
 
     A User Warning will be generated if some or all of the unique values
     in the column are not present in the provided `categories` argument.
@@ -617,7 +580,7 @@ def encode_categorical(
 
         df = (pd.DataFrame(...)
                 .encode_categorical(
-                    col1 = As_Categorical(
+                    col1 = (
                             categories = [4, 5, 6],
                             order = "appearance"
                             )
@@ -663,10 +626,9 @@ def encode_categorical(
         df = jn.encode_categorical(
                     df,
                     col1 = (categories, order),
-                    col2 = jn.As_Categorical(
-                                categories = [values],
-                                order="sort"/"appearance"/None
-                                )
+                    col2 = (categories = [values],
+                    order="sort"  # or "appearance" or None
+
                 )
 
     Method chaining syntax:
@@ -684,31 +646,22 @@ def encode_categorical(
             pd.DataFrame(...)
             .encode_categorical(
                 col1 = (categories, order),
-                col2 = jn.As_Categorical(
-                            categories = [values]/None,
-                            order="sort"/"appearance"/None
-                            )
+                col2 = (categories = [values]/None,
+                        order="sort"  # or "appearance" or None
+                        )
         )
 
 
     :param df: The pandas DataFrame object.
     :param column_names: A column name or an iterable (list or
         tuple) of column names.
     :param kwargs: A pairing of column name to a tuple of (`categories`, `order`).
-        There is also the `janitor.As_Categorical` function, which creates a
-        namedtuple of (`categories`, `order`) to make it clearer what the arguments
-        are. This is useful in creating categorical columns that are ordered, or
+        This is useful in creating categorical columns that are ordered, or
         if the user needs to explicitly specify the categories.
     :returns: A pandas DataFrame.
-    :raises JanitorError: if a column specified within ``column_names``
-        is not found in the DataFrame.
-    :raises JanitorError: if ``column_names`` is not hashable
-        nor iterable.
     :raises ValueError: if both ``column_names`` and ``kwargs`` are provided.
     """  # noqa: E501
 
-    df = df.copy()
-
     if all((column_names, kwargs)):
         raise ValueError(
             """
@@ -719,28 +672,17 @@ def encode_categorical(
     # column_names deal with only category dtype (unordered)
     # kwargs takes care of scenarios where user wants an ordered category
     # or user supplies specific categories to create the categorical
-    if column_names:
-        if isinstance(column_names, (list, Tuple)):
-            for col in column_names:
-                if col not in df.columns:
-                    raise JanitorError(
-                        f"{col} missing from DataFrame columns!"
-                    )
-                df[col] = pd.Categorical(df[col])
-        elif isinstance(column_names, Hashable):
-            if column_names not in df.columns:
-                raise JanitorError(
-                    f"{column_names} missing from DataFrame columns!"
-                )
-            df[column_names] = pd.Categorical(df[column_names])
-        else:
-            raise JanitorError(
-                "kwarg `column_names` must be hashable or iterable!"
-            )
-        return df
+    if column_names is not None:
+        check("column_names", column_names, [list, tuple, Hashable])
+        if isinstance(column_names, (list, tuple)):
+            check_column(df, column_names)
+            dtypes = {col: "category" for col in column_names}
+            return df.astype(dtypes)
+        if isinstance(column_names, Hashable):
+            check_column(df, [column_names])
+            return df.astype({column_names: "category"})
 
-    df = _computations_as_categorical(df, **kwargs)
-    return df
+    return _computations_as_categorical(df, **kwargs)
 
 
 @pf.register_dataframe_method
@@ -6359,10 +6301,43 @@ def conditional_join(
     The join is done only on the columns.
     MultiIndex columns are not supported.
 
-    For non-equi joins, onnly numeric and date columns are supported.
+    For non-equi joins, only numeric and date columns are supported.
 
     Only `inner`, `left`, and `right` joins are supported.
 
+    Functional usage syntax:
+
+    .. code-block:: python
+
+        import pandas as pd
+        import janitor as jn
+
+        df = pd.DataFrame(...)
+        right = pd.DataFrame(...)
+
+        df = jn.conditional_join(
+                df,
+                right,
+                (col_from_df, col_from_right, join_operator),
+                (col_from_df, col_from_right, join_operator),
+                ...,
+                how = 'inner' # or left/right
+                sort_by_appearance = True # or False
+                )
+
+    Method chaining syntax:
+
+    .. code-block:: python
+
+        df.conditional_join(
+            right,
+            (col_from_df, col_from_right, join_operator),
+            (col_from_df, col_from_right, join_operator),
+            ...,
+            how = 'inner' # or left/right
+            sort_by_appearance = True # or False
+            )
+
 
     :param df: A Pandas DataFrame.
     :param right: Named Series or DataFrame to join to.