Add MWE for label_encode and factorize_columns

Author: thatlittleboy

janitor/functions/factorize_columns.py

@@ -1,3 +1,4 @@
+"""Implementation of the `factorize_columns` function"""
 from typing import Hashable, Iterable, Union
 import pandas_flavor as pf
 import pandas as pd
@@ -13,50 +14,49 @@ def factorize_columns(
     **kwargs,
 ) -> pd.DataFrame:
     """
-    Converts labels into numerical data
+    Converts labels into numerical data.
 
     This method will create a new column with the string `_enc` appended
     after the original column's name.
     This can be overriden with the suffix parameter.
 
-    Internally this method uses pandas `factorize` method.
+    Internally, this method uses pandas `factorize` method.
     It takes in an optional suffix and keyword arguments also.
     An empty string as suffix will override the existing column.
 
     This method mutates the original DataFrame.
 
-    Functional usage syntax:
+    Example:
 
-    ```python
-    df = factorize_columns(
-        df,
-        column_names="my_categorical_column",
-        suffix="_enc"
-    )  # one way
-    ```
-
-    Method chaining syntax:
-
-    ```python
-    import pandas as pd
-    import janitor
-    categorical_cols = ['col1', 'col2', 'col4']
-    df = (
-        pd.DataFrame(...)
-        .factorize_columns(
-            column_names=categorical_cols,
-            suffix="_enc"
-        )
-    )
-    ```
+        >>> 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.factorize_columns(column_names="foo")
+          foo  bar  foo_enc
+        0   b    4        0
+        1   b    5        0
+        2   a    6        1
+        3   c    7        2
+        4   b    8        0
 
     :param df: The pandas DataFrame object.
-    :param column_names: A column name or an iterable (list
-        or tuple) of column names.
-    :param suffix: Suffix to be used for the new column. Default value is _enc.
-        An empty string suffix means, it will override the existing column
+    :param column_names: A column name or an iterable (list or tuple) of
+        column names.
+    :param suffix: Suffix to be used for the new column.
+        An empty string suffix means, it will override the existing column.
     :param **kwargs: Keyword arguments. It takes any of the keyword arguments,
-        which the pandas factorize method takes like sort,na_sentinel,size_hint
+        which the pandas factorize method takes like `sort`, `na_sentinel`,
+        `size_hint`.
 
     :returns: A pandas DataFrame.
     """

janitor/functions/label_encode.py

@@ -1,3 +1,4 @@
+"""Implementation of `label_encode` function"""
 from typing import Hashable, Iterable, Union
 import warnings
 import pandas_flavor as pf
@@ -10,43 +11,62 @@
 @pf.register_dataframe_method
 @deprecated_alias(columns="column_names")
 def label_encode(
-    df: pd.DataFrame, column_names: Union[str, Iterable[str], Hashable]
+    df: pd.DataFrame,
+    column_names: Union[str, Iterable[str], Hashable],
 ) -> pd.DataFrame:
     """
     Convert labels into numerical data.
 
     This method will create a new column with the string `_enc` appended
-    after the original column's name. Consider this to be syntactic sugar.
+    after the original column's name.
+    Consider this to be syntactic sugar.
+    This function uses the `factorize` pandas function under the hood.
 
-    This method behaves differently from `encode_categorical`. This method
-    creates a new column of numeric data. `encode_categorical` replaces the
-    dtype of the original column with a *categorical* dtype.
+    This method behaves differently from
+    [`encode_categorical`][janitor.functions.encode_categorical.encode_categorical].
+    This method creates a new column of numeric data.
+    [`encode_categorical`][janitor.functions.encode_categorical.encode_categorical]
+    replaces the dtype of the original column with a *categorical* dtype.
 
     This method mutates the original DataFrame.
 
-    Functional usage syntax:
+    Example:
 
-    ```python
-    df = label_encode(df, column_names="my_categorical_column")  # one way
-    ```
+        >>> 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.label_encode(column_names="foo")
+          foo  bar  foo_enc
+        0   b    4        0
+        1   b    5        0
+        2   a    6        1
+        3   c    7        2
+        4   b    8        0
 
-    Method chaining syntax:
+    !!!note
 
-    ```python
-    import pandas as pd
-    import janitor
-    categorical_cols = ['col1', 'col2', 'col4']
-    df = pd.DataFrame(...).label_encode(column_names=categorical_cols)
-    ```
+        This function will be deprecated in a 1.x release.
+        Please use [`factorize_columns`][janitor.functions.factorize_columns.factorize_columns]
+        instead.
 
     :param df: The pandas DataFrame object.
     :param column_names: A column name or an iterable (list
         or tuple) of column names.
     :returns: A pandas DataFrame.
-    """
+    """  # noqa: E501
     warnings.warn(
-        "label_encode will be deprecated in a 1.x release. \
-        Please use factorize_columns instead"
+        "`label_encode` will be deprecated in a 1.x release. "
+        "Please use `factorize_columns` instead."
     )
     df = _factorize(df, column_names, "_enc")
     return df