---
title: "Introduction to tidytransit"
date: "2023-06-23"
author: "Tom Buckley"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to tidytransit}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(tidytransit)
library(dplyr)
```
<!-- [![CRAN -->
<!-- status](https://www.r-pkg.org/badges/version/tidytransit?)](https://cran.r-project.org/package=tidytransit) -->

# Introduction

Use tidytransit to:

- [Read a GTFS Feed into R Data Types](https://r-transit.github.io/tidytransit/articles/introduction.html#read-a-gtfs-feed)
- [Validate transit feeds](https://r-transit.github.io/tidytransit/articles/introduction.html#feed-validation-results)
- [Convert stops and routes to 'simple features'](https://r-transit.github.io/tidytransit/reference/gtfs_as_sf.html) and [plot them](https://r-transit.github.io/tidytransit/reference/plot.tidygtfs.html)
- [Calculate travel times between transit stops](https://r-transit.github.io/tidytransit/reference/travel_times.html)
- [Analyse route frequency and headways](https://r-transit.github.io/tidytransit/articles/servicepatterns.html)
- [Analyse calendar data](https://r-transit.github.io/tidytransit/articles/servicepatterns.html)
- [Create time tables for stops](https://r-transit.github.io/tidytransit/articles/timetable.html)

# Installation & Dependencies

This package requires a working installation of [sf](https://github.com/r-spatial/sf#installing). 

```{r, eval=FALSE}
# Once sf is installed, you can install from CRAN with: 
install.packages("tidytransit")

# For the development version from Github:
# install.packages("devtools")
devtools::install_github("r-transit/tidytransit")
```

# The General Transit Feed Specification

The [summary page for the GTFS standard](https://gtfs.org/documentation/overview/) 
is a good resource for more information on the standard.

GTFS feeds contain many linked tables about published transit schedules, service 
schedules, trips, stops, and routes. Below is a diagram of these relationships and tables:

![gtfs-relationship-diagram](figures/GTFS_class_diagram.svg.png)
Source: Wikimedia, user -stk. 

# Read a GTFS Feed

GTFS data come packaged as a zip file of comma separated tables in text form. The first thing 
tidytransit does is consolidate the reading of all those tables into a single R object, which contains 
a list of the tables in each feed. 

Below we use the tidytransit `read_gtfs` function in order to read a feed from the NYC MTA 
into R.

We use an example feed included in the package in the example below. But note that you can read 
directly from the New York City Metropolitan Transit Authority, as shown in the commented 
code below.

You can also read from any other URL. This is useful because there are many sources for 
GTFS data, and often the best source is transit service providers themselves. See the next 
section on "Finding More GTFS Feeds" for more sources of feeds. 

```{r}
# nyc <- read_gtfs("http://web.mta.info/developers/data/nyct/subway/google_transit.zip")

local_gtfs_path <- system.file("extdata", 
                               "nyc_subway.zip", 
                               package = "tidytransit")
nyc <- read_gtfs(local_gtfs_path)
```

You can use `summary` to get an overview of the feed.

```{r}
summary(nyc)
```

Each of the source tables for the GTFS feed is now available in the nyc `gtfs` object. For
example, stops:

```{r}
head(nyc$stops)
```

The tables available on each feed may vary. Below we can simply print the names of all the 
tables that were read in for this feed. Each of these is a table.

```{r}
names(nyc)
```

## Feed Validation Results

When reading a feed, it is checked against the GTFS specification, and an attribute is 
added to the resultant object called `validation_result`, which is a tibble about the files 
and fields in the GTFS feed and how they compare to the specification. 

You can get this tibble from the metadata about the feed. 

```{r}
validation_result <- attr(nyc, "validation_result")
head(validation_result)
```

## Finding More GTFS Feeds

### Feed registries

You can find more feeds on the following sites

- https://database.mobilitydata.org/
- https://www.transit.land/

There might be other feed registries available, depending on your area of interest. 
Transit agencies might also provide their feeds on their on website.

### Using MobilityData

MobilityData.org provide a csv file with all their feed sources on their
[GitHub page](https://github.com/MobilityData/mobility-database-catalogs).

```{r, eval=FALSE}
mbd_url = "https://storage.googleapis.com/storage/v1/b/mdb-csv/o/sources.csv?alt=media"
MobilityData.csv = read.csv(mbd_url)
```

You can load it in R and browse it as a data frame. Tidytransit cannot handle GTFS realtime 
data, so we can remove those entries.

```{r, include=FALSE}
mdb_url = "https://storage.googleapis.com/storage/v1/b/mdb-csv/o/sources.csv?alt=media"
MobilityData.csv = tryCatch(
  read.csv(mdb_url), 
  warning = function(e) { # If URL is not reachable, load local dataset
    readRDS(system.file("extdata", "mobilitydata.rds", package = "tidytransit"))
  })
```

```{r}
MobilityData_feedlist = MobilityData.csv %>% 
  as_tibble() %>% 
  filter(data_type == "gtfs")

str(MobilityData_feedlist)
```

There is a URL (column `urls.direct_download`) for each feed, which 
can be used to read the feed for a given area directly into R. For example:

```{r, eval=FALSE}
gtfs_path_goldengate <- MobilityData_feedlist %>% 
  filter(provider == "Golden Gate Transit") %>%
  pull(urls.direct_download)

gtfs_goldengate = read_gtfs(gtfs_path_goldengate)
```

The MobilityData feedlist contains bounding box coordinates for a feed which can be used to 
give a basic impression of the location of feeds. Note that some bounding boxes might be 
wrong.

First, let's create bounding box polygons.

```{r}
# create a bounding box polygon from min/max corner coordinates
suppressPackageStartupMessages(library(sf))
bbox_polygon = function(lon_min, lon_max, lat_min, lat_max) {
  corner_coords = matrix(
    c(lon_min, lat_min,
      lon_min, lat_max,
      lon_max, lat_max,
      lon_max, lat_min,
      lon_min, lat_min),
    ncol = 2, byrow = TRUE
  )
  polyg = st_polygon(list(corner_coords))
  return(st_sfc(polyg, crs = 4326))
}

# create bounding box polygon (only for reasonable values)
MobilityData_sf = MobilityData_feedlist %>% 
  filter(!is.na(location.bounding_box.minimum_longitude)) %>% 
  filter(location.bounding_box.minimum_latitude > -89) %>% 
  group_by(mdb_source_id) %>% 
  mutate(geometry = bbox_polygon(location.bounding_box.minimum_longitude,
                                 location.bounding_box.maximum_longitude,
                                 location.bounding_box.minimum_latitude,
                                 location.bounding_box.maximum_latitude)) %>% 
  ungroup() %>% 
  st_as_sf()
```

These boxes could now be shown on an interactive map.

```{r, fig.width=7, eval=FALSE}
library(leaflet)
leaflet() %>% 
  addProviderTiles(provider = providers$CartoDB.Positron) %>% 
  addPolygons(data = MobilityData_sf, weight = 2, 
              fillOpacity = 0.1, label = substr(MobilityData_sf$provider, 0, 60))
```
