DOC: add more tutorial to text/text_intro #9827

jklymak · 2017-11-21T22:55:32Z

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.py seems like a good place to explain these things.

PR Checklist

Has Pytest style unit tests
Code is PEP 8 compliant
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

anntzer · 2017-11-21T23:15:40Z

tutorials/text/text_intro.py


-* :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``;


single backquotes for Axes/Figure

anntzer · 2017-11-21T23:17:09Z

tutorials/text/text_intro.py

+# Terminology
+# ~~~~~~~~~~~
+#
+# *Axes*  (typically) have an `axis.xaxis` and `axis.yaxis` object that


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".

Yes, that was a typo (darn auto-correct). I changed to Axes.xaxis to actually point to the objects. I think that works.

anntzer · 2017-11-21T23:17:42Z

tutorials/text/text_intro.py

+#
+# 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*


An Axis (capital) (to emphasize the difference with Axes).

anntzer · 2017-11-21T23:19:40Z

tutorials/text/text_intro.py

+# Simple ticks
+# ~~~~~~~~~~~~
+#
+# While "discouraged", if can be very convenient to simply define the


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

anntzer · 2017-11-21T23:21:25Z

tutorials/text/text_intro.py

+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# Instead of making a list of all the tickalbels, we could have
+# used a `ticker.FormatStrFormatter` and passed it to the `axis.xaxis`


ax.xaxis (as above, and throughout)

anntzer · 2017-11-21T23:25:43Z

tutorials/text/text_intro.py

+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')


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.

Ha, ok. I just suck at the new format. I’ll change!

tbh I don't really like ticker.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!

I give an example of func formatter below. Your use above is clever, but a bit obscure ;-)

anntzer · 2017-11-21T23:26:01Z

tutorials/text/text_intro.py

+
+plt.show()
+
+############################################################################## Finally, we can secify functions for the formatter using


newline missing?
specify

anntzer · 2017-11-21T23:26:59Z

tutorials/text/text_intro.py

+# `ticker.FuncFormatter`.
+
+def formatoddticks(x, pos):
+    """ Format odd tick positions


extra space

jklymak · 2017-11-22T02:53:27Z

tutorials/text/text_intro.py

-* :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.


@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 do matplotlib.Axes.text?

See: https://3893-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/tutorials/text/text_intro.html#sphx-glr-tutorials-text-text-intro-py

~.Axes.text

or

.Axes.text

should work, I think(?) (the leading dot means "search in other namespaces"; the tilde means "don't write the prefix in the rendered docs http://www.sphinx-doc.org/en/stable/domains.html#role-py:obj).

Ok thanks a lot. Hopefully that makes it into @dstansby doc on docs.

anntzer · 2017-11-22T05:53:35Z

tutorials/text/text_intro.py

-=================
+========================
+Text in Matplotlib Plots
+========================


remove subtitle just below, or merge with title

replace matplotlib by Matplotlib when in text, throughout.

The first line shows up in a hover-over in the docs, so I think thats why the "subtitle" is there.

anntzer · 2017-11-22T05:54:49Z

tutorials/text/text_intro.py

-* :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.


overindented by one space. see https://3904-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/tutorials/text/text_intro.html#basic-text-commands

anntzer · 2017-11-22T05:55:22Z

tutorials/text/text_intro.py

-* :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`


overindented here too

Fixed the indents (I hope)

anntzer · 2017-11-22T05:55:48Z

tutorials/text/text_intro.py

@@ -31,36 +32,38 @@
 ===================

 The following commands are used to create text in the pyplot
-interface
+interface and the object-oriented API:


I think this would be better presented as a 3-column table (pyplot, oo, explanation).

I agree, but making a table that will fit is not trivial for someone w/ my rst skills. I think the list is OK.

anntzer · 2017-11-22T06:03:18Z

tutorials/text/text_intro.py

 """

+import matplotlib


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).

anntzer · 2017-11-22T06:04:41Z

tutorials/text/text_intro.py

+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]$')


needs to be a raw string (otherwise the backslash escapes are invalid)

? They render fine.

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)

anntzer · 2017-11-22T06:05:33Z

tutorials/text/text_intro.py

+# Terminology
+# ~~~~~~~~~~~
+#
+# *Axes*  (typically) have an `matplotlib.axis` object for the ``ax.xaxis``


why typically?

3-D axes, not sure how polar axes work....

Actually it's a matplotlib.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.

anntzer · 2017-11-22T06:07:12Z

tutorials/text/text_intro.py

+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.))


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.

I did 8.1 on purpose so show the bad side effect of using set_ticks. I uses arange because thats just something I typically do to get ticks.

anntzer · 2017-11-22T06:08:22Z

tutorials/text/text_intro.py

