Updated scatterplot docstring, also top_words docstring. Closes #100

[vidyap-xgboost]

In scatterplot, also made a change to the argument return_figure, by default it was set to False, but it still returns the figure, why? Because fig.show() was not commented out and it makes more sense to put the default as True because the function is built to return the scatterplot. Hence, setting return_figure as True.

Changed the grammar in top_words function.

For scatterplot and top_words, I followed numpy docstring guide as provided in the CONTRIBUTING.md and also an example from numpy docstring guide.

Closes #100

[henrifroese]

Hi, I actually believe this is a bad idea. With this, users would have to visualize the returned plot for themselves. I think it's much nicer if

1. return_figure=True -> no plot is shown, figure is returned
2. return_figure=False -> plot is shown, figure is not returned

This is what we implemented in #107 , please have a look and maybe consider closing this if you agree.

Thanks,
Henri

[vidyap-xgboost]

Hi, I actually believe this is a bad idea. With this, users would have to visualize the returned plot for themselves. I think it's much nicer if

1. return_figure=True -> no plot is shown, figure is returned
2. return_figure=False -> plot is shown, figure is not returned

This is what we implemented in #107 , please have a look and maybe consider closing this if you agree.

Thanks,
Henri

Hi, I fail to understand how returning 2 plots can help the user. Could you explain a bit more?

Thanks.

[henrifroese]

Yes, I'll clarify:

We have two things:

1. a return value . This is what the function returns to the user.
2. the plot/figure as side effect that the users can actually see on the screen.

If we return the plot with return fig, the plot itself is not shown. If we use fig.show(), the plot is shown. The only reason why we might want to use return fig that I can think of is that a user might want to modify the plotly plot somehow.

Consider the following example:

>>> import plotly.express as px
>>> def f():
>>>     fig = px.scatter(x=[0, 1, 2, 3, 4], y=[0, 1, 4, 9, 16])
>>>     return fig
>>> f()  # try it out, does not show the plot, it just returns the figure object
Figure({
    'data': [{'hovertemplate': 'x=%{x}<br>y=%{y}<extra></extra>',
              'legendgroup': '',
              'marker': {'color': '#636efa', 'symbol': 'circle'},
              'mode': 'markers',
              'name': '',
              'showlegend': False,
              'type': 'scatter',
              'x': array([0, 1, 2, 3, 4]),
              'xaxis': 'x',
              'y': array([ 0,  1,  4,  9, 16]),
              'yaxis': 'y'}],
    'layout': {'legend': {'tracegroupgap': 0},
               'margin': {'t': 60},
               'template': '...',
               'xaxis': {'anchor': 'y', 'domain': [0.0, 1.0], 'title': {'text': 'x'}},
               'yaxis': {'anchor': 'x', 'domain': [0.0, 1.0], 'title': {'text': 'y'}}}
})
>>> 
>>> def g():
>>>     fig = px.scatter(x=[0, 1, 2, 3, 4], y=[0, 1, 4, 9, 16])
>>>     fig.show()
>>> g()  # try it out, this shows the plot!

So fig.show() shows the plot to the user and return fig returns the figure object to the user so he could change it if he wants to (probably unlikely, so default should be to just show the plot).

[vidyap-xgboost]

@henrifroese Thank you for explaining! I understood now. Closing this pull request since you're already working on it.

[jbesomi]

@vidyap-xgboost @henrifroese @sleeper @cclauss @ParthGandhi #85 # #111 @ #107

Hey @lydz1209, what does that mean?