\documentclass[../../book.tex]{subfiles}
\graphicspath{{\subfix{.}}}
\begin{document}
\chapter{Plotting data using Matplotlib}

If you are doing science, you are going to collect data. And if you are collecting data, you are going to want to plot it.  In Python, you have many options for libraries that can plot data. In this chapter, we will explore how to do so for arguably the most common one: Matplotlib. 

We wish to note up front that other libraries may provide better-looking figures, different figure types, or provide better functionality. However, Matplotlib is used here for two reasons.  First (and most important), it is the easiest to get working, which makes it ideal for people new to programming. Once you have a firm grip on programming, you can turn to other libraries.  Second, it is a standard library, and you can find lots of information for it on the internet. 

One more thing to acknowledge: we are focusing on how to construct plots and control many of the aspects of plotting, but we are not focusing on the theory of why you migth want to change these aspects.  If you are curious to understand this, there are many good books on graphic design and the design of data visualizations. Our goal here is to show you how to change plots, but not why. 

%%
\section{The basics of plotting using Matplotlib}

When one plots data, there are a number of elements that are expected.  If we are defining a plot as something that takes quantitative information and then represents it on a 2D surface space, a minimum set of items would be:
\begin{itemize}
    \item the figure area: if we are going to represent something in space, then we need the space to represent it. Conventionally this is something like a piece of paper or computer screen.  Importantly, this area typically needs to be a bit larger than strictly required to show the data, since we often want to include other information like titles, labels, and also our next entry: axes.
    
    \item axes: if we are to arrange objects in space according to quantitative values, then we need a reference for this. We call this reference the axes, which contain a scale against which we plot our data. It is important to note that sometimes axes are not shown, but they are always present. For instance, it is convention to not show axes on pie charts, even though the data is really plotted on radial axes.  
    
    \item the mode of representation: as scientists, we are conversant with many different means of representing data.  We use bars, scatterplots, line plots, histograms, box and whisker plots, etc. Thus, not only do we need a place to draw our representation and a scale against which to represent our data, but we need to know how we are going to represent our data.  
    
    \item data: finally, if we are going to plot data, it makes sense we need data to plot. 
\end{itemize}

The most basic implementation of Matplotlib references each of these ideas in turn. To see this, let us take a set of x-y data and make a scatter plot of it. 

\begin{lstlisting}
EXAMPLE StuFF> 
\end{lstlisting}

Running this produces the following plot in Spyder:


If we refer to our list of essential items, we see that \texttt{plt.figure()} creates an object that maps onto our figure area.  In matplotlib, this element is a container for all the information on our plot. Next, we see that \texttt{fig.subplots()} produces an object that maps onto our idea of axes. There are two things to note here.  First, we use variable \texttt{fig}, which means that the \texttt{subplots()} is a method of the figure object we created.  Second, \texttt{subplots()} actually can generate a series of axes, if we want to have many different plots (i.e., subplots) on this figure.  However, if we only want one, then we can leave the arguments empty. Finally, we see that \texttt{ax.scatter(x, y)} produces an object that maps onto our idea of the mode of representation.  In this case, we wanted a scatterplot, and so we specified that and the x and y data to be plotted. It is important to note here that we didn't really need to assign this object to the variable \texttt{scat}---we will produce the desired plot either way. However, if we do so we can refer back to this \texttt{scatter} object we now can do so using this variable.  Going forward, we will often not assign the mode of representation to a variable.  However, it will \textit{always} prove useful to assign the results of \texttt{plt.figure()} and \texttt{.subplots()} to variables. 

In the above example, there were a few other things worth commenting on.  Let us start at the top: with \texttt{matplotlib.pyplot as plt}.  Since we are using matplotlib, why do we want pyplot, and why do we \textit{only} import this part of matplotlib? Well, to make a \textit{very} long story short, pyplot is the thing that actually allows you to display the plot on your computer. Without pyplot, it is possible to construct a complete figure object that holds axes and a data representation, however, you simply cannot display this on a screen without pyplot. To borrow an old analogy: the figure environment contains a series of instructions that explains how to draw a figure. Pyplot is the person following these instructions to draw the figure.  And since pyplot knows how to follow the instructions, it also contains all the information we need to make the instructions.  So we only need to import pyplot, and we can construct all the figures we want. Specifically, we start these instructions on line xxx when we use \texttt{plt.figure()} and then we just keep adding to them for the next two lines. 

The actual drawing by pyplot brings us to the end of the example, where we find two lines. Though, strictly speaking, they are not both necessary \textbf{we are very VERY strongly recommending that anytime you are creating figures with matplotlib, you end your script with these two lines.}

Let us unpack this recommendation. 

It is most useful to start at the end. \texttt{plt.show()} shows \textbf{all} of the figures we have constructed.  We will see examples throughout this book (and this chapter) in which we make multiple figures, and plt.show() will display all of them.  Importantly, there is no simple way in matplotlib to show only a specific figure \textit{and} once you use \texttt{plt.show()} matplotlib can no longer alter the figures it has shown.  The end result is that you are best constructing all the figures you want to show, and then ending your program by showing them all. 


This brings us to \texttt{plt.ion()}, which turns on `interactive mode"  (ion =  \emph(i)nteraction \emph{on}). The effects of this are three-fold. First, it displays the graphics, in a manner that is somewhat similar to \texttt{plt.show()}, with the difference being that you can still continue to alter the plot.  It turns on the interactive mode, which allows you to zoom in and pan on your data. Third, it makes it so that \texttt{plt.show()} no longer really works.  That is, you no longer end your ability to refer to the graphic elements. 

So why not just use \texttt{plt.ion()} all the time? Well, there are times that it won't work as expected.  In particular, Spyder can have some difficulties with the interactive mode.  So there may be times you want to use \texttt{plt.show()} only.  If you always include it, then you can just comment out \texttt{plt.ion()} and your code will work fine.  On the other hand, if your code and environment handle \texttt{plt.ion()}, then the presence of \texttt{plt.show()} does no harm. This is why we recommend using them both. It is worth noting that you will not see this in examples online, but we really do think that this is the most robust and useful way to implement matplotlib. 

The last thing to note is that this simple example is not something that people would use in communication. Most obviously, there is no title on the x-axis or y-axis. However, there is also inconsitent decimal places on the y, somewhat poor choices in tickmarks, color, and marker size. The plot margins are maybe a bit small, and the font might be improved. All of these things can be adjusted, and understanding how to do so constitutes the rest of this chapter. 










\end{document}