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