Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork7.9k
DOC: add more tutorial to text/text_intro#9827
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.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Conversation
tutorials/text/text_intro.py Outdated
| * :func:`~matplotlib.pyplot.text` - add text at an arbitrary location to the ``Axes``; | ||
| :meth:`matplotlib.axes.Axes.text` in the API. | ||
| * `pyplot.text` - add text at an arbitrary location to the ``Axes``; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
single backquotes for Axes/Figure
tutorials/text/text_intro.py Outdated
| # Terminology | ||
| # ~~~~~~~~~~~ | ||
| # | ||
| # *Axes* (typically) have an `axis.xaxis` and `axis.yaxis` object that |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I think the normal convention is to call a single Axes object "ax" instead of "axis" in order to avoid confusion with Axis. So "ax.xaxis" and "ax.yaxis".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Yes, that was a typo (darn auto-correct). I changed toAxes.xaxis to actually point to the objects. I think that works.
tutorials/text/text_intro.py Outdated
| # | ||
| # The axis API is explained in detail in the `axis_api` section. | ||
| # An axis object has major and minor ticks. The axis has a *major_locator* |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
An Axis (capital) (to emphasize the difference with Axes).
tutorials/text/text_intro.py Outdated
| # Simple ticks | ||
| # ~~~~~~~~~~~~ | ||
| # | ||
| # While "discouraged", if can be very convenient to simply define the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I think we should always say why things are discouraged, rather than just handwaving it. In this case, I'd say it's because 1) they are not recomputed during interactive navigation, and 2) this prevents the data cursor (in the status bar) from working.
Edit: didn't notice it was clarified below, but I would still mention the above points.
typo below: overriding
tutorials/text/text_intro.py Outdated
| # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| # | ||
| # Instead of making a list of all the tickalbels, we could have | ||
| # used a `ticker.FormatStrFormatter` and passed it to the `axis.xaxis` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
ax.xaxis (as above, and throughout)
tutorials/text/text_intro.py Outdated
| axs[1].plot(x1, y1) | ||
| ticks = np.arange(0., 8.1, 2.) | ||
| # list comprehension to get all tick labels... | ||
| formatter = matplotlib.ticker.FormatStrFormatter('%1.1f') |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I would perhaps(?) rather push forward StrMethodFormatter (i.e. using str.format), as old-style format strings are, well, old-style.
ticker.StrMethodFormatter("{x:1.1f}")In fact I tend to just pass a bound method to FuncFormatter:
ticker.FuncFormatter("{:1.1f}".format)which covers all use cases rather than having to invoke a specific class in each case.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Ha, ok. I just suck at the new format. I’ll change!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
tbh I don't really liketicker.StrMethodFormatter("{x:1.1f}") either (IMO FuncFormatter is really the clearest) but I'm likely not be the best judge for what's best in a tutorial!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I give an example of func formatter below. Your use above is clever, but a bit obscure ;-)
tutorials/text/text_intro.py Outdated
| plt.show() | ||
| ############################################################################## Finally, we can secify functions for the formatter using |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
newline missing?
specify
tutorials/text/text_intro.py Outdated
| # `ticker.FuncFormatter`. | ||
| def formatoddticks(x, pos): | ||
| """ Format odd tick positions |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
extra space
tutorials/text/text_intro.py Outdated
| *:func:`~matplotlib.pyplot.text` - add text at an arbitrary location to the ``Axes``; | ||
| :meth:`matplotlib.axes.Axes.text` in the API. | ||
| *`pyplot.text` - add text at an arbitrary location to the `Axes`; | ||
| `Axes.text` in the API. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
@anntzer or others who understand: I am still not getting the sphinx auto-resolution. What is the proper way to make these links? Do I have to domatplotlib.Axes.text?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
~.Axes.textor
.Axes.textshould work, I think(?) (the leading dot means "search in other namespaces"; the tilde means "don't write the prefix in the rendered docshttp://www.sphinx-doc.org/en/stable/domains.html#role-py:obj).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Ok thanks a lot. Hopefully that makes it into@dstansby doc on docs.
e216346 to4144e38Compare| ================= | ||
| ======================== | ||
| Text in Matplotlib Plots | ||
| ======================== |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
remove subtitle just below, or merge with title
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
replace matplotlib by Matplotlib when in text, throughout.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
The first line shows up in a hover-over in the docs, so I think thats why the "subtitle" is there.
tutorials/text/text_intro.py Outdated
| *:func:`~matplotlib.pyplot.figtext` - add text at an arbitrary location to the ``Figure``; | ||
| :meth:`matplotlib.figure.Figure.text` in the API. | ||
| *`matplotlib.pyplot.figtext` - add text at an arbitrary location to the | ||
| Figure;`matplotlib.Figure.text` in the API. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
tutorials/text/text_intro.py Outdated
| *:func:`~matplotlib.pyplot.annotate` - add an annotation, with | ||
| optional arrow, to the ``Axes`` ;:meth:`matplotlib.axes.Axes.annotate` | ||
| *`matplotlib.pyplot.annotate` - add an annotation, with | ||
| optional arrow, to the `~matplotlib.axes.Axes` ; `matplotlib.axes.Axes.annotate` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
overindented here too
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Fixed the indents (I hope)
| @@ -31,36 +32,38 @@ | |||
| =================== | |||
| The following commands are used to create text in the pyplot | |||
| interface | |||
| interface and the object-oriented API: | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I think this would be better presented as a 3-column table (pyplot, oo, explanation).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I agree, but making a table that will fit is not trivial for someone w/ my rst skills. I think the list is OK.
| """ | ||
| import matplotlib |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
below (unicode example): replace \374 with either the proper unicode character or "\N{LATIN SMALL LETTER U WITH DIAERESIS}" which is much more self-explanatory I think (if a bit lengthy)... (see unicodedata.name).
tutorials/text/text_intro.py Outdated
| fig.subplots_adjust(bottom=0.2, left=0.2) | ||
| ax.plot(x1, np.cumsum(y1**2)) | ||
| ax.set_xlabel('time [s] \n This was a long experiment') | ||
| ax.set_ylabel('$\int\ Y^2\ dt\ \ [V^2 s]$') |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
needs to be a raw string (otherwise the backslash escapes are invalid)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
? They render fine.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals
Changed in version 3.6: Unrecognized escape sequences produce a DeprecationWarning. In some future version of Python they will be a SyntaxError.
(run with python -Wd to see the deprecation warnings)
tutorials/text/text_intro.py Outdated
| # Terminology | ||
| # ~~~~~~~~~~~ | ||
| # | ||
| # *Axes* (typically) have an `matplotlib.axis` object for the ``ax.xaxis`` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
why typically?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
3-D axes, not sure how polar axes work....
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Actually it's amatplotlib.axis.Axis object. 3D axes have xaxis/yaxis/zaxis which also inherit from Axis. Polar axes have, for the better or (mostly?) the worse, also an xaxis (theta) and a yaxis (r) attributes.
| fig, axs = plt.subplots(2, 1, figsize=(5, 3), tight_layout=True) | ||
| axs[0].plot(x1, y1) | ||
| axs[1].plot(x1, y1) | ||
| axs[1].xaxis.set_ticks(np.arange(0., 8.1, 2.)) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
The "8.1" is a bit ugh. In this specific case I'd just write [0, 2, 4, 6, 8] explicitly (or even stop at 6, which is enough for the example).
Same below.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I did 8.1 on purpose so show the bad side effect of usingset_ticks. I usesarange because thats just something I typically do to get ticks.
tutorials/text/text_intro.py Outdated
| ############################################################################# | ||
| # The default formatter is the `matplotlib.ticker.MaxNLocator` called as | ||
| # ``ticker.MaxNLocator(self, nbins='auto', steps=[1, 2, 2.5, 5, 10])`` | ||
| # The *steps* keyword is acceptable multiples that can be used for |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
"is acceptable" typo
| axs[1].xaxis.set_major_locator(locator) | ||
| axs[1].xaxis.set_major_formatter(formatter) | ||
| formatter = matplotlib.ticker.FormatStrFormatter('%1.5f') |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
%1.4f would avoid overlapping labels
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Yeah, but the overlapping labels are the point!
| # `matplotlib.ticker.FuncFormatter`. | ||
| def formatoddticks(x, pos): |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
ternaries for the win:return '%1.2f' % x if x % 2 else ''
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Lets save that for the Advanced Python Tricks guide. I want to be able to read this thing when its done ;-)
tutorials/text/text_intro.py Outdated
| # order to help, dates have spectial Locators and Formatters, | ||
| # defined in the `matplotlib.dates` module. | ||
| # | ||
| # A simple exmample is as follows. Note how we have to rotate the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
pyto
tutorials/text/text_intro.py Outdated
| ############################################################################## | ||
| # Maybe the format of the labels above is acceptable, but the choices is | ||
| # rather idiosyncratic. We can make the ticks fall on the start of the month | ||
| # by very lightly modifying `matplotlib.dates.AutoDateLocator` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
lightly? slightly?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
struck "very lightly"
tutorials/text/text_intro.py Outdated
| plt.show() | ||
| ############################################################################## | ||
| # Oddly, this changes the labels! The easiest fix is to pass a format to |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
While the behavior may be "odd" I think we should not say it as such in the official docs... (a brief explaination why (I guess locators and formatters are coupled) would be nicer)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Yeah, I'm not sure why. Seems like a bug. But for now its a good excuse to introduce the formatter...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
struck inflamatory language for:However, this changes the tick labels.
tutorials/text/text_intro.py Outdated
| # Legends and Annotations | ||
| # ======================= | ||
| # | ||
| # - Legends: :ref:`sphx_glr_tutorials_intermediate_legend_guide.py` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I tend to prefer
:doc:`/tutorials/intermediate/legend_guide`which links to the page itself rather than an html anchor, and is also shorter to type.
1e4b476 tod8a3c96CompareMilestoning against 2.2 because this requires the |
For further review:https://3926-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/tutorials/text/text_intro.html#sphx-glr-tutorials-text-text-intro-py Question: Is there a way to order the tutorials? Currently they are alphabetical, which isn't necessarily sensible. |
@anntzer I'm not too concerned w/ the order of the folders, but the order of the tutorials inside each folder. However, I take it back about them being alphabetical. I'm not sure how they are ordered: |
No idea, but if that's not in the s-g docs perhaps you should open an issue there? |
Thanks a lot@jklymak for this contribution! As for ordering tutorial, maybe open an issue, although my 2 cents is that tutorials should be rst, not sphinx-gallery based, and thus can be ordered naturally. |
Thanks@NelleV. I did look up whats happening. They are are ordered bylines of code! You can change it to alphabetical, and a few other things, but I don't see where you can set it manually. I guess we could rename the tutorial files |
Uh oh!
There was an error while loading.Please reload this page.
PR Summary
Working on the default DateLocators I noted that I couldn't really find a good place where Locators are explained.
tutorials/text/text_intro.pyseems like a good place to explain these things.PR Checklist