Skip to content

Docstring touchups #1866

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Nov 4, 2019
Merged

Docstring touchups #1866

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
8a6469a
Reduce line width to prevent wrapping in Jupyter Notebook help dialog
joelostblom Nov 4, 2019
037955b
Correct trendline docstring
joelostblom Nov 4, 2019
5c9cf5f
Unify language in "one of" docstrings
joelostblom Nov 4, 2019
12fe5a5
Mention "suspectedoutliers" as a legal argument to the points parameter
joelostblom Nov 4, 2019
b2bff06
Document extension of whiskers when no sample points are plotted
joelostblom Nov 4, 2019
09c255e
Document box and whisker ranges
joelostblom Nov 4, 2019
3b5db1b
Mention whisker extension at one more place
joelostblom Nov 4, 2019
a15a381
Add newline in boxplot description
joelostblom Nov 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions packages/python/plotly/plotly/express/_chart_types.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could you please add a blank line before this sentence? The convention is to have a 1-line sentence to start the docstring, then if needed explanations in another paragraph.

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(),
Expand Down
26 changes: 14 additions & 12 deletions packages/python/plotly/plotly/express/_doc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'`.",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oops good catch!

"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.",
],
Expand All @@ -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=[
Expand All @@ -345,15 +345,15 @@
],
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`.",
"The arguments to this function for `density_heatmap` and `density_contour` are the values of `z`.",
],
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.",
Expand Down Expand Up @@ -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=[
Expand All @@ -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."],
Expand All @@ -444,7 +446,7 @@


def make_docstring(fn):
tw = TextWrapper(width=79, initial_indent=" ", subsequent_indent=" ")
tw = TextWrapper(width=77, initial_indent=" ", subsequent_indent=" ")
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure I understand this change...

Copy link
Contributor Author

@joelostblom joelostblom Nov 4, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's to prevent spillover in the help message that pops up when clicking shift + tab in Jupyter notebooks. I thought the width for that was 79 when I reformatted the docstrings previously, but noticed today that it actually is 77.

Before:
image

After:
image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK thank you for the explanation! It's weird however because I don't have the problem
image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which version of jupyter are you using? Mine is

$ jupyter --version
jupyter core     : 4.5.0
jupyter-notebook : 6.0.1
qtconsole        : 4.5.5
ipython          : 7.8.0
ipykernel        : 5.1.2
jupyter client   : 5.3.1
jupyter lab      : 1.1.4
nbconvert        : 5.6.0
ipywidgets       : 7.5.1
nbformat         : 4.4.0
traitlets        : 4.3.2

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I'm using a dark theme for jupyter which might tune the configuration. I also tested on binder and there is even more spillover I think, it looks like it does not use wrapping at all?
image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This issue seems more complicated than I orginally thought, would you mind reverting here to 79 and opening an issue so that we can take the time to understand what's going on, and merge the rest of this PR?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is the custom dark theme that changes the width of the help box in the first screen shot (it looks like you have even more room on the right). I tried the default Jupyter Light and Dark theme and they both perform the wrapping as I indicated above:

image

On your binder screenshot, it appears as if you are running without PR #1835. I'm on jupyter 4.4.0 and jupyterlab 1.0.5.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you prefer if I make a new commit that to revert the change, or can I drop the old one in a rebase and then force push?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot for helping to document this. OK, so no need to revert the change, I'll merge as it is.

result = (fn.__doc__ or "") + "\nParameters\n----------\n"
for param in inspect.getargspec(fn)[0]:
param_desc_list = docs[param][1:]
Expand Down
14 changes: 8 additions & 6 deletions packages/python/plotly/plotly/graph_objs/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions packages/python/plotly/plotly/graph_objs/_figure.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions packages/python/plotly/plotly/graph_objs/_figurewidget.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down