diff --git a/packages/python/plotly/plotly/express/_chart_types.py b/packages/python/plotly/plotly/express/_chart_types.py index 24264bf3b41..cbf2fff85cd 100644 --- a/packages/python/plotly/plotly/express/_chart_types.py +++ b/packages/python/plotly/plotly/express/_chart_types.py @@ -461,6 +461,12 @@ def box( """ In a box plot, rows of `data_frame` are grouped together into a box-and-whisker mark to visualize their distribution. + + Each box spans from quartile 1 (Q1) to quartile 3 (Q3). The + second quartile (Q2) is marked by a line inside the box. By + default, the whiskers correspond to the box' edges +/- 1.5 + times the interquartile range (IQR: Q3-Q1), see "points" for + other options. """ return make_figure( args=locals(), diff --git a/packages/python/plotly/plotly/express/_doc.py b/packages/python/plotly/plotly/express/_doc.py index 653c71b886b..e01ec87fe73 100644 --- a/packages/python/plotly/plotly/express/_doc.py +++ b/packages/python/plotly/plotly/express/_doc.py @@ -302,22 +302,22 @@ ], marginal=[ "str", - "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.", + "One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`.", "If set, a subplot is drawn alongside the main plot, visualizing the distribution.", ], marginal_x=[ "str", - "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.", + "One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`.", "If set, a horizontal subplot is drawn above the main plot, visualizing the x-distribution.", ], marginal_y=[ "str", - "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.", + "One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`.", "If set, a vertical subplot is drawn to the right of the main plot, visualizing the y-distribution.", ], trendline=[ "str", - "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.", + "One of `'ols'` or `'lowess'`.", "If `'ols'`, an Ordinary Least Squares regression line will be drawn for each discrete-color/symbol group.", "If `'lowess`', a Locally Weighted Scatterplot Smoothing line will be drawn for each discrete-color/symbol group.", ], @@ -336,7 +336,7 @@ ], direction=[ "str", - "One of '`counterclockwise'`, `'clockwise'`. Default is `'clockwise'`", + "One of '`counterclockwise'` or `'clockwise'`. Default is `'clockwise'`", "Sets the direction in which increasing values of the angular axis are drawn.", ], start_angle=[ @@ -345,7 +345,7 @@ ], histfunc=[ "str (default `'count'`)", - "One of `'count'`, `'sum'`, `'avg'`, `'min'`, `'max'`." + "One of `'count'`, `'sum'`, `'avg'`, `'min'`, or `'max'`." "Function used to aggregate values for summarization (note: can be normalized with `histnorm`).", "The arguments to this function for `histogram` are the values of `y` if `orientation` is `'v'`,", "otherwise the arguements are the values of `x`.", @@ -353,7 +353,7 @@ ], histnorm=[ "str (default `None`)", - "One of `'percent'`, `'probability'`, `'density'`, `'probability density'`", + "One of `'percent'`, `'probability'`, `'density'`, or `'probability density'`", "If `None`, the output of `histfunc` is used as is.", "If `'probability'`, the output of `histfunc` for a given bin is divided by the sum of the output of `histfunc` for all bins.", "If `'percent'`, the output of `histfunc` for a given bin is divided by the sum of the output of `histfunc` for all bins and multiplied by 100.", @@ -411,12 +411,12 @@ line_shape=["str (default `'linear'`)", "One of `'linear'` or `'spline'`."], scope=[ "str (default `'world'`).", - "One of `'world'`, `'usa'`, `'europe'`, `'asia'`, `'africa'`, `'north america'`, `'south america'`)" + "One of `'world'`, `'usa'`, `'europe'`, `'asia'`, `'africa'`, `'north america'`, or `'south america'`)" "Default is `'world'` unless `projection` is set to `'albers usa'`, which forces `'usa'`.", ], projection=[ "str ", - "One of `'equirectangular'`, `'mercator'`, `'orthographic'`, `'natural earth'`, `'kavrayskiy7'`, `'miller'`, `'robinson'`, `'eckert4'`, `'azimuthal equal area'`, `'azimuthal equidistant'`, `'conic equal area'`, `'conic conformal'`, `'conic equidistant'`, `'gnomonic'`, `'stereographic'`, `'mollweide'`, `'hammer'`, `'transverse mercator'`, `'albers usa'`, `'winkel tripel'`, `'aitoff'`, `'sinusoidal'`" + "One of `'equirectangular'`, `'mercator'`, `'orthographic'`, `'natural earth'`, `'kavrayskiy7'`, `'miller'`, `'robinson'`, `'eckert4'`, `'azimuthal equal area'`, `'azimuthal equidistant'`, `'conic equal area'`, `'conic conformal'`, `'conic equidistant'`, `'gnomonic'`, `'stereographic'`, `'mollweide'`, `'hammer'`, `'transverse mercator'`, `'albers usa'`, `'winkel tripel'`, `'aitoff'`, or `'sinusoidal'`" "Default depends on `scope`.", ], center=[ @@ -426,10 +426,12 @@ ], points=[ "str or boolean (default `'outliers'`)", - "One of `'all'`, `'outliers'`, or `False`.", + "One of `'outliers'`, `'suspectedoutliers'`, `'all'`, or `False`.", + "If `'outliers'`, only the sample points lying outside the whiskers are shown.", + "If `'suspectedoutliers'`, all outlier points are shown and those less than 4*Q1-3*Q3 or greater than 4*Q3-3*Q1 are highlighted with the marker's `'outliercolor'`.", "If `'outliers'`, only the sample points lying outside the whiskers are shown.", "If `'all'`, all sample points are shown.", - "If `False`, no sample points are shown", + "If `False`, no sample points are shown and the whiskers extend to the full range of the sample.", ], box=["boolean (default `False`)", "If `True`, boxes are drawn inside the violins."], notched=["boolean (default `False`)", "If `True`, boxes are drawn with notches."], @@ -444,7 +446,7 @@ def make_docstring(fn): - tw = TextWrapper(width=79, initial_indent=" ", subsequent_indent=" ") + tw = TextWrapper(width=77, initial_indent=" ", subsequent_indent=" ") result = (fn.__doc__ or "") + "\nParameters\n----------\n" for param in inspect.getargspec(fn)[0]: param_desc_list = docs[param][1:] diff --git a/packages/python/plotly/plotly/graph_objs/__init__.py b/packages/python/plotly/plotly/graph_objs/__init__.py index 3bf52d18179..4ccf51786bf 100644 --- a/packages/python/plotly/plotly/graph_objs/__init__.py +++ b/packages/python/plotly/plotly/graph_objs/__init__.py @@ -5533,7 +5533,8 @@ def points(self): are shown and points either less than 4*Q1-3*Q3 or greater than 4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all sample points are shown If False, only the violins are shown - with no sample points + with no sample points and the whiskers extend to the range of the + sample. The 'points' property is an enumeration that may be specified as: - One of the following enumeration values: @@ -6278,7 +6279,7 @@ def _prop_descriptions(self): or greater than 4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all sample points are shown If False, only the violins are shown with no sample - points + points and the whiskers extend to the range of the sample. scalegroup If there are multiple violins that should be sized according to to some metric (see `scalemode`), link @@ -6610,7 +6611,7 @@ def __init__( or greater than 4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all sample points are shown If False, only the violins are shown with no sample - points + points and the whiskers extend to the range of the sample. scalegroup If there are multiple violins that should be sized according to to some metric (see `scalemode`), link @@ -83296,7 +83297,8 @@ def boxpoints(self): are shown and points either less than 4*Q1-3*Q3 or greater than 4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all sample points are shown If False, only the box(es) are shown - with no sample points + with no sample points and the whiskers extend to the range of the + sample. The 'boxpoints' property is an enumeration that may be specified as: - One of the following enumeration values: @@ -84562,7 +84564,7 @@ def _prop_descriptions(self): or greater than 4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all sample points are shown If False, only the box(es) are shown with no sample - points + points and the whiskers extend to the range of the sample. customdata Assigns extra data each datum. This may be useful when listening to hover, click and selection events. Note @@ -84868,7 +84870,7 @@ def __init__( or greater than 4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all sample points are shown If False, only the box(es) are shown with no sample - points + points and the whiskers extend to the range of the sample. customdata Assigns extra data each datum. This may be useful when listening to hover, click and selection events. Note diff --git a/packages/python/plotly/plotly/graph_objs/_figure.py b/packages/python/plotly/plotly/graph_objs/_figure.py index 1b14ed03a99..70345d014d5 100644 --- a/packages/python/plotly/plotly/graph_objs/_figure.py +++ b/packages/python/plotly/plotly/graph_objs/_figure.py @@ -1613,7 +1613,7 @@ def add_box( or greater than 4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all sample points are shown If False, only the box(es) are shown with no sample - points + points and the whiskers extend to the range of the sample. customdata Assigns extra data each datum. This may be useful when listening to hover, click and selection events. Note @@ -14865,7 +14865,7 @@ def add_violin( or greater than 4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all sample points are shown If False, only the violins are shown with no sample - points + points and the whiskers extend to the range of the sample. scalegroup If there are multiple violins that should be sized according to to some metric (see `scalemode`), link diff --git a/packages/python/plotly/plotly/graph_objs/_figurewidget.py b/packages/python/plotly/plotly/graph_objs/_figurewidget.py index a793c3f178a..a796074dfc5 100644 --- a/packages/python/plotly/plotly/graph_objs/_figurewidget.py +++ b/packages/python/plotly/plotly/graph_objs/_figurewidget.py @@ -1613,7 +1613,7 @@ def add_box( or greater than 4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all sample points are shown If False, only the box(es) are shown with no sample - points + points and the whiskers extend to the range of the sample. customdata Assigns extra data each datum. This may be useful when listening to hover, click and selection events. Note @@ -14865,7 +14865,7 @@ def add_violin( or greater than 4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all sample points are shown If False, only the violins are shown with no sample - points + points and the whiskers extend to the range of the sample. scalegroup If there are multiple violins that should be sized according to to some metric (see `scalemode`), link