DOC: add units to user/explain [ci doc]

jklymak · jklymak · commit 1817f3b004fc · 2023-10-02T16:43:12.000-07:00
diff --git a/galleries/users_explain/axes/axes_units.py b/galleries/users_explain/axes/axes_units.py
@@ -23,9 +23,9 @@
 ===============
 
 If ``x`` and/or ``y`` are a list of `datetime` or an array of
-`numpy.datetime64`, Matplotlib has a built in converter that will convert the
-datetime to a float, and add locators and formatters to the axis that are
-appropriate for dates.
+`numpy.datetime64`, Matplotlib has a built-in converter that will convert the
+datetime to a float, and add tick locators and formatters to the axis that are
+appropriate for dates.  See `matplotlib.dates`.
 
 In the following example, the x-axis gains a converter that converts from
 `numpy.datetime64` to float, and a locator that put ticks at the beginning of
@@ -49,8 +49,8 @@
 # Note that if we try to plot a float on the x-axis, it will be plotted in
 # units of days since the "epoch" for the converter, in this case 1970-01-01
 # (see :ref:`date-format`).  So when we plot the value 0, the ticks start at
-# 1970-01-01, and note that the locator now chooses every two years for a tick
-# instead of every month:
+# 1970-01-01.  (The locator also now chooses every two years for a tick instead
+# of every month):
 
 fig, ax = plt.subplots(figsize=(5.4, 2), layout='constrained')
 time = np.arange('1980-01-01', '1980-06-25', dtype='datetime64[D]')
@@ -60,7 +60,6 @@
 ax.plot(0, 0, 'd')
 ax.text(0, 0, ' Float x=0', rotation=45)
 
-
 # %%
 #
 # We can customize the locator and the formatter; see :ref:`date-locators` and
@@ -80,11 +79,10 @@
 # %%
 #
 # The default locator is the `~.dates.AutoDateLocator`, and the default
-# Formatter `~.dates.AutoDateFormatter`.  There is also a "concise"
-# formatter/locator that gives a more compact labelling, and can be set via
-# rcParams.  Note how instead of the redundant "Jan" label at the start of the
-# year, "1980" is used instead.  See :ref:`date_concise_formatter` for more
-# examples.
+# Formatter `~.dates.AutoDateFormatter`.  There are also  "concise" formatter
+# and locators that give a more compact labelling, and can be set via rcParams.
+# Note how instead of the redundant "Jan" label at the start of the year,
+# "1980" is used instead.  See :ref:`date_concise_formatter` for more examples.
 
 plt.rcParams['date.converter'] = 'concise'
 
@@ -95,9 +93,10 @@
 
 # %%
 #
-# We can set the limits on the axis either by passing the appropriate dates in
-# or by passing a floating point value in the proper units of floating days
-# since the epoch.  We can get this value from `~.dates.date2num`.
+# We can set the limits on the axis either by passing the appropriate dates as
+# limits, or by passing a floating-point value in the proper units of days
+# since the epoch.  If we need it, we can get this value from
+# `~.dates.date2num`.
 
 fig, axs = plt.subplots(2, 1, figsize=(5.4, 3), layout='constrained')
 for ax in axs.flat:
@@ -135,15 +134,16 @@
 #
 # Note that the "categories" are plotted in the order that they are first
 # specified and that subsequent plotting in a different order will not affect
-# the original order.  Further, new additions will be added on the end:
+# the original order.  Further, new additions will be added on the end (see
+# "pear" below):
 
 fig, ax = plt.subplots(figsize=(5, 3), layout='constrained')
 ax.bar(names, values)
 
 # plot in a different order:
 ax.scatter(['lemon', 'apple'], [7, 12])
 
-# add a new category, and out of order:
+# add a new category, "pear", and put the other categories in a different order:
 ax.plot(['pear', 'orange', 'apple', 'lemon'], [13, 10, 7, 12], color='C1')
 
 
@@ -154,8 +154,11 @@
 # specified.
 #
 # The category converter maps from categories to integers, starting at zero. So
-# data can also be manually added to the axis using a float.  However, note
-# that a float that is not a category will not get a label.
+# data can also be manually added to the axis using a float.  Note that if a
+# float is passed in that does not have a "category" associated with it, the
+# data point can still be plotted, but a tick will not be created.  In the
+# following, we plot data at 4.0 and 2.5, but no tick is added there because
+# those are not categories.
 
 fig, ax = plt.subplots(figsize=(5, 3), layout='constrained')
 ax.bar(names, values)
@@ -220,7 +223,7 @@
 # ======================================================
 #
 # Sometimes it is helpful to be able to debug what Matplotlib is using to
-# convert the incoming data: we can do that by querying the ``converter``
+# convert the incoming data.  We can do that by querying the ``converter``
 # property on the axis.  We can also query the formatters and locators using
 # `~.axis.Axis.get_major_locator` and `~.axis.Axis.get_major_formatter`.
 #
@@ -256,11 +259,11 @@
 
 # %%
 #
-# General unit support
-# ====================
+# More about "unit" support
+# =========================
 #
-# The support for dates and categories is part of "units" support that is
-# built into Matplotlib.  This is described at `.matplotlib.units` and in the #
+# The support for dates and categories is part of "units" support that is built
+# into Matplotlib.  This is described at `.matplotlib.units` and in the
 # :ref:`basic_units` example.
 #
 # Unit support works by querying the type of data passed to the plotting
@@ -274,5 +277,6 @@
 
 # %%
 #
-# Downstream libraries like pandas, astropy, and pint all can add their own
-# converters to Matplotlib.
+# Downstream libraries like `pandas <https://pandas.pydata.org>`_,
+# `astropy <https://www.astropy.org>`, `pint <https://pint.readthedocs.io>`
+# and others supply their own converters that can be used with Matplotlib.
