1Plotting Astropy objects in Matplotlib
2**************************************
3
4.. _plotting-quantities:
5
6Plotting quantities
7===================
8
9|Quantity| objects can be conveniently plotted using matplotlib.  This
10feature needs to be explicitly turned on:
11
12.. doctest-requires:: matplotlib
13
14    >>> from astropy.visualization import quantity_support
15    >>> quantity_support()  # doctest: +IGNORE_OUTPUT
16    <astropy.visualization.units.MplQuantityConverter ...>
17
18Then |Quantity| objects can be passed to matplotlib plotting
19functions.  The axis labels are automatically labeled with the unit of
20the quantity:
21
22.. plot::
23   :include-source:
24   :context: reset
25
26    from astropy import units as u
27    from astropy.visualization import quantity_support
28    quantity_support()
29    from matplotlib import pyplot as plt
30    plt.figure(figsize=(5,3))
31    plt.plot([1, 2, 3] * u.m)
32
33Quantities are automatically converted to the first unit set on a
34particular axis, so in the following, the y-axis remains in ``m`` even
35though the second line is given in ``cm``:
36
37.. plot::
38   :include-source:
39   :context:
40
41    plt.plot([1, 2, 3] * u.cm)
42
43Plotting a quantity with an incompatible unit will raise an exception.
44For example, calling ``plt.plot([1, 2, 3] * u.kg)`` (mass unit) to overplot
45on the plot above that is displaying length units.
46
47To make sure unit support is turned off afterward, you can use
48`~astropy.visualization.quantity_support` with a ``with`` statement::
49
50    with quantity_support():
51        plt.plot([1, 2, 3] * u.m)
52
53.. _plotting-times:
54
55Plotting times
56==============
57
58Matplotlib natively provides a mechanism for plotting dates and times on one
59or both of the axes, as described in
60`Date tick labels <https://matplotlib.org/3.1.0/gallery/text_labels_and_annotations/date.html>`_.
61To make use of this, you can use the ``plot_date`` attribute of |Time| to get
62values in the time system used by Matplotlib.
63
64However, in many cases, you will probably want to have more control over the
65precise scale and format to use for the tick labels, in which case you can make
66use of the `~astropy.visualization.time_support` function. This feature needs to
67be explicitly turned on:
68
69.. doctest-requires:: matplotlib
70
71    >>> from astropy.visualization import time_support
72    >>> time_support()  # doctest: +IGNORE_OUTPUT
73    <astropy.visualization.units.MplTimeConverter ...>
74
75Once this is enabled, |Time| objects can be passed to matplotlib plotting
76functions. The axis labels are then automatically labeled with times formatted
77using the |Time| class:
78
79.. plot::
80   :include-source:
81   :context: reset
82
83    from matplotlib import pyplot as plt
84    from astropy.time import Time
85    from astropy.visualization import time_support
86
87    time_support()
88
89    plt.figure(figsize=(5,3))
90    plt.plot(Time([58000, 59000, 62000], format='mjd'), [1.2, 3.3, 2.3])
91
92By default, the format and scale used for the plots is taken from the first time
93that Matplotlib encounters for a particular Axes instance. The format and scale
94can also be explicitly controlled by passing arguments to ``time_support``:
95
96.. plot::
97   :nofigs:
98   :context: reset
99
100   from matplotlib import pyplot as plt
101   from astropy.time import Time
102   from astropy.visualization import time_support
103
104.. plot::
105   :include-source:
106   :context:
107
108    time_support(format='mjd', scale='tai')
109    plt.figure(figsize=(5,3))
110    plt.plot(Time([50000, 52000, 54000], format='mjd'), [1.2, 3.3, 2.3])
111
112To make sure support for plotting times is turned off afterward, you can use
113`~astropy.visualization.time_support` as a context manager::
114
115    with time_support(format='mjd', scale='tai'):
116        plt.figure(figsize=(5,3))
117        plt.plot(Time([50000, 52000, 54000], format='mjd'))
118