lreshape and wide_to_long documentation (Closes #33417)

doc/source/reference/frame.rst

@@ -234,6 +234,8 @@ Reshaping, sorting, transposing
    DataFrame.unstack
    DataFrame.swapaxes
    DataFrame.melt
+   lreshape
+   wide_to_long
    DataFrame.explode
    DataFrame.squeeze
    DataFrame.to_xarray

doc/source/reference/general_functions.rst

@@ -25,6 +25,7 @@ Data manipulations
    get_dummies
    factorize
    unique
+   lreshape
    wide_to_long
 
 Top-level missing data

doc/source/whatsnew/v1.1.0.rst

@@ -88,7 +88,7 @@ Other enhancements
 - :class:`Series.str` now has a `fullmatch` method that matches a regular expression against the entire string in each row of the series, similar to `re.fullmatch` (:issue:`32806`).
 - :meth:`DataFrame.sample` will now also allow array-like and BitGenerator objects to be passed to ``random_state`` as seeds (:issue:`32503`)
 - :meth:`MultiIndex.union` will now raise `RuntimeWarning` if the object inside are unsortable, pass `sort=False` to suppress this warning (:issue:`33015`)
--
+- Updated :meth:`pandas.lreshape` and :meth:`pandas.wide_to_long` documentation (:issue:`33417`)
 
 .. ---------------------------------------------------------------------------
 

pandas/core/frame.py

@@ -5913,6 +5913,10 @@ def groupby(
             duplicate values for one index/column pair.
         DataFrame.unstack : Pivot based on the index values instead of a
             column.
+        lreshape : Reshape wide-format data to format. Generalized inverse of
+            DataFrame.pivot.
+        wide_to_long : Wide panel to long format. Less flexible but more
+            user-friendly than melt.
 
         Notes
         -----
@@ -6067,6 +6071,12 @@ def pivot(self, index=None, columns=None, values=None) -> "DataFrame":
         --------
         DataFrame.pivot : Pivot without aggregation that can handle
             non-numeric data.
+        DataFrame.melt: Unpivot a DataFrame from wide to long format,
+            optionally leaving identifiers set.
+        lreshape : Reshape wide-format data to format. Generalized inverse of
+            DataFrame.pivot.
+        wide_to_long : Wide panel to long format. Less flexible but more
+            user-friendly than melt.
 
         Examples
         --------
@@ -6511,7 +6521,11 @@ def unstack(self, level=-1, fill_value=None):
     See Also
     --------
     %(other)s : Identical method.
+    wide_to_long : Wide panel to long format. Less flexible but more
+        user-friendly than melt.
     pivot_table : Create a spreadsheet-style pivot table as a DataFrame.
+    lreshape : Reshape wide-format data to format. Generalized inverse of
+        DataFrame.pivot.
     DataFrame.pivot : Return reshaped DataFrame organized
         by given index / column values.
     DataFrame.explode : Explode a DataFrame from list-like

pandas/core/reshape/melt.py

@@ -121,14 +121,44 @@ def melt(
 @deprecate_kwarg(old_arg_name="label", new_arg_name=None)
 def lreshape(data: DataFrame, groups, dropna: bool = True, label=None) -> DataFrame:
     """
-    Reshape long-format data to wide. Generalized inverse of DataFrame.pivot
+    Reshape wide-format data to long. Generalized inverse of DataFrame.pivot.
+
+    Similar to ``pd.melt`` but more user-friendly. Accepts a dictionary,
+    ``groups``, in which each key is a new column name and each value is a
+    list of old column names that will be "melted" under the new column name as
+    part of the reshape.
 
     Parameters
     ----------
     data : DataFrame
+        The wide-format DataFrame.
     groups : dict
-        {new_name : list_of_columns}
-    dropna : boolean, default True
+        {new_name : list_of_columns}.
+    dropna : bool, default True
+        Do not include columns whose entries are all NaN.
+    label : None
+        Not used.
+
+        .. deprecated:: 1.0.0
+
+    Returns
+    -------
+    DataFrame
+        Reshaped DataFrame.
+
+    See Also
+    --------
+    melt : Unpivot a DataFrame from wide to long format, optionally leaving
+        identifiers set.
+    pivot : Create a spreadsheet-style pivot table as a DataFrame.
+    DataFrame.pivot : Pivot without aggregation that can handle
+        non-numeric data.
+    DataFrame.pivot_table : Generalization of pivot that can handle
+        duplicate values for one index/column pair.
+    DataFrame.unstack : Pivot based on the index values instead of a
+        column.
+    wide_to_long : Wide panel to long format. Less flexible but more
+        user-friendly than melt.
 
     Examples
     --------
@@ -146,10 +176,6 @@ def lreshape(data: DataFrame, groups, dropna: bool = True, label=None) -> DataFr
     1  Yankees  2007  573
     2  Red Sox  2008  545
     3  Yankees  2008  526
-
-    Returns
-    -------
-    reshaped : DataFrame
     """
     if isinstance(groups, dict):
         keys = list(groups.keys())
@@ -239,6 +265,20 @@ def wide_to_long(
         A DataFrame that contains each stub name as a variable, with new index
         (i, j).
 
+    See Also
+    --------
+    melt : Unpivot a DataFrame from wide to long format, optionally leaving
+        identifiers set.
+    pivot : Create a spreadsheet-style pivot table as a DataFrame.
+    DataFrame.pivot : Pivot without aggregation that can handle
+        non-numeric data.
+    DataFrame.pivot_table : Generalization of pivot that can handle
+        duplicate values for one index/column pair.
+    DataFrame.unstack : Pivot based on the index values instead of a
+        column.
+    lreshape : Reshape wide-format data to format. Generalized inverse of
+        DataFrame.pivot.
+
     Notes
     -----
     All extra variables are left untouched. This simply uses