Improve documentation on boxplot and violinplot #27787

timhoffm · 2024-02-13T21:48:01Z

write out defaults coming from rcParams
see also-link between boxplot/bxp and violinplot/violin
some rewording

story645 · 2024-02-13T22:38:29Z

Love love the little sketch.
I'm finding 'statistical parameters' to be a bit vague, so wondering about emphasizing that the difference is computation vs drawing. Maybe hinge the distinction on 'boxplot/violinplot -> takes data as input and computes the statistical parameters", 'bxp/violin' -> draws already computed parameters, e.g.

timhoffm · 2024-02-13T23:00:41Z

I'm finding 'statistical parameters' to be a bit vague, so wondering about emphasizing that the difference is computation vs drawing. Maybe hinge the distinction on 'boxplot/violinplot -> takes data as input and computes the statistical parameters", 'bxp/violin' -> draws already computed parameters, e.g.

If you have an idea how to fit that into the one-line sentences for summary and See Also, I'm happy to take that. 'statistical parameters' was the best I could come up with.

rcomer · 2024-02-14T21:05:58Z

lib/matplotlib/axes/_axes.py

@@ -3958,6 +3958,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,

        See Also
        --------
+        .Axes.bxp : Draw a boxplot based on statistical parameters (instead of data).


Suggested change

.Axes.bxp : Draw a boxplot based on statistical parameters (instead of data).

.Axes.bxp : Draw a boxplot based on pre-computed statistics (instead of raw data).

?

Draw a boxplot based on pre-computed statistics (.i.e., the bxpstats input dictionary)

I think the instead of data confuses insteads of elucidates. But I like this wording in that the flip works too

.Axes.boxplot: Computes boxplot statistics and draws a boxplot

Thanks @rcomer. This is a good wording.

@story645, I've removed the instead-comment for this direction. While I see the appeal of "Computes boxplot statistics and draws a boxplot", I'd like to keep the "Draw ..." pattern because that's the primary objective. And I believe people think "here's my data, make a boxplot". It's implicitly understood that you have to calculate statistics, but explicitly mention that may even be distracting.

It's implicitly understood that you have to calculate statistics, but explicitly mention that may even be distracting.

I was just pulling the pattern we use for histogram https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.hist.html#matplotlib.axes.Axes.hist

also nit on raw - processed data is fine as input too (and technically the computed stats can be data)

It's because the computed stats can be data that I thought the "raw" would help but yes I appreciate that point. Pretty much none of the data I analyse would be considered raw by an instrument scientist. Can't think of a better term right now.

That was sorta why I was like put the emphasis on "boxplot-you provide the data and it computes the stats and draws, bxp-you provide the stats and it just draws"

Like normally yes the computation is expected but we have a viz method that doesn't do the computation and that's what we're trying to distinguish on.

@story645 please check whether the current wording works for you:

Summary lines:

boxplot(): Draw a box and whisker plot.

bxp(): Draw a box and whisker plot based on pre-computed statistics.

Motivation: Since it's very rare that people have pre-computed statistics, boxplot() (including computation) is the canonical behavior and we don't need to qualify the type of input. bxp() has the addition "base on pre-computed statistics" because that special and needs explicit mentioning.

See also:

boxplot() -> bxp(): Draw a boxplot based on pre-computed statistics.

bxp() -> boxplot(): Draw a boxplot based on raw data (instead of pre-computed statistics).

