From f8d4cb5f6ba4745aaae55d49db80b3580329f729 Mon Sep 17 00:00:00 2001 From: Kevin Christian Amparado Date: Sun, 5 Oct 2025 10:19:44 +0800 Subject: [PATCH 1/9] add inline comments to plotting.boxplot --- pandas/plotting/_core.py | 167 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 165 insertions(+), 2 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index c91903f7bd43e..c30dcb6e83ee7 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -490,8 +490,6 @@ def hist_frame( """ -@Substitution(data="data : DataFrame\n The data to visualize.\n", backend="") -@Appender(_boxplot_doc) def boxplot( data: DataFrame, column: str | list[str] | None = None, @@ -505,6 +503,171 @@ def boxplot( return_type: str | None = None, **kwargs, ): + """ + 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 `_. + + Parameters + ---------- + data : DataFrame + The data to visualize. + column : str or list of str, optional + Column name or list of names, or vector. + Can be any valid input to :meth:`pandas.DataFrame.groupby`. + by : str or array-like, optional + Column in the DataFrame to :meth:`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. + figsize : A 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. + + **kwargs + All other plotting keyword arguments to be passed to + :func:`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: + + * :class:`~pandas.Series` + * :class:`~numpy.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: + + .. plot:: + :context: close-figs + + >>> np.random.seed(1234) + >>> df = pd.DataFrame(np.random.randn(10, 4), + ... columns=['Col1', 'Col2', 'Col3', 'Col4']) + >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3']) # doctest: +SKIP + + Boxplots of variables distributions grouped by the values of a third + variable can be created using the option ``by``. For instance: + + .. plot:: + :context: close-figs + + >>> 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: + + .. plot:: + :context: close-figs + + >>> 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``: + + .. plot:: + :context: close-figs + + >>> 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``): + + .. plot:: + :context: close-figs + + >>> boxplot = df.boxplot(grid=False, rot=45, fontsize=15) # doctest: +SKIP + + 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) + + + 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) + + + 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) + + """ plot_backend = _get_plot_backend("matplotlib") return plot_backend.boxplot( data, From c79bfd2839fa9b5577558bb5470d87416fb506a7 Mon Sep 17 00:00:00 2001 From: Kevin Christian Amparado Date: Sun, 5 Oct 2025 10:26:38 +0800 Subject: [PATCH 2/9] add inline comments to plotting.boxplot_frame --- pandas/plotting/_core.py | 172 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 170 insertions(+), 2 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index c30dcb6e83ee7..d39c3fb92e19f 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -684,8 +684,6 @@ def boxplot( ) -@Substitution(data="", backend=_backend_doc) -@Appender(_boxplot_doc) def boxplot_frame( self: DataFrame, column=None, @@ -700,6 +698,176 @@ def boxplot_frame( backend=None, **kwargs, ): + """ + + 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 `_. + + Parameters + ---------- + column : str or list of str, optional + Column name or list of names, or vector. + Can be any valid input to :meth:`pandas.DataFrame.groupby`. + by : str or array-like, optional + Column in the DataFrame to :meth:`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. + figsize : A 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 + :func:`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: + + * :class:`~pandas.Series` + * :class:`~numpy.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: + + .. plot:: + :context: close-figs + + >>> np.random.seed(1234) + >>> df = pd.DataFrame(np.random.randn(10, 4), + ... columns=['Col1', 'Col2', 'Col3', 'Col4']) + >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3']) # doctest: +SKIP + + Boxplots of variables distributions grouped by the values of a third + variable can be created using the option ``by``. For instance: + + .. plot:: + :context: close-figs + + >>> 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: + + .. plot:: + :context: close-figs + + >>> 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``: + + .. plot:: + :context: close-figs + + >>> 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``): + + .. plot:: + :context: close-figs + + >>> boxplot = df.boxplot(grid=False, rot=45, fontsize=15) # doctest: +SKIP + + 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) + + + 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) + + + 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) + + """ + plot_backend = _get_plot_backend(backend) return plot_backend.boxplot_frame( self, From c12ecfb7776509245d12dad4633ea77e590003e7 Mon Sep 17 00:00:00 2001 From: Kevin Christian Amparado Date: Sun, 5 Oct 2025 10:38:40 +0800 Subject: [PATCH 3/9] remove all @Appender and @Substition and replace with inline comments on plotting.PlotAccessor --- pandas/plotting/_core.py | 456 +++++++++++++++++++++++---------------- 1 file changed, 274 insertions(+), 182 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index d39c3fb92e19f..15aa10a898358 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -8,10 +8,6 @@ from pandas._config import get_option -from pandas.util._decorators import ( - Appender, - Substitution, -) from pandas.core.dtypes.common import ( is_integer, @@ -1405,63 +1401,6 @@ def __call__(self, *args, **kwargs): __call__.__doc__ = __doc__ - @Appender( - """ - See Also - -------- - matplotlib.pyplot.plot : Plot y versus x as lines and/or markers. - - Examples - -------- - - .. plot:: - :context: close-figs - - >>> s = pd.Series([1, 3, 2]) - >>> s.plot.line() # doctest: +SKIP - - .. plot:: - :context: close-figs - - The following example shows the populations for some animals - over the years. - - >>> df = pd.DataFrame({ - ... 'pig': [20, 18, 489, 675, 1776], - ... 'horse': [4, 25, 281, 600, 1900] - ... }, index=[1990, 1997, 2003, 2009, 2014]) - >>> lines = df.plot.line() - - .. plot:: - :context: close-figs - - An example with subplots, so an array of axes is returned. - - >>> axes = df.plot.line(subplots=True) - >>> type(axes) - - - .. plot:: - :context: close-figs - - Let's repeat the same example, but specifying colors for - each column (in this case, for each animal). - - >>> axes = df.plot.line( - ... subplots=True, color={"pig": "pink", "horse": "#742802"} - ... ) - - .. plot:: - :context: close-figs - - The following example shows the relationship between both - populations. - - >>> lines = df.plot.line(x='pig', y='horse') - """ - ) - @Substitution(kind="line") - @Appender(_bar_or_line_doc) def line( self, x: Hashable | None = None, @@ -1474,89 +1413,100 @@ def line( This function is useful to plot lines using DataFrame's values as coordinates. - """ - if color is not None: - kwargs["color"] = color - return self(kind="line", x=x, y=y, **kwargs) - @Appender( - """ - See Also - -------- - DataFrame.plot.barh : Horizontal bar plot. - DataFrame.plot : Make plots of a DataFrame. - matplotlib.pyplot.bar : Make a bar plot with matplotlib. + Parameters + ---------- + x : label or position, optional + Allows plotting of one column versus another. If not specified, + the index of the DataFrame is used. + y : label or position, optional + Allows plotting of one column versus another. If not specified, + all numerical columns are used. + color : str, array-like, or dict, optional + The color for each of the DataFrame's columns. Possible values are: - Examples - -------- - Basic plot. + - A single color string referred to by name, RGB or RGBA code, + for instance 'red' or '#a98d19'. - .. plot:: - :context: close-figs + - A sequence of color strings referred to by name, RGB or RGBA + code, which will be used for each column recursively. For + instance ['green','yellow'] each column's line will be filled in + green or yellow, alternatively. If there is only a single column to + be plotted, then only the first color from the color list will be + used. - >>> df = pd.DataFrame({'lab': ['A', 'B', 'C'], 'val': [10, 30, 20]}) - >>> ax = df.plot.bar(x='lab', y='val', rot=0) + - A dict of the form {column name : color}, so that each column will be + colored accordingly. For example, if your columns are called `a` and + `b`, then passing {'a': 'green', 'b': 'red'} will color lines for + column `a` in green and lines for column `b` in red. - Plot a whole dataframe to a bar plot. Each column is assigned a - distinct color, and each row is nested in a group along the - horizontal axis. + **kwargs + Additional keyword arguments are documented in + :meth:`DataFrame.plot`. - .. plot:: - :context: close-figs + Returns + ------- + matplotlib.axes.Axes or np.ndarray of them + An ndarray is returned with one :class:`matplotlib.axes.Axes` + per column when ``subplots=True``. - >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] - >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = ['snail', 'pig', 'elephant', - ... 'rabbit', 'giraffe', 'coyote', 'horse'] - >>> df = pd.DataFrame({'speed': speed, - ... 'lifespan': lifespan}, index=index) - >>> ax = df.plot.bar(rot=0) + See Also + -------- + matplotlib.pyplot.plot : Plot y versus x as lines and/or markers. - Plot stacked bar charts for the DataFrame + Examples + -------- - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - >>> ax = df.plot.bar(stacked=True) + >>> s = pd.Series([1, 3, 2]) + >>> s.plot.line() # doctest: +SKIP - Instead of nesting, the figure can be split by column with - ``subplots=True``. In this case, a :class:`numpy.ndarray` of - :class:`matplotlib.axes.Axes` are returned. + .. plot:: + :context: close-figs - .. plot:: - :context: close-figs + The following example shows the populations for some animals + over the years. - >>> axes = df.plot.bar(rot=0, subplots=True) - >>> axes[1].legend(loc=2) # doctest: +SKIP + >>> df = pd.DataFrame({ + ... 'pig': [20, 18, 489, 675, 1776], + ... 'horse': [4, 25, 281, 600, 1900] + ... }, index=[1990, 1997, 2003, 2009, 2014]) + >>> lines = df.plot.line() - If you don't like the default colours, you can specify how you'd - like each column to be colored. + .. plot:: + :context: close-figs - .. plot:: - :context: close-figs + An example with subplots, so an array of axes is returned. - >>> axes = df.plot.bar( - ... rot=0, subplots=True, color={"speed": "red", "lifespan": "green"} - ... ) - >>> axes[1].legend(loc=2) # doctest: +SKIP + >>> axes = df.plot.line(subplots=True) + >>> type(axes) + - Plot a single column. + .. plot:: + :context: close-figs - .. plot:: - :context: close-figs + Let's repeat the same example, but specifying colors for + each column (in this case, for each animal). - >>> ax = df.plot.bar(y='speed', rot=0) + >>> axes = df.plot.line( + ... subplots=True, color={"pig": "pink", "horse": "#742802"} + ... ) - Plot only selected categories for the DataFrame. + .. plot:: + :context: close-figs - .. plot:: - :context: close-figs + The following example shows the relationship between both + populations. + + >>> lines = df.plot.line(x='pig', y='horse') + + """ + if color is not None: + kwargs["color"] = color + return self(kind="line", x=x, y=y, **kwargs) - >>> ax = df.plot.bar(x='lifespan', rot=0) - """ - ) - @Substitution(kind="bar") - @Appender(_bar_or_line_doc) def bar( self, x: Hashable | None = None, @@ -1572,85 +1522,122 @@ def bar( represent. A bar plot shows comparisons among discrete categories. One axis of the plot shows the specific categories being compared, and the other axis represents a measured value. - """ - if color is not None: - kwargs["color"] = color - return self(kind="bar", x=x, y=y, **kwargs) - @Appender( - """ - See Also - -------- - DataFrame.plot.bar : Vertical bar plot. - DataFrame.plot : Make plots of DataFrame using matplotlib. - matplotlib.axes.Axes.bar : Plot a vertical bar plot using matplotlib. + Parameters + ---------- + x : label or position, optional + Allows plotting of one column versus another. If not specified, + the index of the DataFrame is used. + y : label or position, optional + Allows plotting of one column versus another. If not specified, + all numerical columns are used. + color : str, array-like, or dict, optional + The color for each of the DataFrame's columns. Possible values are: - Examples - -------- - Basic example + - A single color string referred to by name, RGB or RGBA code, + for instance 'red' or '#a98d19'. - .. plot:: - :context: close-figs + - A sequence of color strings referred to by name, RGB or RGBA + code, which will be used for each column recursively. For + instance ['green','yellow'] each column's bar will be filled in + green or yellow, alternatively. If there is only a single column to + be plotted, then only the first color from the color list will be + used. - >>> df = pd.DataFrame({'lab': ['A', 'B', 'C'], 'val': [10, 30, 20]}) - >>> ax = df.plot.barh(x='lab', y='val') + - A dict of the form {column name : color}, so that each column will be + colored accordingly. For example, if your columns are called `a` and + `b`, then passing {'a': 'green', 'b': 'red'} will color bars for + column `a` in green and bars for column `b` in red. - Plot a whole DataFrame to a horizontal bar plot + **kwargs + Additional keyword arguments are documented in + :meth:`DataFrame.plot`. - .. plot:: - :context: close-figs + Returns + ------- + matplotlib.axes.Axes or np.ndarray of them + An ndarray is returned with one :class:`matplotlib.axes.Axes` + per column when ``subplots=True``. - >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] - >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = ['snail', 'pig', 'elephant', - ... 'rabbit', 'giraffe', 'coyote', 'horse'] - >>> df = pd.DataFrame({'speed': speed, - ... 'lifespan': lifespan}, index=index) - >>> ax = df.plot.barh() + See Also + -------- + DataFrame.plot.barh : Horizontal bar plot. + DataFrame.plot : Make plots of a DataFrame. + matplotlib.pyplot.bar : Make a bar plot with matplotlib. - Plot stacked barh charts for the DataFrame + Examples + -------- + Basic plot. - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - >>> ax = df.plot.barh(stacked=True) + >>> df = pd.DataFrame({'lab': ['A', 'B', 'C'], 'val': [10, 30, 20]}) + >>> ax = df.plot.bar(x='lab', y='val', rot=0) - We can specify colors for each column + Plot a whole dataframe to a bar plot. Each column is assigned a + distinct color, and each row is nested in a group along the + horizontal axis. - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - >>> ax = df.plot.barh(color={"speed": "red", "lifespan": "green"}) + >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] + >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] + >>> index = ['snail', 'pig', 'elephant', + ... 'rabbit', 'giraffe', 'coyote', 'horse'] + >>> df = pd.DataFrame({'speed': speed, + ... 'lifespan': lifespan}, index=index) + >>> ax = df.plot.bar(rot=0) - Plot a column of the DataFrame to a horizontal bar plot + Plot stacked bar charts for the DataFrame - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] - >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = ['snail', 'pig', 'elephant', - ... 'rabbit', 'giraffe', 'coyote', 'horse'] - >>> df = pd.DataFrame({'speed': speed, - ... 'lifespan': lifespan}, index=index) - >>> ax = df.plot.barh(y='speed') + >>> ax = df.plot.bar(stacked=True) - Plot DataFrame versus the desired column + Instead of nesting, the figure can be split by column with + ``subplots=True``. In this case, a :class:`numpy.ndarray` of + :class:`matplotlib.axes.Axes` are returned. - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs + + >>> axes = df.plot.bar(rot=0, subplots=True) + >>> axes[1].legend(loc=2) # doctest: +SKIP + + If you don't like the default colours, you can specify how you'd + like each column to be colored. + + .. plot:: + :context: close-figs + + >>> axes = df.plot.bar( + ... rot=0, subplots=True, + ... color={"speed": "red", "lifespan": "green"} + ... ) + >>> axes[1].legend(loc=2) # doctest: +SKIP + + Plot a single column. + + .. plot:: + :context: close-figs + + >>> ax = df.plot.bar(y='speed', rot=0) + + Plot only selected categories for the DataFrame. + + .. plot:: + :context: close-figs + + >>> ax = df.plot.bar(x='lifespan', rot=0) + + """ + if color is not None: + kwargs["color"] = color + return self(kind="bar", x=x, y=y, **kwargs) - >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] - >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = ['snail', 'pig', 'elephant', - ... 'rabbit', 'giraffe', 'coyote', 'horse'] - >>> df = pd.DataFrame({'speed': speed, - ... 'lifespan': lifespan}, index=index) - >>> ax = df.plot.barh(x='lifespan') - """ - ) - @Substitution(kind="bar") - @Appender(_bar_or_line_doc) def barh( self, x: Hashable | None = None, @@ -1666,6 +1653,111 @@ def barh( represent. A bar plot shows comparisons among discrete categories. One axis of the plot shows the specific categories being compared, and the other axis represents a measured value. + + Parameters + ---------- + x : label or position, optional + Allows plotting of one column versus another. If not specified, + the index of the DataFrame is used. + y : label or position, optional + Allows plotting of one column versus another. If not specified, + all numerical columns are used. + color : str, array-like, or dict, optional + The color for each of the DataFrame's columns. Possible values are: + + - A single color string referred to by name, RGB or RGBA code, + for instance 'red' or '#a98d19'. + + - A sequence of color strings referred to by name, RGB or RGBA + code, which will be used for each column recursively. For + instance ['green','yellow'] each column's bar will be filled in + green or yellow, alternatively. If there is only a single column to + be plotted, then only the first color from the color list will be + used. + + - A dict of the form {column name : color}, so that each column will be + colored accordingly. For example, if your columns are called `a` and + `b`, then passing {'a': 'green', 'b': 'red'} will color bars for + column `a` in green and bars for column `b` in red. + + **kwargs + Additional keyword arguments are documented in + :meth:`DataFrame.plot`. + + Returns + ------- + matplotlib.axes.Axes or np.ndarray of them + An ndarray is returned with one :class:`matplotlib.axes.Axes` + per column when ``subplots=True``. + + See Also + -------- + DataFrame.plot.bar : Vertical bar plot. + DataFrame.plot : Make plots of DataFrame using matplotlib. + matplotlib.axes.Axes.bar : Plot a vertical bar plot using matplotlib. + + Examples + -------- + Basic example + + .. plot:: + :context: close-figs + + >>> df = pd.DataFrame({'lab': ['A', 'B', 'C'], 'val': [10, 30, 20]}) + >>> ax = df.plot.barh(x='lab', y='val') + + Plot a whole DataFrame to a horizontal bar plot + + .. plot:: + :context: close-figs + + >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] + >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] + >>> index = ['snail', 'pig', 'elephant', + ... 'rabbit', 'giraffe', 'coyote', 'horse'] + >>> df = pd.DataFrame({'speed': speed, + ... 'lifespan': lifespan}, index=index) + >>> ax = df.plot.barh() + + Plot stacked barh charts for the DataFrame + + .. plot:: + :context: close-figs + + >>> ax = df.plot.barh(stacked=True) + + We can specify colors for each column + + .. plot:: + :context: close-figs + + >>> ax = df.plot.barh(color={"speed": "red", "lifespan": "green"}) + + Plot a column of the DataFrame to a horizontal bar plot + + .. plot:: + :context: close-figs + + >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] + >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] + >>> index = ['snail', 'pig', 'elephant', + ... 'rabbit', 'giraffe', 'coyote', 'horse'] + >>> df = pd.DataFrame({'speed': speed, + ... 'lifespan': lifespan}, index=index) + >>> ax = df.plot.barh(y='speed') + + Plot DataFrame versus the desired column + + .. plot:: + :context: close-figs + + >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] + >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] + >>> index = ['snail', 'pig', 'elephant', + ... 'rabbit', 'giraffe', 'coyote', 'horse'] + >>> df = pd.DataFrame({'speed': speed, + ... 'lifespan': lifespan}, index=index) + >>> ax = df.plot.barh(x='lifespan') """ if color is not None: kwargs["color"] = color From 2339a8777494bd470a80467076226e056d179cdf Mon Sep 17 00:00:00 2001 From: Kevin Christian Amparado Date: Sun, 5 Oct 2025 10:41:23 +0800 Subject: [PATCH 4/9] fix inline comments based on scripts/validate_docstring.py --- pandas/plotting/_core.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 15aa10a898358..5c767c686a75c 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -695,7 +695,6 @@ def boxplot_frame( **kwargs, ): """ - Make a box plot from DataFrame columns. Make a box-and-whisker plot from DataFrame columns, optionally grouped @@ -1501,7 +1500,6 @@ def line( populations. >>> lines = df.plot.line(x='pig', y='horse') - """ if color is not None: kwargs["color"] = color @@ -1632,7 +1630,6 @@ def bar( :context: close-figs >>> ax = df.plot.bar(x='lifespan', rot=0) - """ if color is not None: kwargs["color"] = color From 09a04db1ba445b8522acbdbd50765a2d44d8fabe Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 5 Oct 2025 02:48:54 +0000 Subject: [PATCH 5/9] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- pandas/plotting/_core.py | 173 ++++++++++++++++++++++----------------- 1 file changed, 97 insertions(+), 76 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 5c767c686a75c..4f3f6f31788f9 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -8,7 +8,6 @@ from pandas._config import get_option - from pandas.core.dtypes.common import ( is_integer, is_list_like, @@ -593,9 +592,10 @@ def boxplot( :context: close-figs >>> np.random.seed(1234) - >>> df = pd.DataFrame(np.random.randn(10, 4), - ... columns=['Col1', 'Col2', 'Col3', 'Col4']) - >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3']) # doctest: +SKIP + >>> df = pd.DataFrame( + ... np.random.randn(10, 4), columns=["Col1", "Col2", "Col3", "Col4"] + ... ) + >>> boxplot = df.boxplot(column=["Col1", "Col2", "Col3"]) # doctest: +SKIP Boxplots of variables distributions grouped by the values of a third variable can be created using the option ``by``. For instance: @@ -603,11 +603,9 @@ def boxplot( .. plot:: :context: close-figs - >>> 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') + >>> 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: @@ -615,21 +613,17 @@ def boxplot( .. plot:: :context: close-figs - >>> 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']) + >>> 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``: .. plot:: :context: close-figs - >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by='X', - ... layout=(2, 1)) + >>> 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``) @@ -644,23 +638,21 @@ def boxplot( 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') + >>> boxplot = df.boxplot(column=["Col1", "Col2"], return_type="axes") >>> type(boxplot) When grouping with ``by``, a Series mapping columns to ``return_type`` is returned: - >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by='X', - ... return_type='axes') + >>> boxplot = df.boxplot(column=["Col1", "Col2"], by="X", return_type="axes") >>> type(boxplot) 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) + >>> boxplot = df.boxplot(column=["Col1", "Col2"], by="X", return_type=None) >>> type(boxplot) """ @@ -791,9 +783,10 @@ def boxplot_frame( :context: close-figs >>> np.random.seed(1234) - >>> df = pd.DataFrame(np.random.randn(10, 4), - ... columns=['Col1', 'Col2', 'Col3', 'Col4']) - >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3']) # doctest: +SKIP + >>> df = pd.DataFrame( + ... np.random.randn(10, 4), columns=["Col1", "Col2", "Col3", "Col4"] + ... ) + >>> boxplot = df.boxplot(column=["Col1", "Col2", "Col3"]) # doctest: +SKIP Boxplots of variables distributions grouped by the values of a third variable can be created using the option ``by``. For instance: @@ -801,11 +794,9 @@ def boxplot_frame( .. plot:: :context: close-figs - >>> 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') + >>> 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: @@ -813,21 +804,17 @@ def boxplot_frame( .. plot:: :context: close-figs - >>> 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']) + >>> 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``: .. plot:: :context: close-figs - >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by='X', - ... layout=(2, 1)) + >>> 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``) @@ -842,23 +829,21 @@ def boxplot_frame( 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') + >>> boxplot = df.boxplot(column=["Col1", "Col2"], return_type="axes") >>> type(boxplot) When grouping with ``by``, a Series mapping columns to ``return_type`` is returned: - >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by='X', - ... return_type='axes') + >>> boxplot = df.boxplot(column=["Col1", "Col2"], by="X", return_type="axes") >>> type(boxplot) 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) + >>> boxplot = df.boxplot(column=["Col1", "Col2"], by="X", return_type=None) >>> type(boxplot) """ @@ -1468,10 +1453,13 @@ def line( The following example shows the populations for some animals over the years. - >>> df = pd.DataFrame({ - ... 'pig': [20, 18, 489, 675, 1776], - ... 'horse': [4, 25, 281, 600, 1900] - ... }, index=[1990, 1997, 2003, 2009, 2014]) + >>> df = pd.DataFrame( + ... { + ... "pig": [20, 18, 489, 675, 1776], + ... "horse": [4, 25, 281, 600, 1900], + ... }, + ... index=[1990, 1997, 2003, 2009, 2014], + ... ) >>> lines = df.plot.line() .. plot:: @@ -1499,7 +1487,7 @@ def line( The following example shows the relationship between both populations. - >>> lines = df.plot.line(x='pig', y='horse') + >>> lines = df.plot.line(x="pig", y="horse") """ if color is not None: kwargs["color"] = color @@ -1570,8 +1558,8 @@ def bar( .. plot:: :context: close-figs - >>> df = pd.DataFrame({'lab': ['A', 'B', 'C'], 'val': [10, 30, 20]}) - >>> ax = df.plot.bar(x='lab', y='val', rot=0) + >>> df = pd.DataFrame({"lab": ["A", "B", "C"], "val": [10, 30, 20]}) + >>> ax = df.plot.bar(x="lab", y="val", rot=0) Plot a whole dataframe to a bar plot. Each column is assigned a distinct color, and each row is nested in a group along the @@ -1582,10 +1570,18 @@ def bar( >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = ['snail', 'pig', 'elephant', - ... 'rabbit', 'giraffe', 'coyote', 'horse'] - >>> df = pd.DataFrame({'speed': speed, - ... 'lifespan': lifespan}, index=index) + >>> index = [ + ... "snail", + ... "pig", + ... "elephant", + ... "rabbit", + ... "giraffe", + ... "coyote", + ... "horse", + ... ] + >>> df = pd.DataFrame( + ... {"speed": speed, "lifespan": lifespan}, index=index + ... ) >>> ax = df.plot.bar(rot=0) Plot stacked bar charts for the DataFrame @@ -1612,8 +1608,9 @@ def bar( :context: close-figs >>> axes = df.plot.bar( - ... rot=0, subplots=True, - ... color={"speed": "red", "lifespan": "green"} + ... rot=0, + ... subplots=True, + ... color={"speed": "red", "lifespan": "green"}, ... ) >>> axes[1].legend(loc=2) # doctest: +SKIP @@ -1622,14 +1619,14 @@ def bar( .. plot:: :context: close-figs - >>> ax = df.plot.bar(y='speed', rot=0) + >>> ax = df.plot.bar(y="speed", rot=0) Plot only selected categories for the DataFrame. .. plot:: :context: close-figs - >>> ax = df.plot.bar(x='lifespan', rot=0) + >>> ax = df.plot.bar(x="lifespan", rot=0) """ if color is not None: kwargs["color"] = color @@ -1700,8 +1697,8 @@ def barh( .. plot:: :context: close-figs - >>> df = pd.DataFrame({'lab': ['A', 'B', 'C'], 'val': [10, 30, 20]}) - >>> ax = df.plot.barh(x='lab', y='val') + >>> df = pd.DataFrame({"lab": ["A", "B", "C"], "val": [10, 30, 20]}) + >>> ax = df.plot.barh(x="lab", y="val") Plot a whole DataFrame to a horizontal bar plot @@ -1710,10 +1707,18 @@ def barh( >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = ['snail', 'pig', 'elephant', - ... 'rabbit', 'giraffe', 'coyote', 'horse'] - >>> df = pd.DataFrame({'speed': speed, - ... 'lifespan': lifespan}, index=index) + >>> index = [ + ... "snail", + ... "pig", + ... "elephant", + ... "rabbit", + ... "giraffe", + ... "coyote", + ... "horse", + ... ] + >>> df = pd.DataFrame( + ... {"speed": speed, "lifespan": lifespan}, index=index + ... ) >>> ax = df.plot.barh() Plot stacked barh charts for the DataFrame @@ -1737,11 +1742,19 @@ def barh( >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = ['snail', 'pig', 'elephant', - ... 'rabbit', 'giraffe', 'coyote', 'horse'] - >>> df = pd.DataFrame({'speed': speed, - ... 'lifespan': lifespan}, index=index) - >>> ax = df.plot.barh(y='speed') + >>> index = [ + ... "snail", + ... "pig", + ... "elephant", + ... "rabbit", + ... "giraffe", + ... "coyote", + ... "horse", + ... ] + >>> df = pd.DataFrame( + ... {"speed": speed, "lifespan": lifespan}, index=index + ... ) + >>> ax = df.plot.barh(y="speed") Plot DataFrame versus the desired column @@ -1750,11 +1763,19 @@ def barh( >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = ['snail', 'pig', 'elephant', - ... 'rabbit', 'giraffe', 'coyote', 'horse'] - >>> df = pd.DataFrame({'speed': speed, - ... 'lifespan': lifespan}, index=index) - >>> ax = df.plot.barh(x='lifespan') + >>> index = [ + ... "snail", + ... "pig", + ... "elephant", + ... "rabbit", + ... "giraffe", + ... "coyote", + ... "horse", + ... ] + >>> df = pd.DataFrame( + ... {"speed": speed, "lifespan": lifespan}, index=index + ... ) + >>> ax = df.plot.barh(x="lifespan") """ if color is not None: kwargs["color"] = color From 75c6a86bd060bdf62cab3281530523cf6b915428 Mon Sep 17 00:00:00 2001 From: Kevin Christian Amparado Date: Sun, 5 Oct 2025 11:36:06 +0800 Subject: [PATCH 6/9] fix docstring based on doc/make.py --- pandas/plotting/_core.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 4f3f6f31788f9..3f020446381cc 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -542,10 +542,10 @@ def boxplot( * 'axes' returns the matplotlib axes the boxplot is drawn on. * 'dict' returns a dictionary whose values are the matplotlib - Lines of the boxplot. + 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. + ``return_type`` is returned. If ``return_type`` is `None`, a NumPy array of axes with the same shape as ``layout`` is returned. @@ -728,10 +728,10 @@ def boxplot_frame( * 'axes' returns the matplotlib axes the boxplot is drawn on. * 'dict' returns a dictionary whose values are the matplotlib - Lines of the boxplot. + 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. + ``return_type`` is returned. If ``return_type`` is `None`, a NumPy array of axes with the same shape as ``layout`` is returned. From d8d14dc5f2671a529f1de8227c07957268e0bf3f Mon Sep 17 00:00:00 2001 From: Kevin Christian Amparado Date: Sun, 5 Oct 2025 18:52:15 +0800 Subject: [PATCH 7/9] fix docstring of line and bar and barh based on docs/make.py --- pandas/plotting/_core.py | 76 ++++++++++++++++++++-------------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 3f020446381cc..34352f3227281 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -1410,19 +1410,19 @@ def line( The color for each of the DataFrame's columns. Possible values are: - A single color string referred to by name, RGB or RGBA code, - for instance 'red' or '#a98d19'. + for instance 'red' or '#a98d19'. - A sequence of color strings referred to by name, RGB or RGBA - code, which will be used for each column recursively. For - instance ['green','yellow'] each column's line will be filled in - green or yellow, alternatively. If there is only a single column to - be plotted, then only the first color from the color list will be - used. + code, which will be used for each column recursively. For + instance ['green','yellow'] each column's line will be filled in + green or yellow, alternatively. If there is only a single column to + be plotted, then only the first color from the color list will be + used. - A dict of the form {column name : color}, so that each column will be - colored accordingly. For example, if your columns are called `a` and - `b`, then passing {'a': 'green', 'b': 'red'} will color lines for - column `a` in green and lines for column `b` in red. + colored accordingly. For example, if your columns are called `a` and + `b`, then passing {'a': 'green', 'b': 'red'} will color lines for + column `a` in green and lines for column `b` in red. **kwargs Additional keyword arguments are documented in @@ -1463,23 +1463,23 @@ def line( >>> lines = df.plot.line() .. plot:: - :context: close-figs + :context: close-figs - An example with subplots, so an array of axes is returned. + An example with subplots, so an array of axes is returned. - >>> axes = df.plot.line(subplots=True) - >>> type(axes) - + >>> axes = df.plot.line(subplots=True) + >>> type(axes) + .. plot:: - :context: close-figs + :context: close-figs - Let's repeat the same example, but specifying colors for - each column (in this case, for each animal). + Let's repeat the same example, but specifying colors for + each column (in this case, for each animal). - >>> axes = df.plot.line( - ... subplots=True, color={"pig": "pink", "horse": "#742802"} - ... ) + >>> axes = df.plot.line( + ... subplots=True, color={"pig": "pink", "horse": "#742802"} + ... ) .. plot:: :context: close-figs @@ -1521,19 +1521,19 @@ def bar( The color for each of the DataFrame's columns. Possible values are: - A single color string referred to by name, RGB or RGBA code, - for instance 'red' or '#a98d19'. + for instance 'red' or '#a98d19'. - A sequence of color strings referred to by name, RGB or RGBA - code, which will be used for each column recursively. For - instance ['green','yellow'] each column's bar will be filled in - green or yellow, alternatively. If there is only a single column to - be plotted, then only the first color from the color list will be - used. + code, which will be used for each column recursively. For + instance ['green','yellow'] each column's bar will be filled in + green or yellow, alternatively. If there is only a single column to + be plotted, then only the first color from the color list will be + used. - A dict of the form {column name : color}, so that each column will be - colored accordingly. For example, if your columns are called `a` and - `b`, then passing {'a': 'green', 'b': 'red'} will color bars for - column `a` in green and bars for column `b` in red. + colored accordingly. For example, if your columns are called `a` and + `b`, then passing {'a': 'green', 'b': 'red'} will color bars for + column `a` in green and bars for column `b` in red. **kwargs Additional keyword arguments are documented in @@ -1660,19 +1660,19 @@ def barh( The color for each of the DataFrame's columns. Possible values are: - A single color string referred to by name, RGB or RGBA code, - for instance 'red' or '#a98d19'. + for instance 'red' or '#a98d19'. - A sequence of color strings referred to by name, RGB or RGBA - code, which will be used for each column recursively. For - instance ['green','yellow'] each column's bar will be filled in - green or yellow, alternatively. If there is only a single column to - be plotted, then only the first color from the color list will be - used. + code, which will be used for each column recursively. For + instance ['green','yellow'] each column's bar will be filled in + green or yellow, alternatively. If there is only a single column to + be plotted, then only the first color from the color list will be + used. - A dict of the form {column name : color}, so that each column will be - colored accordingly. For example, if your columns are called `a` and - `b`, then passing {'a': 'green', 'b': 'red'} will color bars for - column `a` in green and bars for column `b` in red. + colored accordingly. For example, if your columns are called `a` and + `b`, then passing {'a': 'green', 'b': 'red'} will color bars for + column `a` in green and bars for column `b` in red. **kwargs Additional keyword arguments are documented in From b5ba3a317e77158db07a4a3d0df9855fa4f55951 Mon Sep 17 00:00:00 2001 From: Kevin Christian Amparado Date: Mon, 6 Oct 2025 19:47:00 +0800 Subject: [PATCH 8/9] remove unused docstring vars that was previously used for @Appender and @Substition --- pandas/plotting/_core.py | 214 --------------------------------------- 1 file changed, 214 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 34352f3227281..19a79ddb556aa 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -271,220 +271,6 @@ def hist_frame( ) -_boxplot_doc = """ -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 `_. - -Parameters ----------- -%(data)s\ -column : str or list of str, optional - Column name or list of names, or vector. - Can be any valid input to :meth:`pandas.DataFrame.groupby`. -by : str or array-like, optional - Column in the DataFrame to :meth:`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. -figsize : A 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)s\ - -**kwargs - All other plotting keyword arguments to be passed to - :func:`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: - -* :class:`~pandas.Series` -* :class:`~numpy.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: - -.. plot:: - :context: close-figs - - >>> np.random.seed(1234) - >>> df = pd.DataFrame(np.random.randn(10, 4), - ... columns=['Col1', 'Col2', 'Col3', 'Col4']) - >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3']) # doctest: +SKIP - -Boxplots of variables distributions grouped by the values of a third -variable can be created using the option ``by``. For instance: - -.. plot:: - :context: close-figs - - >>> 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: - -.. plot:: - :context: close-figs - - >>> 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``: - -.. plot:: - :context: close-figs - - >>> 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``): - -.. plot:: - :context: close-figs - - >>> boxplot = df.boxplot(grid=False, rot=45, fontsize=15) # doctest: +SKIP - -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) - - -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) - - -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) - -""" - -_backend_doc = """\ -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``. -""" - - -_bar_or_line_doc = """ - Parameters - ---------- - x : label or position, optional - Allows plotting of one column versus another. If not specified, - the index of the DataFrame is used. - y : label or position, optional - Allows plotting of one column versus another. If not specified, - all numerical columns are used. - color : str, array-like, or dict, optional - The color for each of the DataFrame's columns. Possible values are: - - - A single color string referred to by name, RGB or RGBA code, - for instance 'red' or '#a98d19'. - - - A sequence of color strings referred to by name, RGB or RGBA - code, which will be used for each column recursively. For - instance ['green','yellow'] each column's %(kind)s will be filled in - green or yellow, alternatively. If there is only a single column to - be plotted, then only the first color from the color list will be - used. - - - A dict of the form {column name : color}, so that each column will be - colored accordingly. For example, if your columns are called `a` and - `b`, then passing {'a': 'green', 'b': 'red'} will color %(kind)ss for - column `a` in green and %(kind)ss for column `b` in red. - - **kwargs - Additional keyword arguments are documented in - :meth:`DataFrame.plot`. - - Returns - ------- - matplotlib.axes.Axes or np.ndarray of them - An ndarray is returned with one :class:`matplotlib.axes.Axes` - per column when ``subplots=True``. -""" - - def boxplot( data: DataFrame, column: str | list[str] | None = None, From fba1351bcab5f8a0817291e5d02857972afd68cd Mon Sep 17 00:00:00 2001 From: Kevin Christian Amparado Date: Mon, 6 Oct 2025 19:50:16 +0800 Subject: [PATCH 9/9] fix indentation on docstrings of PlotAccessor: line, barh, bar after "See Also" --- pandas/plotting/_core.py | 378 +++++++++++++++++++-------------------- 1 file changed, 185 insertions(+), 193 deletions(-) diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 19a79ddb556aa..b46af93c447d4 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -1220,60 +1220,60 @@ def line( An ndarray is returned with one :class:`matplotlib.axes.Axes` per column when ``subplots=True``. - See Also - -------- - matplotlib.pyplot.plot : Plot y versus x as lines and/or markers. + See Also + -------- + matplotlib.pyplot.plot : Plot y versus x as lines and/or markers. - Examples - -------- + Examples + -------- - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - >>> s = pd.Series([1, 3, 2]) - >>> s.plot.line() # doctest: +SKIP + >>> s = pd.Series([1, 3, 2]) + >>> s.plot.line() # doctest: +SKIP - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - The following example shows the populations for some animals - over the years. + The following example shows the populations for some animals + over the years. - >>> df = pd.DataFrame( - ... { - ... "pig": [20, 18, 489, 675, 1776], - ... "horse": [4, 25, 281, 600, 1900], - ... }, - ... index=[1990, 1997, 2003, 2009, 2014], - ... ) - >>> lines = df.plot.line() + >>> df = pd.DataFrame( + ... { + ... "pig": [20, 18, 489, 675, 1776], + ... "horse": [4, 25, 281, 600, 1900], + ... }, + ... index=[1990, 1997, 2003, 2009, 2014], + ... ) + >>> lines = df.plot.line() - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - An example with subplots, so an array of axes is returned. + An example with subplots, so an array of axes is returned. - >>> axes = df.plot.line(subplots=True) - >>> type(axes) - + >>> axes = df.plot.line(subplots=True) + >>> type(axes) + - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - Let's repeat the same example, but specifying colors for - each column (in this case, for each animal). + Let's repeat the same example, but specifying colors for + each column (in this case, for each animal). - >>> axes = df.plot.line( - ... subplots=True, color={"pig": "pink", "horse": "#742802"} - ... ) + >>> axes = df.plot.line( + ... subplots=True, color={"pig": "pink", "horse": "#742802"} + ... ) - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - The following example shows the relationship between both - populations. + The following example shows the relationship between both + populations. - >>> lines = df.plot.line(x="pig", y="horse") + >>> lines = df.plot.line(x="pig", y="horse") """ if color is not None: kwargs["color"] = color @@ -1331,88 +1331,86 @@ def bar( An ndarray is returned with one :class:`matplotlib.axes.Axes` per column when ``subplots=True``. - See Also - -------- - DataFrame.plot.barh : Horizontal bar plot. - DataFrame.plot : Make plots of a DataFrame. - matplotlib.pyplot.bar : Make a bar plot with matplotlib. - - Examples - -------- - Basic plot. + See Also + -------- + DataFrame.plot.barh : Horizontal bar plot. + DataFrame.plot : Make plots of a DataFrame. + matplotlib.pyplot.bar : Make a bar plot with matplotlib. - .. plot:: - :context: close-figs + Examples + -------- + Basic plot. - >>> df = pd.DataFrame({"lab": ["A", "B", "C"], "val": [10, 30, 20]}) - >>> ax = df.plot.bar(x="lab", y="val", rot=0) + .. plot:: + :context: close-figs - Plot a whole dataframe to a bar plot. Each column is assigned a - distinct color, and each row is nested in a group along the - horizontal axis. + >>> df = pd.DataFrame({"lab": ["A", "B", "C"], "val": [10, 30, 20]}) + >>> ax = df.plot.bar(x="lab", y="val", rot=0) - .. plot:: - :context: close-figs + Plot a whole dataframe to a bar plot. Each column is assigned a + distinct color, and each row is nested in a group along the + horizontal axis. - >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] - >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = [ - ... "snail", - ... "pig", - ... "elephant", - ... "rabbit", - ... "giraffe", - ... "coyote", - ... "horse", - ... ] - >>> df = pd.DataFrame( - ... {"speed": speed, "lifespan": lifespan}, index=index - ... ) - >>> ax = df.plot.bar(rot=0) + .. plot:: + :context: close-figs - Plot stacked bar charts for the DataFrame + >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] + >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] + >>> index = [ + ... "snail", + ... "pig", + ... "elephant", + ... "rabbit", + ... "giraffe", + ... "coyote", + ... "horse", + ... ] + >>> df = pd.DataFrame({"speed": speed, "lifespan": lifespan}, index=index) + >>> ax = df.plot.bar(rot=0) + + Plot stacked bar charts for the DataFrame - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - >>> ax = df.plot.bar(stacked=True) + >>> ax = df.plot.bar(stacked=True) - Instead of nesting, the figure can be split by column with - ``subplots=True``. In this case, a :class:`numpy.ndarray` of - :class:`matplotlib.axes.Axes` are returned. + Instead of nesting, the figure can be split by column with + ``subplots=True``. In this case, a :class:`numpy.ndarray` of + :class:`matplotlib.axes.Axes` are returned. - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - >>> axes = df.plot.bar(rot=0, subplots=True) - >>> axes[1].legend(loc=2) # doctest: +SKIP + >>> axes = df.plot.bar(rot=0, subplots=True) + >>> axes[1].legend(loc=2) # doctest: +SKIP - If you don't like the default colours, you can specify how you'd - like each column to be colored. + If you don't like the default colours, you can specify how you'd + like each column to be colored. - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - >>> axes = df.plot.bar( - ... rot=0, - ... subplots=True, - ... color={"speed": "red", "lifespan": "green"}, - ... ) - >>> axes[1].legend(loc=2) # doctest: +SKIP + >>> axes = df.plot.bar( + ... rot=0, + ... subplots=True, + ... color={"speed": "red", "lifespan": "green"}, + ... ) + >>> axes[1].legend(loc=2) # doctest: +SKIP - Plot a single column. + Plot a single column. - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - >>> ax = df.plot.bar(y="speed", rot=0) + >>> ax = df.plot.bar(y="speed", rot=0) - Plot only selected categories for the DataFrame. + Plot only selected categories for the DataFrame. - .. plot:: - :context: close-figs + .. plot:: + :context: close-figs - >>> ax = df.plot.bar(x="lifespan", rot=0) + >>> ax = df.plot.bar(x="lifespan", rot=0) """ if color is not None: kwargs["color"] = color @@ -1470,98 +1468,92 @@ def barh( An ndarray is returned with one :class:`matplotlib.axes.Axes` per column when ``subplots=True``. - See Also - -------- - DataFrame.plot.bar : Vertical bar plot. - DataFrame.plot : Make plots of DataFrame using matplotlib. - matplotlib.axes.Axes.bar : Plot a vertical bar plot using matplotlib. - - Examples - -------- - Basic example - - .. plot:: - :context: close-figs - - >>> df = pd.DataFrame({"lab": ["A", "B", "C"], "val": [10, 30, 20]}) - >>> ax = df.plot.barh(x="lab", y="val") - - Plot a whole DataFrame to a horizontal bar plot - - .. plot:: - :context: close-figs - - >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] - >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = [ - ... "snail", - ... "pig", - ... "elephant", - ... "rabbit", - ... "giraffe", - ... "coyote", - ... "horse", - ... ] - >>> df = pd.DataFrame( - ... {"speed": speed, "lifespan": lifespan}, index=index - ... ) - >>> ax = df.plot.barh() - - Plot stacked barh charts for the DataFrame - - .. plot:: - :context: close-figs - - >>> ax = df.plot.barh(stacked=True) - - We can specify colors for each column - - .. plot:: - :context: close-figs - - >>> ax = df.plot.barh(color={"speed": "red", "lifespan": "green"}) - - Plot a column of the DataFrame to a horizontal bar plot - - .. plot:: - :context: close-figs - - >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] - >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = [ - ... "snail", - ... "pig", - ... "elephant", - ... "rabbit", - ... "giraffe", - ... "coyote", - ... "horse", - ... ] - >>> df = pd.DataFrame( - ... {"speed": speed, "lifespan": lifespan}, index=index - ... ) - >>> ax = df.plot.barh(y="speed") - - Plot DataFrame versus the desired column - - .. plot:: - :context: close-figs - - >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] - >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] - >>> index = [ - ... "snail", - ... "pig", - ... "elephant", - ... "rabbit", - ... "giraffe", - ... "coyote", - ... "horse", - ... ] - >>> df = pd.DataFrame( - ... {"speed": speed, "lifespan": lifespan}, index=index - ... ) - >>> ax = df.plot.barh(x="lifespan") + See Also + -------- + DataFrame.plot.bar : Vertical bar plot. + DataFrame.plot : Make plots of DataFrame using matplotlib. + matplotlib.axes.Axes.bar : Plot a vertical bar plot using matplotlib. + + Examples + -------- + Basic example + + .. plot:: + :context: close-figs + + >>> df = pd.DataFrame({"lab": ["A", "B", "C"], "val": [10, 30, 20]}) + >>> ax = df.plot.barh(x="lab", y="val") + + Plot a whole DataFrame to a horizontal bar plot + + .. plot:: + :context: close-figs + + >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] + >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] + >>> index = [ + ... "snail", + ... "pig", + ... "elephant", + ... "rabbit", + ... "giraffe", + ... "coyote", + ... "horse", + ... ] + >>> df = pd.DataFrame({"speed": speed, "lifespan": lifespan}, index=index) + >>> ax = df.plot.barh() + + Plot stacked barh charts for the DataFrame + + .. plot:: + :context: close-figs + + >>> ax = df.plot.barh(stacked=True) + + We can specify colors for each column + + .. plot:: + :context: close-figs + + >>> ax = df.plot.barh(color={"speed": "red", "lifespan": "green"}) + + Plot a column of the DataFrame to a horizontal bar plot + + .. plot:: + :context: close-figs + + >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] + >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] + >>> index = [ + ... "snail", + ... "pig", + ... "elephant", + ... "rabbit", + ... "giraffe", + ... "coyote", + ... "horse", + ... ] + >>> df = pd.DataFrame({"speed": speed, "lifespan": lifespan}, index=index) + >>> ax = df.plot.barh(y="speed") + + Plot DataFrame versus the desired column + + .. plot:: + :context: close-figs + + >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88] + >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28] + >>> index = [ + ... "snail", + ... "pig", + ... "elephant", + ... "rabbit", + ... "giraffe", + ... "coyote", + ... "horse", + ... ] + >>> df = pd.DataFrame({"speed": speed, "lifespan": lifespan}, index=index) + >>> ax = df.plot.barh(x="lifespan") """ if color is not None: kwargs["color"] = color