Add MWE for encode_categorical; fixed formatting of error messages

Author: thatlittleboy

janitor/functions/encode_categorical.py

@@ -1,10 +1,12 @@
+import warnings
+from enum import Enum
 from typing import Hashable, Iterable, Union
+
 import pandas_flavor as pf
 import pandas as pd
 from pandas.api.types import is_list_like
-import warnings
+
 from janitor.utils import check, check_column, deprecated_alias
-from enum import Enum
 
 
 @pf.register_dataframe_method
@@ -24,80 +26,79 @@ def encode_categorical(
 
     Note: In versions < 0.20.11, this method mutates the original DataFrame.
 
+    If `column_names` is specified, these column(s) are cast to unordered categorical
+    dtypes.
+
     If `categories` is `None` in the `kwargs` tuple, then the
     values for `categories` are inferred from the column;
     if `order` is `None`, then the values for `categories` are applied unordered.
 
     `column_names` and `kwargs` parameters cannot be used at the same time.
 
-    Functional usage syntax:
-
-    ```python
-        import pandas as pd
-        import janitor as jn
-    ```
-
-    - With `column_names`
-
-    ```python
-        categorical_cols = ['col1', 'col2', 'col4']
-        df = jn.encode_categorical(
-                    df,
-                    columns = categorical_cols)  # one way
-    ```
-
-    - With `kwargs`
-
-    ```python
-        df = jn.encode_categorical(
-                    df,
-                    col1 = (categories, order),
-                    col2 = (categories = [values],
-                    order="sort"  # or "appearance" or None
-
-                )
-    ```
-
-    Method chaining syntax:
-
-    - With `column_names`
-
-    ```python
-        categorical_cols = ['col1', 'col2', 'col4']
-        df = (pd.DataFrame(...)
-                .encode_categorical(columns=categorical_cols)
-            )
-    ```
-
-    - With `kwargs`
-
-    ```python
-        df = (
-            pd.DataFrame(...)
-            .encode_categorical(
-                col1 = (categories, order),
-                col2 = (categories = [values]/None,
-                        order="sort"  # or "appearance" or None
-                        )
-        )
-    ```
+    Example: Using `column_names`
+
+        >>> import pandas as pd
+        >>> import janitor
+        >>> df = pd.DataFrame({
+        ...     "foo": ["b", "b", "a", "c", "b"],
+        ...     "bar": range(4, 9),
+        ... })
+        >>> df
+          foo  bar
+        0   b    4
+        1   b    5
+        2   a    6
+        3   c    7
+        4   b    8
+        >>> df.dtypes
+        foo    object
+        bar     int64
+        dtype: object
+        >>> enc_df = df.encode_categorical(column_names="foo")
+        >>> enc_df.dtypes
+        foo    category
+        bar       int64
+        dtype: object
+        >>> enc_df["foo"].cat.categories
+        Index(['a', 'b', 'c'], dtype='object')
+        >>> enc_df["foo"].cat.ordered
+        False
+
+    Example: Using `kwargs` to specify an ordered categorical.
+
+        >>> import pandas as pd
+        >>> import janitor
+        >>> df = pd.DataFrame({
+        ...     "foo": ["b", "b", "a", "c", "b"],
+        ...     "bar": range(4, 9),
+        ... })
+        >>> df.dtypes
+        foo    object
+        bar     int64
+        dtype: object
+        >>> enc_df = df.encode_categorical(foo=(None, "appearance"))
+        >>> enc_df.dtypes
+        foo    category
+        bar       int64
+        dtype: object
+        >>> enc_df["foo"].cat.categories
+        Index(['b', 'a', 'c'], dtype='object')
+        >>> enc_df["foo"].cat.ordered
+        True
 
     :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`).
-        This is useful in creating categorical columns that are ordered, or
-        if the user needs to explicitly specify the categories.
+    :param kwargs: A mapping from column name to a tuple of (`categories`, `order`).
+        `categories` should be list-like (specifying the categories explicitly) or `None`.
+        `order` is only allowed to be `'sort'`, `'appearance'` or `None`.
     :returns: A pandas DataFrame.
-    :raises ValueError: if both ``column_names`` and ``kwargs`` are provided.
+    :raises ValueError: If both `column_names` and `kwargs` are provided.
     """  # noqa: E501
 
     if all((column_names, kwargs)):
         raise ValueError(
-            """
-            Only one of `column_names` or `kwargs`
-            can be provided.
-            """
+            "Only one of `column_names` or `kwargs` can be provided."
         )
     # column_names deal with only category dtype (unordered)
     # kwargs takes care of scenarios where user wants an ordered category
@@ -125,7 +126,7 @@ def _computations_as_categorical(df: pd.DataFrame, **kwargs) -> pd.DataFrame:
     The defaults for the tuple are (None, None)
     and will return a categorical dtype
     with no order and categories inferred from the column.
-    A DataFrame, with catetorical columns, is returned.
+    A DataFrame, with categorical columns, is returned.
     """
 
     categories_dict = _as_categorical_checks(df, **kwargs)
@@ -136,10 +137,10 @@ def _computations_as_categorical(df: pd.DataFrame, **kwargs) -> pd.DataFrame:
         cat,
         order,
     ) in categories_dict.items():
-        error_msg = f"""
-                     Kindly ensure there is at least
-                     one non-null value in {column_name}.
-                     """
+        error_msg = (
+            "Kindly ensure there is at least one non-null value in "
+            f"{column_name}."
+        )
         if (cat is None) and (order is None):
             cat_dtype = pd.CategoricalDtype()
 
@@ -182,30 +183,24 @@ def _as_categorical_checks(df: pd.DataFrame, **kwargs) -> dict:
     :param kwargs: A pairing of column name
         to a tuple of (`categories`, `order`).
     :returns: A dictionary.
-    :raises TypeError: if the value in ``kwargs`` is not a tuple.
-    :raises ValueError: if ``categories`` is not a 1-D array.
-    :raises ValueError: if ``order`` is not one of
+    :raises TypeError: If the value in `kwargs` is not a tuple.
+    :raises ValueError: If `categories` is not a 1-D array.
+    :raises ValueError: If `order` is not one of
         `sort`, `appearance`, or `None`.
     """
 
-    # column checks
     check_column(df, kwargs)
 
     categories_dict = {}
 
     for column_name, value in kwargs.items():
-        # type check
         check("Pair of `categories` and `order`", value, [tuple])
 
         len_value = len(value)
-
         if len_value != 2:
             raise ValueError(
-                f"""
-                The tuple of (categories, order) for {column_name}
-                should be length 2; the tuple provided is
-                length {len_value}.
-                """
+                f"The tuple of (categories, order) for {column_name} should "
+                f"be length 2; the tuple provided is length {len_value}."
             )
 
         cat, order = value
@@ -221,10 +216,8 @@ def _as_categorical_checks(df: pd.DataFrame, **kwargs) -> dict:
             arr_ndim = checker.ndim
             if (arr_ndim != 1) or isinstance(checker, pd.MultiIndex):
                 raise ValueError(
-                    f"""
-                    {cat} is not a 1-D array.
-                    Kindly provide a 1-D array-like object to `categories`.
-                    """
+                    f"{cat} is not a 1-D array. Kindly provide a 1-D "
+                    "array-like object to `categories`."
                 )
 
             if not isinstance(checker, (pd.Series, pd.Index)):
@@ -237,51 +230,38 @@ def _as_categorical_checks(df: pd.DataFrame, **kwargs) -> dict:
 
             if not checker.is_unique:
                 raise ValueError(
-                    """
-                    Kindly provide unique,
-                    non-null values for `categories`.
-                    """
+                    "Kindly provide unique, non-null values for `categories`."
                 )
 
             if checker.empty:
                 raise ValueError(
-                    """
-                    Kindly ensure there is at least
-                    one non-null value in `categories`.
-                    """
+                    "Kindly ensure there is at least one non-null value in "
+                    "`categories`."
                 )
 
             # uniques, without nulls
             uniques = df[column_name].factorize(sort=False)[-1]
             if uniques.empty:
                 raise ValueError(
-                    f"""
-                     Kindly ensure there is at least
-                     one non-null value in {column_name}.
-                     """
+                    "Kindly ensure there is at least one non-null value "
+                    f"in {column_name}."
                 )
 
             missing = uniques.difference(checker, sort=False)
             if not missing.empty and (uniques.size > missing.size):
                 warnings.warn(
-                    f"""
-                     Values {tuple(missing)} are missing from
-                     the provided categories {cat}
-                     for {column_name}; this may create nulls
-                     in the new categorical column.
-                     """,
+                    "Values {tuple(missing)} are missing from the provided "
+                    f"categories {cat} for {column_name}; this may create "
+                    "nulls in the new categorical column.",
                     UserWarning,
                     stacklevel=2,
                 )
 
             elif uniques.equals(missing):
                 warnings.warn(
-                    f"""
-                     None of the values in {column_name} are in
-                     {cat};
-                     this might create nulls for all values
-                     in the new categorical column.
-                     """,
+                    f"None of the values in {column_name} are in {cat}; "
+                    "this might create nulls for all values in the new "
+                    "categorical column.",
                     UserWarning,
                     stacklevel=2,
                 )
@@ -292,10 +272,8 @@ def _as_categorical_checks(df: pd.DataFrame, **kwargs) -> dict:
             category_order_types = [ent.value for ent in _CategoryOrder]
             if order.lower() not in category_order_types:
                 raise ValueError(
-                    """
-                    `order` argument should be one of
-                    "appearance", "sort" or `None`.
-                    """
+                    "`order` argument should be one of 'appearance', "
+                    "'sort' or `None`."
                 )
 
         categories_dict[column_name] = value