8000 [Doc]: Improve examples in documentation · Issue #22266 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

[Doc]: Improve examples in documentation #22266

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

Jump to bottom
Closed
Chandan-h-509 opened this issue Jan 19, 2022 · 2 comments · Fixed by #22276
Closed

[Doc]: Improve examples in documentation #22266

Chandan-h-509 opened this issue Jan 19, 2022 · 2 comments · Fixed by #22276
Labels
Documentation
Milestone
v3.6.0

Comments

@Chandan-h-509
Copy link

Documentation Link

https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.scatter.html

Problem

housing.plot(kind="scatter", x="longitude", y="latitude", alpha=0.4, s=housing["population"]/100, label="population", figsize=(10,7), c="median_house_value", cmap=plt.get_cmap("jet"), colorbar=True, )
I recently found the above code on Jupyter notebook and I referred matplotlib documentation in order to understand about the parameter s, c and alpha. But, I found it difficult to understand about these parameters, and found it unclear due to lack of explanation in the examples provided. The examples provided just has code and no explanation of the parameters.

Suggested improvement

  1. Along with making the users select the examples manually and read the code, I feel that it would also be good if there is a default example available which contains few basic parameters to give a feel of what a particular function does.
  2. I feel there should be a clear explanation of what the particular parameter does, and not just code(in the examples).
  3. It would be even better if an example is further modified by tweeking/changing the value of a particular parameter, so that the user can get an even better understanding of what the parameter does.
    For Example: in this https://matplotlib.org/stable/gallery/lines_bars_and_markers/scatter_symbol.html#sphx-glr-gallery-lines-bars-and-markers-scatter-symbol-py page, you can provide different values of alpha like (0.5,0.2,08) in order to show how the output differs.

Matplotlib Version

3.5.0
@Chandan-h-509 Chandan-h-509 changed the title [Doc]: [Doc]: Improve examples in documentation Jan 19, 2022
@jklymak
Copy link
Member
jklymak commented Jan 19, 2022

Thanks for the feedback.

First, housing.plot(kind='scatter', ...) is pandas wrapping our plotting.

Second, what is your familiarity with Matplotlib? Have you read our Basic Usage tutorial so you know some of the basic concepts? https://matplotlib.org/stable/tutorials/introductory/usage.html We can't go into gory detail in every docstring...

Third, if you have specific suggestions about what could be improved in the scatter docstring (assuming you now understand c, s, and alpha) then that would be very welcome. Looking at these in https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.scatter.html I find these relatively straightforward, so your specific suggestions would be helpful to the rest of the project.

Finally the linked example is showing one esoteric use of scatter. Suggest https://matplotlib.org/stable/gallery/shapes_and_collections/scatter.html#sphx-glr-gallery-shapes-and-collections-scatter-py. For sure, it could have a bit more discussion, particularly f what c and s do, however, I think its also relatively clear if you play with the code a little bit.

@Chandan-h-509
Copy link
Author

Thanks for clearing that @jklymak . I am a beginner and clearly I need more experience with matplotlib. I Hope to make contributions to matplotlib in the near future. Thank you.

timhoffm added a commit to timhoffm/matplotlib that referenced this issue Jan 20, 2022
@timhoffm
Merge "Scatter Symbol" and "Scatter Custom Symbol" examples
9032ed4 
Also closes matplotlib#22266 by using *sizes* instead of *s* and spelling out the
color to make their meaning clearer.
@timhoffm timhoffm mentioned this issue Jan 20, 2022
Merged
timhoffm added a commit to timhoffm/matplotlib that referenced this issue Jan 20, 2022
@timhoffm
Merge "Scatter Symbol" and "Scatter Custom Symbol" examples
1733ce1 
Also closes matplotlib#22266 by using *sizes* instead of *s* and spelling out the
color to make their meaning clearer.
timhoffm added a commit to timhoffm/matplotlib that referenced this issue Jan 20, 2022
@timhoffm
Merge "Scatter Symbol" and "Scatter Custom Symbol" examples
d345624 
Also closes matplotlib#22266 by using *sizes* instead of *s* and spelling out the
color to make their meaning clearer.
timhoffm added a commit to timhoffm/matplotlib that referenced this issue Jan 21, 2022
@timhoffm
Merge "Scatter Symbol" and "Scatter Custom Symbol" examples
cbbebe2 
Remove "Scatter plot with pie chart markers". This is only a variant of
path-as-custom-symbol, which is already covered here. Also, all pie
markers in the scatter plot have the same data distribution, so the
pie is more a style thing and cannot convey additional
datapoint-specific information.

Also closes matplotlib#22266 by using *sizes* instead of *s* and spelling out the
color to make their meaning clearer.
@QuLogic QuLogic added this to the v3.6.0 milestone Mar 18, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
v3.6.0
Development

Successfully merging a pull request may close this issue.

Merge "Scatter Symbol" and "Scatter Custom Symbol" examples timhoffm/matplotlib
3 participants
@QuLogic @jklymak @Chandan-h-509
0