README.Rmd

---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
knitr::opts_knit$set(
  knitr.kable.NA = ''
)
`%>%` <- magrittr::`%>%`
```

# trainR: An Interface to the National Rail Enquiries Systems <img src="https://raw.githubusercontent.com/villegar/trainR/main/inst/images/logo.png" alt="logo" align="right" height=200px/>

<!-- badges: start -->
`r badger::badge_cran_release("trainR", "black")`
`r badger::badge_devel("villegar/trainR", "yellow")`
`r badger::badge_github_actions("villegar/trainR")`
`r badger::badge_doi("10.5281/zenodo.4506590", "black")`
<!-- `r badger::badge_lifecycle()` -->
<!-- badges: end -->

The goal of `trainR` is to provide a simple interface to the 
National Rail Enquiries (NRE) systems. There are few data feeds 
available, the simplest of them is Darwin, which provides real-time 
arrival and departure predictions, platform numbers, delay estimates, 
schedule changes and cancellations. Other data feeds provide historical 
data, Historic Service Performance (HSP), and much more. `trainR` 
simplifies the data retrieval, so that the users can focus on their 
analyses. For more details visit 
https://www.nationalrail.co.uk/46391.aspx.

## Installation

You can install the released version of trainR from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("trainR")
```

And the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("villegar/trainR", "dev")
```

## Setup
Before starting to retrieve data from the NRE data feeds, you must obtain an access token. 
Visit the following website for details: http://realtime.nationalrail.co.uk/OpenLDBWSRegistration/

Once you have received your access token, you have to store it in the `.Renviron` file; this can be 
done by executing the following command:

```{r, eval = FALSE}
trainR::set_token()
```

This will open a text file, `.Renviron`, add a new line at the end (as follows):
```{bash}
NRE="<token>"
```

`<token>` should be replaced by the access token obtained from the NRE. Save the changes and restart 
your R session.

You only need to perform this configuration once.

## Example

Load `trainR` to your working environment:
```{r, message = FALSE}
library(trainR)
```

### Arrivals board at Reading Station (RDG)

Generated on `r lubridate::now()`.

```{r arrivals}
rdg_arr <- trainR::GetArrBoardWithDetailsRequest("RDG")
print(rdg_arr)
```

<!-- Inspect the `rdg_arr` object: -->

```{r, eval = FALSE, echo = FALSE}
rdg_arr %>%
  dplyr::select(-c(5:6)) %>% # Drop the lists of train and bus services
  knitr::kable()
if (!is.na(rdg_arr %>% dplyr::select(5) %>% .[[1]]))
  rdg_arr %>%
    dplyr::select(5) %>%
    .[[1]] %>%
    .[[1]] %>%
    dplyr::select(-previousCallingPoints) %>%
    knitr::kable(caption = "Train services")
if (!is.na(rdg_arr %>% dplyr::select(6) %>% .[[1]]))
  rdg_arr %>%
    dplyr::select(6) %>%
    .[[1]] %>%
    .[[1]] %>%
    dplyr::select(-previousCallingPoints) %>%
    knitr::kable(caption = "Bus services")
```

<!-- #### Previous calling points -->
```{r arrivals-calling-points, eval = FALSE, echo = FALSE}
rdg_arr %>%
  dplyr::select(5) %>%
  .[[1]] %>%
  .[[1]] %>%
  dplyr::select(previousCallingPoints) %>%
  .[[1]] %>%
  knitr::kable(caption = "Train services")
```

### Departures board at Reading Station (RDG)

Generated on `r lubridate::now()`.

```{r departures}
rdg_dep <- trainR::GetDepBoardWithDetailsRequest("RDG")
print(rdg_dep)
```

### Add some colour (Terminal output only)
Now you can add some colour to the service boards, based on their expected time:

- "On time" and early services: `green`
- "Delayed" and delayed by 5 or less minutes: `yellow`
- "Cancelled" and delayed over 5 minutes: `red`

Without colours:
```{r, eval = FALSE}
trainR::GetDepBoardWithDetailsRequest("CRE")
```
<img alt="Crewe station - Departures Board" src="man/figures/README-CRE-DEP-terminal-output-1.png" style="max-width:500px;width:100%">

With colours:
```{r, eval = FALSE}
options(show_colours = TRUE)
trainR::GetDepBoardWithDetailsRequest("CRE")
```
<img alt="Crewe station - Departures Board" src="man/figures/README-CRE-DEP-terminal-output-2.png" style="max-width:500px;width:100%">

```{r departures-old, echo = FALSE, eval = FALSE}
# rdg_dep <- trainR::GetArrDepBoardWithDetailsRequest("rdg_dep") %>%
#   dplyr::mutate(origin = purrr::transpose(.$origin) %>%
#                   purrr::pluck("crs") %>%
#                   purrr::map_chr(as.character),
#                 destination = purrr::transpose(.$destination) %>%
#                   purrr::pluck("crs") %>%
#                   purrr::map_chr(as.character))
# 
# rdg_dep %>%
#   dplyr::select(-11) %>% # Drop the calling points list
#   knitr::kable()
```

<!-- #### Previous calling points -->
```{r departures-calling-points, echo = FALSE}
# names(rdg_dep$previousCallingPoints) <- rdg_dep$serviceID
# trainR::get_calling_points(rdg_dep$previousCallingPoints) %>%
#   dplyr::left_join(rdg_dep[, c(7, 9, 10)], by = "serviceID") %>%
#   dplyr::select(-c("timestamp")) %>%
#   knitr::kable()
```

## Get services without details (calling points)
These requests are useful if the calling points are not relevant for your analyses, visualisations, etc.

### Arrivals board at Reading Station (RDG)

Generated on `r lubridate::now()`.

```{r arrivals-wo-details}
rdg_arr <- trainR::GetArrBoardRequest("RDG")
print(rdg_arr)
```

### Departures board at Reading Station (RDG)

Generated on `r lubridate::now()`.

```{r departures-wo-details}
rdg_dep <- trainR::GetDepBoardRequest("RDG")
print(rdg_dep)
```

## Acknowledgements

Access to the data feeds it is only possible thanks to the National Rail Enquiries. This package is just a tool to facilitate access to the data. For more information about the available data feeds, visit https://www.nationalrail.co.uk.

<img alt="Powered by NRE logo" src="https://raw.githubusercontent.com/villegar/trainR/main/inst/images/NRE_Powered_logo.jpg" style="max-width:400px;width:100%">

## Code of Conduct

Please note that the `trainR` package is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.