From 8a6469a2325124f86da7d8d7f2479fd7e7a8a507 Mon Sep 17 00:00:00 2001 From: joelostblom Date: Mon, 4 Nov 2019 05:06:31 +0100 Subject: [PATCH 1/8] Reduce line width to prevent wrapping in Jupyter Notebook help dialog --- packages/python/plotly/plotly/express/_doc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/python/plotly/plotly/express/_doc.py b/packages/python/plotly/plotly/express/_doc.py index 653c71b886b..7b1b824f1cf 100644 --- a/packages/python/plotly/plotly/express/_doc.py +++ b/packages/python/plotly/plotly/express/_doc.py @@ -444,7 +444,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:] From 037955bc45115fb485c1a1ec9f4abbc9c9c167bd Mon Sep 17 00:00:00 2001 From: joelostblom Date: Mon, 4 Nov 2019 05:11:54 +0100 Subject: [PATCH 2/8] Correct trendline docstring --- packages/python/plotly/plotly/express/_doc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/python/plotly/plotly/express/_doc.py b/packages/python/plotly/plotly/express/_doc.py index 7b1b824f1cf..fda10b30603 100644 --- a/packages/python/plotly/plotly/express/_doc.py +++ b/packages/python/plotly/plotly/express/_doc.py @@ -317,7 +317,7 @@ ], 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.", ], From 5c9cf5f51ffca696b2bbc4e93a9a35552be4f8d6 Mon Sep 17 00:00:00 2001 From: joelostblom Date: Mon, 4 Nov 2019 05:12:18 +0100 Subject: [PATCH 3/8] Unify language in "one of" docstrings --- packages/python/plotly/plotly/express/_doc.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/python/plotly/plotly/express/_doc.py b/packages/python/plotly/plotly/express/_doc.py index fda10b30603..090defd7c21 100644 --- a/packages/python/plotly/plotly/express/_doc.py +++ b/packages/python/plotly/plotly/express/_doc.py @@ -302,17 +302,17 @@ ], 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=[ @@ -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=[ From 12fe5a50b42e8e7e67ea6efdea7e68d89f65f25f Mon Sep 17 00:00:00 2001 From: joelostblom Date: Mon, 4 Nov 2019 11:00:20 +0100 Subject: [PATCH 4/8] Mention "suspectedoutliers" as a legal argument to the points parameter This already shows up in the error message when passing "points" an illegal argument --- packages/python/plotly/plotly/express/_doc.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/python/plotly/plotly/express/_doc.py b/packages/python/plotly/plotly/express/_doc.py index 090defd7c21..63111301eb3 100644 --- a/packages/python/plotly/plotly/express/_doc.py +++ b/packages/python/plotly/plotly/express/_doc.py @@ -426,7 +426,9 @@ ], 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", From b2bff06827338edc7973a1fe141123f2457f2efe Mon Sep 17 00:00:00 2001 From: joelostblom Date: Mon, 4 Nov 2019 11:17:52 +0100 Subject: [PATCH 5/8] Document extension of whiskers when no sample points are plotted The docstring already mentions that the points parameter can be used to control the whisker length, but it does not document how which lead to #522 --- packages/python/plotly/plotly/express/_doc.py | 2 +- packages/python/plotly/plotly/graph_objs/__init__.py | 11 ++++++----- packages/python/plotly/plotly/graph_objs/_figure.py | 4 ++-- .../python/plotly/plotly/graph_objs/_figurewidget.py | 4 ++-- 4 files changed, 11 insertions(+), 10 deletions(-) diff --git a/packages/python/plotly/plotly/express/_doc.py b/packages/python/plotly/plotly/express/_doc.py index 63111301eb3..e01ec87fe73 100644 --- a/packages/python/plotly/plotly/express/_doc.py +++ b/packages/python/plotly/plotly/express/_doc.py @@ -431,7 +431,7 @@ "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."], diff --git a/packages/python/plotly/plotly/graph_objs/__init__.py b/packages/python/plotly/plotly/graph_objs/__init__.py index 3bf52d18179..ccb4c60fadc 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 @@ -84562,7 +84563,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 +84869,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 From 09c255ebe9764818080bb6169c4034dcf0e71ef6 Mon Sep 17 00:00:00 2001 From: joelostblom Date: Mon, 4 Nov 2019 11:24:31 +0100 Subject: [PATCH 6/8] Document box and whisker ranges --- packages/python/plotly/plotly/express/_chart_types.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/python/plotly/plotly/express/_chart_types.py b/packages/python/plotly/plotly/express/_chart_types.py index 24264bf3b41..5cbca4d3329 100644 --- a/packages/python/plotly/plotly/express/_chart_types.py +++ b/packages/python/plotly/plotly/express/_chart_types.py @@ -461,6 +461,11 @@ 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(), From 3b5db1bbc2c7bcdcfc4b05e5091787c0ba07979c Mon Sep 17 00:00:00 2001 From: joelostblom Date: Mon, 4 Nov 2019 11:56:09 +0100 Subject: [PATCH 7/8] Mention whisker extension at one more place --- packages/python/plotly/plotly/graph_objs/__init__.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/python/plotly/plotly/graph_objs/__init__.py b/packages/python/plotly/plotly/graph_objs/__init__.py index ccb4c60fadc..4ccf51786bf 100644 --- a/packages/python/plotly/plotly/graph_objs/__init__.py +++ b/packages/python/plotly/plotly/graph_objs/__init__.py @@ -83297,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: From a15a3819299d86fd8931c6334c81a50312ec4803 Mon Sep 17 00:00:00 2001 From: joelostblom Date: Mon, 4 Nov 2019 15:22:04 +0100 Subject: [PATCH 8/8] Add newline in boxplot description --- packages/python/plotly/plotly/express/_chart_types.py | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/python/plotly/plotly/express/_chart_types.py b/packages/python/plotly/plotly/express/_chart_types.py index 5cbca4d3329..cbf2fff85cd 100644 --- a/packages/python/plotly/plotly/express/_chart_types.py +++ b/packages/python/plotly/plotly/express/_chart_types.py @@ -461,6 +461,7 @@ 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