Motivation: The first is just the summary line of bxp() (mentioning what's special). The second has the extended explanation, because the docstring is in the context of the bxp() special case, so just an unqualified "Draw a boxplot" seems not sufficient - we have to explicitly state what's different. I know, you nitted "raw", but I haven't found a better term, and I think with the addition "raw data (instead of pre-computed statistics)" it's clear enough.

Yeah I feel bad at how many cycles it's taken, the above seems fine except I'd just go with

data instead of pre-computed statistics.

Dropping the parenthetical b/c it's the important part.

story645

Tiny word sub & pulling violin plot into same form but otherwise thanks for your patience here.

story645 · 2024-02-16T19:57:26Z

lib/matplotlib/axes/_axes.py

@@ -4086,13 +4087,26 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True,
            meanline=False, manage_ticks=True, zorder=None,
            capwidths=None):
        """
-        Drawing function for box and whisker plots.
+        Draw a box and whisker plot based on pre-computed statistics.


Suggested change

Draw a box and whisker plot based on pre-computed statistics.

Draw a box and whisker plot using pre-computed statistics.

Is "using" better English here? To me, that sounds like "pre-computed statistics" is some sort of helper, but not the fundamental input.

Honestly I think from is probably the right word- based on kinda implies indirection.

Changed to from.

lib/matplotlib/axes/_axes.py

timhoffm · 2024-02-20T08:51:19Z

Merging based on @story645's approval.

timhoffm added the Documentation: API files in lib/ and doc/api label Feb 13, 2024

timhoffm added this to the v3.9.0 milestone Feb 13, 2024

timhoffm force-pushed the boxplot-doc branch from 67b8dc4 to d04d1c4 Compare February 13, 2024 22:16

github-actions bot removed the Documentation: API files in lib/ and doc/api label Feb 13, 2024

timhoffm added the Documentation: API files in lib/ and doc/api label Feb 13, 2024

rcomer reviewed Feb 14, 2024

View reviewed changes

timhoffm force-pushed the boxplot-doc branch from d04d1c4 to c0de9ca Compare February 14, 2024 22:39

github-actions bot removed the Documentation: API files in lib/ and doc/api label Feb 14, 2024

timhoffm force-pushed the boxplot-doc branch from c0de9ca to 9fac84b Compare February 14, 2024 22:44

dstansby added the Documentation label Feb 15, 2024

timhoffm force-pushed the boxplot-doc branch from 9fac84b to 05a5cff Compare February 16, 2024 19:54

story645 approved these changes Feb 16, 2024

View reviewed changes

Improve documentation on boxplot and violinplot

3f1d8be

timhoffm force-pushed the boxplot-doc branch from 05a5cff to 3f1d8be Compare February 18, 2024 21:40

timhoffm merged commit e4e6840 into matplotlib:main Feb 20, 2024
39 of 42 checks passed

timhoffm deleted the boxplot-doc branch February 20, 2024 08:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve documentation on boxplot and violinplot #27787

Improve documentation on boxplot and violinplot #27787

timhoffm commented Feb 13, 2024

story645 commented Feb 13, 2024

timhoffm commented Feb 13, 2024

rcomer Feb 14, 2024

story645 Feb 14, 2024 •

edited

timhoffm Feb 14, 2024

story645 Feb 14, 2024

story645 Feb 14, 2024

rcomer Feb 15, 2024 •

edited

story645 Feb 15, 2024 •

edited

timhoffm Feb 16, 2024

story645 Feb 16, 2024

timhoffm Feb 16, 2024

story645 left a comment

story645 Feb 16, 2024

timhoffm Feb 16, 2024

story645 Feb 16, 2024 •

edited

timhoffm Feb 18, 2024

timhoffm commented Feb 20, 2024

	.Axes.bxp : Draw a boxplot based on statistical parameters (instead of data).
	.Axes.bxp : Draw a boxplot based on pre-computed statistics (instead of raw data).

	Draw a box and whisker plot based on pre-computed statistics.
	Draw a box and whisker plot using pre-computed statistics.

Improve documentation on boxplot and violinplot #27787

Improve documentation on boxplot and violinplot #27787

Conversation

timhoffm commented Feb 13, 2024

story645 commented Feb 13, 2024

timhoffm commented Feb 13, 2024

Choose a reason for hiding this comment

story645 Feb 14, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rcomer Feb 15, 2024 • edited

Choose a reason for hiding this comment

story645 Feb 15, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Summary lines:

See also:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

story645 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

story645 Feb 16, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timhoffm commented Feb 20, 2024

story645 Feb 14, 2024 •

edited

rcomer Feb 15, 2024 •

edited

story645 Feb 15, 2024 •

edited

story645 Feb 16, 2024 •

edited