index.Rmd

--- 
title: "DfT R Cookbook"
author: "Isi Avbulimen, Hannah Bougdah, Tamsin Forbes, Andrew Kelly, Tim Taylor"
date: "`r Sys.Date()`"
site: bookdown::bookdown_site
output: 
  bookdown::gitbook:
    df_print: kable
    fig_width: 7
    fig_height: 6
documentclass: book
bibliography: [book.bib, packages.bib]
biblio-style: apalike
link-citations: yes
github-repo: departmentfortransport/R-cookbook
description: "Guidance and code examples for R usage for DfT and beyond"

---
```{r include=FALSE}
require(dplyr)
require(knitr)

options(knitr.table.format = "html")

# Load example data for Road Casualties in Great Britain 1969-84
data(mtcars)

# Look at the data
mtcars <- tibble::as.tibble(mtcars) %>%
  # Add rows for dplyr example
  tibble::rownames_to_column(var = "car")
```

# Why do we need _another_ book?

`R` is a very flexible programming language, which inevitably means there are lots of ways to achieve the same result. This is true of all programming languages, but is particularly exaggerated in `R` which makes use of ['meta-programming'](http://adv-r.had.co.nz/). 

For example, here is how to calculate a new variable using standard R and filter on a variable:
```{r}
# Calculate kilometers per litre from miles per gallon
mtcars$kpl <- mtcars$mpg * 0.425144

# Select cars with a horsepower greater than 250 & show only mpg and kpl columns
mtcars[mtcars$hp > 250, c("car", "mpg", "kpl")]

```

Here's the same thing using Tidyverse style R:
```{r}

mtcars %>%
  # Calculate kilometers per litre
  dplyr::mutate(
    kpl = mpg * 0.425144
  ) %>%
  # Filter cars with a horsepower greater than 250
  dplyr::filter(
    hp > 250
  ) %>%
  # Take only the car, mpg, and newly created kpl columns
  dplyr::select(car, mpg, kpl)
```

These coding styles are quite different. As people write more code across the Department, it will become increasingly important that code can be handed over to other R users. It is much easier to pick up code written by others if it uses the same coding style you are familiar with. 

This is the main motivation for this book, to establish a way of coding that represents a sensible default for those who are new to R that is readily transferable across DfT. 


## Coding standards

Related to this, the Data Science team maintain a [coding standards document](https://departmentfortransport.github.io/ds-processes/Coding_standards/r.html), that outlines some best practices when writing R code. This is not prescriptive and goes beyond the scope of this document, but might be useful for managing your R projects. 

## Adding to the book

This book is not static - new chapters can be added and current chapters can be amended. If you want to edit or write a chapter for the book, check out the [GitHub page](https://github.com/departmentfortransport/ds-r-training). 


```{r include=FALSE}
# automatically create a bib database for R packages
knitr::write_bib(c(
  .packages(), "bookdown", "knitr", "rmarkdown"
), "packages.bib")
```