SNOW-2002725: Add support for DataFrame.boxplot (#3532)

Author: sfc-gh-helmeleegy

CHANGELOG.md

@@ -58,6 +58,7 @@ local ingestion. By default, local ingestion uses multithreading. Multiprocessin
 - Added support for `pd.explain_switch()` to return debugging information on hybrid execution decisions.
 - Support `pd.read_snowflake` when the global modin backend is `Pandas`.
 - Added support for `pd.to_dynamic_table`, `pd.to_iceberg`, and `pd.to_view`.
+- Added support for `DataFrame.boxplot`.
 
 #### Improvements
 

docs/source/modin/dataframe.rst

@@ -233,6 +233,13 @@ DataFrame
     DataFrame.last_valid_index
     DataFrame.resample
 
+.. rubric:: Plotting
+
+.. autosummary::
+    :toctree: pandas_api/
+
+    DataFrame.boxplot
+
 .. rubric:: Serialization / IO / conversion
 
 .. autosummary::

docs/source/modin/supported/dataframe_supported.rst

@@ -109,7 +109,7 @@ Methods
 +-----------------------------+---------------------------------+----------------------------------+----------------------------------------------------+
 | ``bool``                    | N                               |                                  |                                                    |
 +-----------------------------+---------------------------------+----------------------------------+----------------------------------------------------+
-| ``boxplot``                 | N                               |                                  |                                                    |
+| ``boxplot``                 | Y                               |                                  |                                                    |
 +-----------------------------+---------------------------------+----------------------------------+----------------------------------------------------+
 | ``clip``                    | N                               |                                  |                                                    |
 +-----------------------------+---------------------------------+----------------------------------+----------------------------------------------------+

src/snowflake/snowpark/modin/plugin/docstrings/base.py

@@ -2220,15 +2220,14 @@ def pct_change():
         fill_method : {'backfill', 'bfill', 'pad', 'ffill', None}, default 'pad'
             How to handle NAs **before** computing percent changes.
 
-            .. deprecated:: 2.1
-                All options of `fill_method` are deprecated except `fill_method=None`.
+            All options of `fill_method` are deprecated except `fill_method=None`.
 
         limit : int, default None
             The number of consecutive NAs to fill before stopping.
 
             Snowpark pandas does not yet support this parameter.
 
-            .. deprecated:: 2.1
+            Deprecated parameter.
 
         freq : DateOffset, timedelta, or str, optional
             Increment to use from time series API (e.g. 'ME' or BDay()).
@@ -2521,7 +2520,7 @@ def resample():
             Which axis to use for up- or down-sampling. For Series this parameter is unused and defaults to 0.
             Snowpark pandas only supports ``axis`` 0 and DatetimeIndex.
 
-            Deprecated since version 2.0.0: Use frame.T.resample(…) instead.
+            Deprecated: Use frame.T.resample(…) instead.
         closed : {'right', 'left'}, default None
             Which side of bin interval is closed. The default is 'left' for all frequency offsets except for
             'ME', 'YE', 'QE', 'BME', 'BA', 'BQE', and 'W' which all have a default of 'right'.
@@ -2536,7 +2535,7 @@ def resample():
             For PeriodIndex only, controls whether to use the start or end of rule.
             Snowpark pandas does not support PeriodIndex.
 
-            Deprecated since version 2.2.0: Convert PeriodIndex to DatetimeIndex before resampling instead.
+            Deprecated: Convert PeriodIndex to DatetimeIndex before resampling instead.
         kind : {'timestamp', 'period'}, optional, default None
             Pass 'timestamp' to convert the resulting index to a DateTimeIndex
             or 'period' to convert it to a PeriodIndex. By default, the input representation is retained.

src/snowflake/snowpark/modin/plugin/docstrings/dataframe.py

@@ -1181,7 +1181,7 @@ def bfill():
         downcast : dict, default is None
             A dict of item->dtype of what to downcast if possible, or the string ‘infer’ which will try to downcast to an appropriate equal type (e.g. float64 to int64 if possible).
 
-        Deprecated since version 2.2.0.
+        Deprecated parameter.
 
         Returns
         -------
@@ -1231,7 +1231,144 @@ def bfill():
 
     def boxplot():
         """
-        Make a box plot from ``DataFrame`` columns.
+        Make a box plot from DataFrame columns.
+
+        Make a box-and-whisker plot from DataFrame columns, optionally grouped by some other columns. A box plot is a method for graphically depicting groups of numerical data through their quartiles. The box extends from the Q1 to Q3 quartile values of the data, with a line at the median (Q2). The whiskers extend from the edges of box to show the range of the data. By default, they extend no more than 1.5 * IQR (IQR = Q3 - Q1) from the edges of the box, ending at the farthest data point within that interval. Outliers are plotted as separate dots.
+
+        For further details see Wikipedia’s entry for [boxplot](https://en.wikipedia.org/wiki/Box_plot).
+
+        Parameters
+        ----------
+        column : str or list of str, optional
+            Column name or list of names, or vector. Can be any valid input to pandas.DataFrame.groupby().
+
+        by : str or array-like, optional
+            Column in the DataFrame to pandas.DataFrame.groupby(). One box-plot will be done per value of columns in by.
+
+        ax : object of class matplotlib.axes.Axes, optional
+            The matplotlib axes to be used by boxplot.
+
+        fontsize : float or str
+            Tick label font size in points or as a string (e.g., large).
+
+        rot : float, default 0
+            The rotation angle of labels (in degrees) with respect to the screen coordinate system.
+
+        grid : bool, default True
+            Setting this to True will show the grid.
+
+        fig : sizeA tuple (width, height) in inches
+            The size of the figure to create in matplotlib.
+
+        layout : tuple (rows, columns), optional
+            For example, (3, 5) will display the subplots using 3 rows and 5 columns, starting from the top-left.
+
+        return_type : {‘axes’, ‘dict’, ‘both’} or None, default ‘axes’
+            The kind of object to return. The default is axes.
+
+            - ‘axes’ returns the matplotlib axes the boxplot is drawn on.
+
+            - ‘dict’ returns a dictionary whose values are the matplotlib Lines of the boxplot.
+
+            - ‘both’ returns a namedtuple with the axes and dict.
+
+            - when grouping with by, a Series mapping columns to return_type is returned.
+
+            If return_type is None, a NumPy array of axes with the same shape as layout is returned.
+
+        backend : str, default None
+            Backend to use instead of the backend specified in the option plotting.backend. For instance, ‘matplotlib’. Alternatively, to specify the plotting.backend for the whole session, set pd.options.plotting.backend.
+
+        **kwargs
+            All other plotting keyword arguments to be passed to matplotlib.pyplot.boxplot().
+
+        Returns
+        -------
+        result
+            See Notes.
+
+        See also
+        --------
+        Series.plot.hist
+            Make a histogram.
+
+        matplotlib.pyplot.boxplot
+            Matplotlib equivalent plot.
+
+        Notes
+        -----
+        The return type depends on the return_type parameter:
+
+        - ‘axes’ : object of class matplotlib.axes.Axes
+
+        - ‘dict’ : dict of matplotlib.lines.Line2D objects
+
+        - ‘both’ : a namedtuple with structure (ax, lines)
+
+        For data grouped with by, return a Series of the above or a numpy array:
+
+        - Series
+
+        - array (for return_type = None)
+
+        Use return_type='dict' when you want to tweak the appearance of the lines after plotting. In this case a dict containing the Lines making up the boxes, caps, fliers, medians, and whiskers is returned.
+
+        Examples
+        --------
+        Boxplots can be created for every column in the dataframe by df.boxplot() or indicating the columns to be used:
+
+        >>> np.random.seed(1234)
+        >>> df = pd.DataFrame(np.random.randn(10, 4),
+        ...                   columns=['Col1', 'Col2', 'Col3', 'Col4'])
+        >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3'])
+        ../../_images/pandas-DataFrame-boxplot-1.png
+
+        Boxplots of variables distributions grouped by the values of a third variable can be created using the option by. For instance:
+
+        >>> df = pd.DataFrame(np.random.randn(10, 2),
+        ...                   columns=['Col1', 'Col2'])
+        >>> df['X'] = pd.Series(['A', 'A', 'A', 'A', 'A',
+        ...                      'B', 'B', 'B', 'B', 'B'])
+        >>> boxplot = df.boxplot(by='X')
+
+        A list of strings (i.e. ['X', 'Y']) can be passed to boxplot in order to group the data by combination of the variables in the x-axis:
+
+        >>> df = pd.DataFrame(np.random.randn(10, 3),
+        ...                   columns=['Col1', 'Col2', 'Col3'])
+        >>> df['X'] = pd.Series(['A', 'A', 'A', 'A', 'A',
+        ...                      'B', 'B', 'B', 'B', 'B'])
+        >>> df['Y'] = pd.Series(['A', 'B', 'A', 'B', 'A',
+        ...                      'B', 'A', 'B', 'A', 'B'])
+        >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by=['X', 'Y'])
+
+        The layout of boxplot can be adjusted giving a tuple to layout:
+
+        >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by='X',
+        ...                      layout=(2, 1))
+
+        Additional formatting can be done to the boxplot, like suppressing the grid (grid=False), rotating the labels in the x-axis (i.e. rot=45) or changing the fontsize (i.e. fontsize=15):
+
+        >>> boxplot = df.boxplot(grid=False, rot=45, fontsize=15)
+
+        The parameter return_type can be used to select the type of element returned by boxplot. When return_type='axes' is selected, the matplotlib axes on which the boxplot is drawn are returned:
+
+        >>> boxplot = df.boxplot(column=['Col1', 'Col2'], return_type='axes')
+        >>> type(boxplot)
+        <class 'matplotlib.axes._axes.Axes'>
+
+        When grouping with by, a Series mapping columns to return_type is returned:
+
+        >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by='X',
+        ...                      return_type='axes')
+        type(boxplot)
+        <class 'pandas.Series'>
+
+        If return_type is None, a NumPy array of axes with the same shape as layout is returned:
+
+        >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by='X',
+        ...                      return_type=None)
+        >>> type(boxplot)
+        <class 'numpy.ndarray'>
         """
 
     def combine():
@@ -1514,7 +1651,7 @@ def ffill():
         downcast : dict, default is None
             A dict of item->dtype of what to downcast if possible, or the string ‘infer’ which will try to downcast to an appropriate equal type (e.g. float64 to int64 if possible).
 
-        Deprecated since version 2.2.0.
+        Deprecated parameter.
 
         Returns
         -------
@@ -1569,8 +1706,7 @@ def fillna():
             * ffill: propagate last valid observation forward to next valid.
             * backfill / bfill: use next valid observation to fill gap.
 
-            .. deprecated:: 2.1.0
-                Use ffill or bfill instead.
+            Deprecated: Use ffill or bfill instead.
 
         axis : {axes_single_arg}
             Axis along which to fill missing values. For `Series`
@@ -1591,7 +1727,7 @@ def fillna():
             or the string 'infer' which will try to downcast to an appropriate
             equal type (e.g. float64 to int64 if possible).
 
-            .. deprecated:: 2.2.0
+            Deprecated parameter.
 
         Returns
         -------
@@ -1758,7 +1894,7 @@ def from_records():
         data : structured ndarray, sequence of tuples or dicts, or DataFrame
             Structured input data.
 
-            Deprecated since version 2.1.0: Passing a DataFrame is deprecated.
+            Deprecated: Passing a DataFrame is deprecated.
 
         index : str, list of fields, array-like
             Field of array to use as the index, alternately a specific set of input labels to use.

src/snowflake/snowpark/modin/plugin/docstrings/groupby.py

@@ -940,7 +940,7 @@ def pct_change():
             The number of consecutive NAs to fill before stopping.
             Snowpark pandas does not yet support this parameter.
 
-            Deprecated.
+            Deprecated parameter.
 
         freq : DateOffset, timedelta, or str, optional
             Increment to use from time series API (e.g. ‘ME’ or BDay()).

src/snowflake/snowpark/modin/plugin/docstrings/index.py

@@ -1649,7 +1649,7 @@ def fillna():
             or the string 'infer' which will try to downcast to an appropriate
             equal type (e.g. float64 to int64 if possible).
 
-            .. deprecated:: 2.1.0
+            Deprecated parameter.
 
         Returns
         -------

src/snowflake/snowpark/modin/plugin/extensions/dataframe_overrides.py

@@ -167,7 +167,6 @@ def _map(self, func: PythonFuncType, na_action: str | None = None, **kwargs):
     )
 
 
