```{r,include=FALSE}
source("common.R")
```

\mainmatter

# (PART) Getting started {-}

# Introduction {#introduction}

## Welcome to ggplot2

ggplot2 is an R package for producing statistical, or data, graphics. Unlike most other graphics packages, ggplot2 has an underlying grammar, based on the Grammar of Graphics [@wilkinson:2006], that allows you to compose graphs by combining independent components. This makes ggplot2 powerful. Rather than being limited to sets of pre-defined graphics, you can create novel graphics that are tailored to your specific problem. While the idea of having to learn a grammar may sound overwhelming, ggplot2 is actually easy to learn: there is a simple set of core principles and there are very few special cases. The hard part is that it may take a little time to forget all the preconceptions that you bring over from using other graphics tools.

ggplot2 provides beautiful, hassle-free plots that take care of fiddly details like drawing legends. In fact, its carefully chosen defaults mean that you can produce publication-quality graphics in seconds. However, if you do have special formatting requirements, ggplot2's comprehensive theming system makes it easy to do what you want. Ultimately, this means that rather than spending your time making your graph look pretty, you can instead focus on creating the graph that best reveal the message in your data.

ggplot2 is designed to work iteratively. You start with a layer that shows the raw data. Then you add layers of annotations and statistical summaries. This allows you to produce graphics using the same structured thinking that you would use to design an analysis. This reduces the distance between the plot in your head and the one on the page. This is especially helpful for students who have not yet developed the structured approach to analysis used by experts.

Learning the grammar will not only help you create graphics that you're familiar with, but will also help you to create newer, better graphics. Without a grammar, there is no underlying theory, so most graphics packages are just a big collection of special cases. For example, in base R, if you design a new graphic, it's composed of raw plot elements like lines and points so it's hard to design new components that combine with existing plots. In ggplot2, the expressions used to create a new graphic are composed of higher-level elements, like representations of the raw data and statistical transformations, that can easily be combined with new datasets and other plots.

This book provides a hands-on introduction to ggplot2 with lots of example code and graphics. It also explains the grammar on which ggplot2 is based. Like other formal systems, ggplot2 is useful even when you don't understand the underlying model. However, the more you learn about it, the more effectively you'll be able to use ggplot2. This book assumes some basic familiarity with R, the level used in the first chapter of Dalgaard's *Introductory Statistics with R* is a good guide.

This book will introduce you to ggplot2 assuming that you're a novice, unfamiliar with the grammar; teach you the basics so that you can re-create plots you are already familiar with; show you how to use the grammar to create new types of graphics; and eventually turn you into an expert who can build new components to extend the grammar.

## What is the grammar of graphics?

@wilkinson:2006 created the grammar of graphics to describe the fundamental features that underlie all statistical graphics. The grammar of graphics answers the a question: what is a statistical graphic? ggplot2 [@wickham:2007d] builds on Wilkinson's grammar by focussing on the primacy of layers and adapting it for use in R. In brief, the grammar tells us that a graphic maps the data to the aesthetic attributes (colour, shape, size) of geometric objects (points, lines, bars). The plot may also include statistical transformations of the data and information about the plot's coordinate system. Facetting can be used to plot for different subsets of the data. The combination of these independent components are what make up a graphic.

As the book progresses, the formal grammar will be explained in greater detail. The first description of the components follows below. It introduces some of the terminology that will be used throughout the book and outlines the basic function of each component. Don't worry if it doesn't make sense right away: you'll have many more opportunities to learn about the components and how they work together.

All plots are composed of the **data**, the information you want to visualise, and a **mapping**, the description of how the data's variables are mapped to aesthetic attributes. There are five mapping components:

- A **layer** is a collection of geometric elements and statistical
  transformations. Geometric elements, **geom**s for short, represent what you
  actually see in the plot: points, lines, polygons, etc. Statistical
  transformations, **stat**s for short, summarise the data: for example,
  binning and counting observations to create a histogram, or fitting a linear
  model.

- **scale**s map values in the data space to values in the aesthetic space.
  This includes the use of colour, shape or size. Scales also draw the legend
  and axes, which make it possible to read the original data values from the
  plot (an inverse mapping).