+#############################################################################
+# 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


"is acceptable" typo

anntzer · 2017-11-22T06:09:04Z

tutorials/text/text_intro.py

+axs[1].xaxis.set_major_locator(locator)
+axs[1].xaxis.set_major_formatter(formatter)
+
+formatter = matplotlib.ticker.FormatStrFormatter('%1.5f')


%1.4f would avoid overlapping labels

Yeah, but the overlapping labels are the point!

anntzer · 2017-11-22T06:10:00Z

tutorials/text/text_intro.py

+# `matplotlib.ticker.FuncFormatter`.
+
+
+def formatoddticks(x, pos):


ternaries for the win: return '%1.2f' % x if x % 2 else ''

Lets save that for the Advanced Python Tricks guide. I want to be able to read this thing when its done ;-)

anntzer · 2017-11-22T06:10:16Z

tutorials/text/text_intro.py

+# 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


anntzer · 2017-11-22T06:10:46Z

tutorials/text/text_intro.py

+##############################################################################
+# 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`


lightly? slightly?

struck "very lightly"

anntzer · 2017-11-22T06:12:04Z

tutorials/text/text_intro.py

+plt.show()
+
+##############################################################################
+# Oddly, this changes the labels!  The easiest fix is to pass a format to


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)

Yeah, I'm not sure why. Seems like a bug. But for now its a good excuse to introduce the formatter...

struck inflamatory language for: However, this changes the tick labels.

anntzer · 2017-11-22T06:13:21Z

tutorials/text/text_intro.py

+# Legends and Annotations
+# =======================
+#
+#   - Legends: :ref:`sphx_glr_tutorials_intermediate_legend_guide.py`


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.

jklymak · 2017-11-22T20:24:34Z

Milestoning against 2.2 because this requires the pad argument in ax.title, which is on master, but not in 2.1. I could take that out if folks want to see this added sooner...

jklymak · 2017-11-22T23:02:45Z

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 · 2017-11-23T00:18:55Z

@jklymak https://github.com/matplotlib/matplotlib/blob/master/doc/conf.py#L101

jklymak · 2017-11-23T00:23:19Z

@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:

http://matplotlib.org/tutorials/index.html#introductory

anntzer · 2017-11-23T02:48:08Z

No idea, but if that's not in the s-g docs perhaps you should open an issue there?

NelleV · 2017-11-24T04:19:18Z

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.

jklymak · 2017-11-24T05:27:35Z

Thanks @NelleV. I did look up whats happening. They are are ordered by lines 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 1_this_tutorial, 2_that_tutorial if we care about the order (and we stick w/ sphinx-gallery)

anntzer reviewed Nov 21, 2017

View reviewed changes

jklymak commented Nov 22, 2017

View reviewed changes

jklymak force-pushed the doc_label_plots branch 2 times, most recently from e216346 to 4144e38 Compare November 22, 2017 05:25

anntzer reviewed Nov 22, 2017

View reviewed changes

dstansby added the Documentation label Nov 22, 2017

jklymak force-pushed the doc_label_plots branch 2 times, most recently from 1e4b476 to d8a3c96 Compare November 22, 2017 20:20

jklymak added this to the v2.2 milestone Nov 22, 2017

DOC: add more tutorial to text/text_intro

cd47ecf

jklymak force-pushed the doc_label_plots branch from 8d89584 to cd47ecf Compare November 22, 2017 22:17

jklymak changed the title ~~WIP: DOC: add more tutorial to text/text_intro~~ DOC: add more tutorial to text/text_intro Nov 22, 2017

jklymak mentioned this pull request Nov 23, 2017

ENH: make interval_multiples work for years #9841

Merged

4 tasks

NelleV merged commit 4fc36df into matplotlib:master Nov 24, 2017

QuLogic modified the milestones: needs sorting, v2.2.0 Feb 12, 2018

jklymak deleted the doc_label_plots branch March 5, 2019 16:09


		plt.show()

		############################################################################## Finally, we can secify functions for the formatter using

		# `matplotlib.ticker.FuncFormatter`.


		def formatoddticks(x, pos):

Uh oh!

DOC: add more tutorial to text/text_intro #9827

DOC: add more tutorial to text/text_intro #9827

Uh oh!

Conversation

jklymak commented Nov 21, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anntzer Nov 21, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anntzer Nov 21, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anntzer Nov 21, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anntzer Nov 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anntzer Nov 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

jklymak commented Nov 21, 2017 •

edited

Loading

anntzer Nov 21, 2017 •

edited

Loading

anntzer Nov 21, 2017 •

edited

Loading

anntzer Nov 21, 2017 •

edited

Loading

anntzer Nov 22, 2017 •

edited

Loading

anntzer Nov 22, 2017 •

edited

Loading