r4ds/workflow-projects.Rmd

# Workflow: projects

One day you will need to quit R, go do something else and return to your analysis later. One day you will have multiple analyses going that use R and you want to keep them separate. One day you will need to bring data from the outside world into R and send numerical results and figures from R back out into the world.

To handle these real life situations, you need to make two decisions:

1.  What about your analysis is "real", i.e. you will save it as your 
    lasting record of what happened?

1.  Where does your analysis "live"?

## What is real?

As a beginning R user, it's OK to consider your environment (i.e. the objects listed in the environment pane) "real". However, in the long-run, you'll be much better off if you consider your R scripts as "real". With the input data and the R code you used, you can reproduce _everything_. You can make your analysis fancier. You can get to the bottom of puzzling results and discover and fix bugs in your code. You can reuse the code to conduct similar analyses in new projects. You can remake a figure with different aspect ratio or save is as TIFF instead of PDF. You are ready to take questions. You are ready for the future.

If you regard your environment as "real" (saving and reloading all the time), it's hard to reproduce an analysis after the fact. You'll either need to retype a lot of code (making mistakes all the way) or will have to mine your R history for the commands you used. Rather than [becoming an expert on managing the R history](https://support.rstudio.com/hc/en-us/articles/200526217-Command-History), a better use of your time and psychic energy is to keep your "good" R code in a script for future reuse.

To foster this behaviour, I highly recommend that you tell RStudio not to preserve your workspace between sessions:

```{r, echo = FALSE, out.width = "75%"}
knitr::include_graphics("screenshots/rstudio-workspace.png")
```

This ensures that every time you restart RStudio you get a completely clean slate. That's good practice because it encourages you to capture all important interactions in your code. There's nothing worse than discovering three months after the fact that you've only stored the results of an important calculation in your workspace, not the calculation itself in your code. 

There is a great pair of keyboard short cuts that will work together to make sure you've captured the important parts of your code in the editor:

1. Press Cmd/Ctrl + Shift + F10 to restart RStudio.
2. Press Cmd/Ctrl + Shift + S to rerun the current script.

I do this probably hundreds of times a day.

## Where does your analysis live?

R has a powerful notion of the __working directory__. This is where R looks, by default, for files that you ask it to load, and where it will put any files that you save to disk. RStudio shows your current working directory at the top of the console:

```{r, echo = FALSE, out.width = NULL}
knitr::include_graphics("screenshots/rstudio-wd.png")
```

And you can print this out in R code by running `getwd()`:

```{r eval = FALSE}
getwd()
#> [1] "/Users/hadley/Documents/r4ds/r4ds"
```

As a beginning R user, it's OK let your home directory or any other weird directory on your computer be R's working directory. But _very soon_ you should evolve to  organising your analytical projects into directories and, when working on project A, set R's working directory to the associated directory.

__Although I do not recommend it__, in case you're curious, you can set R's working directory at the command line like so:

```{r eval = FALSE}
setwd("~/myCoolProject")
```

But there's a better way. A way that also puts you on the path to managing your R work like an expert.

## RStudio projects

Keeping all the files associated with a project organized together -- input data, R scripts, analytical results, figures -- is such a wise and common practice that RStudio has built-in support for this via its _projects_.

[Using Projects](https://support.rstudio.com/hc/en-us/articles/200526207-Using-Projects)

Let's make one for you to use for the rest of this book. Click File > New Project, then:

```{r, echo = FALSE, out.width = "50%"}
knitr::include_graphics("screenshots/rstudio-project-1.png")
knitr::include_graphics("screenshots/rstudio-project-2.png")
knitr::include_graphics("screenshots/rstudio-project-3.png")
```

Call your project `r4ds`.

Once this process is complete, you'll get a new RStudio project that just for this book. Check that the "home" directory for your project is the working directory of our current R process:

```{r eval = FALSE}
getwd()
#> [1] ~/Desktop/r4ds
```

Now, whenever you refer to a file (sans directory) it will look for it in this directory. 

Now enter the following commands in the script editor, then save the file, calling it "diamonds.R". Next, run the complete script which will save a pdf and csv file into your project directory. Don't worry about the details --- you'll learn them later in the book.

```{r toy-line, eval = FALSE}
library(ggplot2)
library(readr)

ggplot(diamonds, aes(carat, price)) + 
  geom_hex()
ggsave("diamonds-hex.pdf")

write_csv(diamonds, "diamonds.csv")
```

Quit RStudio. Inspect the folder associated with your project --- notice the `.Rproj` file. You can click on that to re-open the project in the future (using projects even allows you to have multiple instances of RStudio open at the same time). Maybe view the PDF in an external viewer.

Restart RStudio. Notice you get back to where you left off: it's the save working directory and command history, and all the files you were working on are still open. You will, however, have a completely fresh environment, guaranteeing that you're starting with a clean slate.

In your favorite OS-specific way, search your computer for `diamonds.pdf` and presumably you will find the PDF (no surprise) but _also the script that created it _ (`diamonds.r`). This is huge win! One day you will want to remake a figure or just simply understand where it came from. If you rigorously save figures to file __with R code__ and never with the mouse or the clipboard, you will be able to reproduce old work with ease!

## Overall workflow

RStudio projects give you a solid workflow that will serve you well in the future:

* Create an RStudio project for each data analyis project.
* Keep data files  there; we'll talk about a bit later importing in [import].
* Keep scripts there; edit them, run them in bits or as a whole.
* Save your outputs there.

Everything you need is in one place, and cleanly separated from all the other projects that you are working on.