-@register_dataframe_not_implemented()
 def boxplot(
     self,
     column=None,
@@ -182,7 +181,22 @@ def boxplot(
     backend=None,
     **kwargs,
 ):  # noqa: PR01, RT01, D200
-    pass  # pragma: no cover
+    WarningMessage.single_warning(
+        "DataFrame.boxplot materializes data to the local machine."
+    )
+    return self._to_pandas().boxplot(
+        column=column,
+        by=by,
+        ax=ax,
+        fontsize=fontsize,
+        rot=rot,
+        grid=grid,
+        figsize=figsize,
+        layout=layout,
+        return_type=return_type,
+        backend=backend,
+        **kwargs,
+    )
 
 
 @register_dataframe_not_implemented()

tests/integ/modin/frame/test_boxplot.py

@@ -0,0 +1,39 @@
+#
+# Copyright (c) 2012-2025 Snowflake Computing Inc. All rights reserved.
+#
+
+import modin.pandas as pd
+import matplotlib.pyplot as plt
+import pandas as native_pd
+import pytest
+
+from matplotlib.testing.compare import compare_images
+from tests.integ.utils.sql_counter import sql_count_checker
+
+
+@sql_count_checker(query_count=1)
+@pytest.mark.parametrize("grid", [True, False])
+@pytest.mark.parametrize("column", [None, "A", ["A", "B"]])
+def test_boxplot(grid, column, tmp_path):
+    data = {
+        "A": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+        "B": [2, 4, 6, 8, 10, 12, 14, 16, 18, 20],
+        "C": [1, 3, 5, 7, 9, 11, 13, 15, 17, 19],
+    }
+    native_df = native_pd.DataFrame(data)
+    snow_df = pd.DataFrame(native_df)
+
+    native_fig = plt.figure()
+    snow_fig = plt.figure()
+
+    native_fig.add_axes(
+        native_df.boxplot(ax=native_fig.gca(), grid=grid, column=column)
+    )
+    native_file_path = f"{tmp_path}/test_boxplot_native.png"
+    native_fig.savefig(native_file_path)
+
+    snow_fig.add_axes(snow_df.boxplot(ax=snow_fig.gca(), grid=grid, column=column))
+    snow_file_path = f"{tmp_path}/test_boxplot_snow.png"
+    snow_fig.savefig(snow_file_path)
+
+    assert compare_images(native_file_path, snow_file_path, 0) is None

tests/unit/modin/test_unsupported.py

@@ -71,7 +71,6 @@ def test_unsupported_general(general_method, kwargs):
         ["at_time", {"time": ""}],
         ["between_time", {"start_time": "", "end_time": ""}],
         ["bool", {}],
-        ["boxplot", {}],
         ["clip", {}],
         ["combine", {"other": "", "func": ""}],
         ["combine_first", {"other": ""}],