- A **coord**, or coordinate system, describes how data coordinates are mapped
  to the plane of the graphic. It also provides axes and gridlines to help read
  the graph. We normally use the Cartesian coordinate system, but a number of
  others are available, including polar coordinates and map projections.

- A **facet** specifies how to break up and display subsets of data as small
  multiples. This is also known as conditioning or latticing/trellising.

- A **theme** controls the finer points of display, like the font size and
  background colour. While the defaults in ggplot2 have been chosen with care,
  you may need to consult other references to create an attractive plot. A good
  starting place is Tufte's early works [@tufte:1990;@tufte:1997;@tufte:2001].

It's also important to note what the grammar doesn't do:

- It doesn't suggest which graphics to use. While this book endeavours to
  promote a sensible process for producing plots, the focus is on how to
  produce the plots you want, not on which plot to produce. For more advice on
  choosing or creating plots to answer the question you're interested in, you
  may want to consult @robbins:2004, @cleveland:1993, @chambers:1983, and
  @tukey:1977.

- It doesn't describe interactive graphics, only static ones. There is
  essentially no difference between displaying ggplot2 graphs on a computer
  screen and printing them on a piece of paper. For dynamic and interactive
  graphics, you'll have to look elsewhere (perhaps at ggvis, described below).
  @cook:2007 provides an excellent introduction to the interactive graphics
  package GGobi. GGobi can be connected to R with the rggobi package
  [@wickham:2008b].

## How does ggplot2 fit in with other R graphics?

There are a number of other graphics systems available in R: base graphics, grid graphics and trellis/lattice graphics. How does ggplot2 differ from them?

- Base graphics were written by Ross Ihaka based on experience implementing the S 
  graphics driver and partly looking at @chambers:1983. Base graphics has a pen 
  on paper model: you can only draw on top of the plot, you cannot modify or 
  delete existing content. There is no (user accessible) representation of the 
  graphics, apart from their appearance on the screen. Base graphics includes 
  both tools for drawing primitives and entire plots. Base graphics functions 
  are generally fast, but have limited scope. If you've created a single 
  scatterplot, or histogram, or a set of boxplots in the past, you've probably 
  used base graphics. \index{Base graphics}

- The development of "grid" graphics, a much richer system of graphical 
  primitives, started in 2000. Grid is developed by Paul Murrell, growing out of 
  his PhD work [@murrell:1998]. Grid grobs (graphical objects) can be 
  represented independently of the plot and modified later. A system of 
  viewports (each containing its own coordinate system) makes it easier to lay
  out complex graphics. Grid provides drawing primitives, but no tools for 
  producing statistical graphics. \index{grid}

- The lattice package, developed by Deepayan Sarkar, uses grid 
  graphics to implement the trellis graphics system of @cleveland:1993 
  and is a considerable improvement over base graphics. You can easily produce 
  conditioned plots and some plotting details (e.g., legends) are taken care 
  of automatically. However, lattice graphics lacks a formal model, which can 
  make it hard to extend. Lattice graphics are explained in depth in 
  @sarkar:2008. \index{lattice}

- ggplot2, started in 2005, is an attempt to take the good things about base 
  and lattice graphics and improve on them with a strong underlying model which 
  supports the production of any kind of statistical graphic, based on 
  the principles outlined above. The solid underlying model of ggplot2 makes it 
  easy to describe a wide range of graphics with a compact syntax, and 
  independent components make extension easy. Like lattice, ggplot2 uses grid 
  to draw the graphics, which means you can exercise much low-level control over 
  the appearance of the plot.

- Work on ggvis, the successor to ggplot2, started in 2014. It takes
  the foundational ideas of ggplot2 but extends them to the web and interactive
  graphics. The syntax is similar, but it's been re-designed from scratch to 
  take advantage of what I've learned in the 10 years since creating ggplot2.
  The most exciting thing about ggvis is that it's interactive and dynamic, so
  plots automatically re-draw themselves when the underlying data or plot
  specification changes. However, ggvis is work in progress and currently can
  create only a fraction of the plots in ggplot2 can. Stay tuned for updates!
  \index{ggvis}
  
