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%",
  message = FALSE
)
```

# zugr

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->

Just a small package that wraps the Fahrplan API of the German train company [db](https://www.bahn.de).
The main idea is to be able to be able to cast your net a bit wider in cases when you are flexible to go on a different hour, day, or week.

## Installation

You can install the development version of zugr like so (or with `remotes`, but the cool kids use `pak` now :grin:):

``` r
# install.packages("pak)
pak::pak("JBGruber/zugr")
```

## Example: When should I go to Amsterdam

A journey that I take often is from Wiesbaden to Amsterdam.
There are really fast connections between these cities, which is awsome!
What is less great is trying to decide if I go Monday or Tuesday, on the weekend or during the week, or if I should rather go in a different week?
If you've used the interface of [bahn.de](https://www.bahn.de), you know these decisions require a lot of useless click-work.
Well not anymore...

The first step is to get the station ID for the main stations in Wiesbaden and Amsterdam:

```{r example}
library(zugr)
wi <- search_station("Wiesbaden")
wi
```

The first one is what I need!
Now Amsterdam.
Here I don't need as many options:

```{r}
adam <- search_station("Amsterdam", n_res = 1)
adam
```

Now I can make a search for next Tuesday Morning (as of writing this):

```{r}
next_tuesday <- bahn_search(
  from = wi$id[1],
  to = adam$id[1],
  start = "2023-10-03T05:00:00",
  end =  "2023-10-03T19:00:00"
)
next_tuesday
```

Note that the `end` parameter marks the time at which the train should arrive at the latest,
while `start` marks the earliest departure that should be included in the results.

So what is the cheapest connection?
Easy to see with some `R` commands :smirk::

```{r}
library(tidyverse)
next_tuesday |> 
  slice_min(price, n = 1) |> 
  select(-id)
```

With 4 connections and more than 6 hours, this is a rather terrible connections.
It is cheap though.
Let's see s quick visualisation instead:

```{r}
next_tuesday |> 
  # some connections include trains from different companies, the prices for
  # these are not oncluded
  filter(!is.na(price)) |>
  ggplot(aes(x = start, y = price, label = changes, fill = duration)) +
  geom_col() +
  geom_text(aes(y = price / 2), colour = "white") +
  scale_y_continuous(labels = function(x) paste0(x, "€")) +
  scale_fill_gradient(labels = function(x) paste0(round(x / 60 / 60, 1), "h")) +
  labs(x = "depature", y = NULL, 
       title = "Prices and number of changes for different connections") +
  theme_minimal()
```

With more data, this gets a little more interesting.