- htmlwidgets, <http://www.htmlwidgets.org>, provides a common framework for 
  accessing web visualisation tools from R. Packages built on top of htmlwidgets 
  include leaflet (<https://rstudio.github.io/leaflet/>, maps), 
  dygraph (<http://rstudio.github.io/dygraphs/>, time series) and
  networkD3 (<http://christophergandrud.github.io/networkD3/>, networks).
  htmlwidgets is to ggvis what the many specialised graphic packages are to 
  ggplot2: it provides graphics honed for specific purposes. 
  \index{htmlwidgets}

Many other R packages, such as vcd [@meyer:2006], plotrix [@plotrix] and gplots [@gplots], implement specialist graphics, but no others provide a framework for producing statistical graphics. A comprehensive list of all graphical tools available in other packages can be found in the graphics task view at <http://cran.r-project.org/web/views/Graphics.html>.

## About this book

The first chapter, Chapter \@ref(getting-started), describes how to quickly get started using ggplot2 to make useful graphics. This chapter introduces several important ggplot2 concepts: geoms, aesthetic mappings and facetting. Chapters \@ref(individual-geoms) to \@ref(annotations) dive into more details, giving you a toolbox designed to solve a wide range of problems.

Chapter \@ref(mastery) describes the layered grammar of graphics which underlies ggplot2. The theory is illustrated in Chapter \@ref(layers) which demonstrates how to add additional layers to your plot, exercising full control over the geoms and stats used within them. 

Understanding how scales work is crucial for fine-tuning the perceptual properties of your plot. Customising scales gives fine control over the exact appearance of the plot and helps to support the story that you are telling. Chapter \@ref(scales) will show you what scales are available, how to adjust their parameters, and how to control the appearance of axes and legends.

Coordinate systems and facetting control the position of elements of the plot. These are described in Chapter \@ref(position). Facetting is a very powerful graphical tool as it allows you to rapidly compare different subsets of your data. Different coordinate systems are less commonly needed, but are very important for certain types of data.

To polish your plots for publication, you will need to learn about the tools described in Chapter \@ref(polishing). There you will learn about how to control the theming system of ggplot2 and how to save plots to disk.


## Installation {#installation}
\index{Installation}

To use ggplot2, you must first install it. Make sure you have a recent version of R (at least version 3.2.0) from <http://r-project.org> and then run the following code to download and install ggplot2:

```{r install, eval = FALSE}
install.packages("ggplot2")
```

## Other resources {#other-resources}

This book teaches you the elements of ggplot2's grammar and how they fit together, but it does not document every function in complete detail. You will need additional documentation as your use of ggplot2 becomes more complex and varied.

The best resource for specific details of ggplot2 functions and their arguments will always be the built-in documentation. This is accessible online, <https://ggplot2.tidyverse.org/reference/index.html>, and from within R using the usual help syntax. The advantage of the online documentation is that you can see all the example plots and navigate between topics more easily.

If you use ggplot2 regularly, it's a good idea to sign up for the ggplot2 mailing list, <http://groups.google.com/group/ggplot2>. The list has relatively low traffic and is very friendly to new users. Another useful resource is stackoverflow, <http://stackoverflow.com>. There is an active ggplot2 community on stackoverflow, and many common questions have already been asked and answered. In either place, you're much more likely to get help if you create a minimal reproducible example. The [reprex](https://github.com/jennybc/reprex) package by Jenny Bryan provides a convenient way to do this, and also include advice on creating a good example. The more information you provide, the easier it is for the community to help you.

The number of functions in ggplot2 can be overwhelming, but RStudio provides some great cheatsheets to jog your memory at <http://www.rstudio.com/resources/cheatsheets/>.

Finally, the complete source code for the book is available online at <https://github.com/hadley/ggplot2-book>. This contains the complete text for the book, as well as all the code and data needed to recreate all the plots.

## Colophon

This book was written in [R Markdown](http://rmarkdown.rstudio.com/) inside [RStudio](http://www.rstudio.com/ide/). [knitr](http://yihui.name/knitr/) and [pandoc](http://johnmacfarlane.net/pandoc/) converted the raw Rmarkdown to html and pdf. The complete source is available from [github](https://github.com/hadley/ggplot2-book). This version of the book was built with:

```{r colophon}
devtools::session_info(c("ggplot2", "dplyr", "broom"))
getOption("width")
```
