---
title: "Introduction to tidytransit"
date: "`r Sys.Date()`"
author: "Tom Buckley"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{tidytransit-Introduction}
  %\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](http://tidytransit.r-transit.org/articles/introduction.html#read-gtfs-data)
- [Validate transit feeds](http://tidytransit.r-transit.org/articles/introduction.html#feed-validation-results)
- Coerce [stops and routes to 'simple features'](http://tidytransit.r-transit.org/reference/stops_as_sf.html) and [plot them](http://tidytransit.r-transit.org/reference/plot.gtfs.html)
- [Create graphics about transit service](http://tidytransit.r-transit.org/articles/servicepatterns.html)
- [Calculate travel time between transit stops](http://tidytransit.r-transit.org/reference/raptor.html)
- [Look up GTFS feeds from around the world within R](http://tidytransit.r-transit.org/articles/introduction.html#finding-more-gtfs-feeds)

# 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")
```

For some users, `sf` is impractical to install due to system level dependencies. For these users, [`trread`](https://github.com/r-transit/trread) may work better. Its tidytransit without geospatial tools. 

# The General Transit Feed Specification

The [summary page for the GTFS standard](https://developers.google.com/transit/gtfs/#overview-of-a-gtfs-feed) is a good resource for more information on the standard.  

GTFS feeds contain many linked tables about published transit schedules about 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 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 a 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", 
                               "google_transit_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

Included in the tidytransit package is a dataframe with a list of urls, city names, and locations. 

You can browse it as a data frame:

```{r}
head(feedlist)
```

Note that there is a url (`url_d`) for each feed, which can be used to read the feed for a given city into R. 

For example:

```{r, eval=FALSE}
nyc_ferries_gtfs <- feedlist %>% 
  filter(t=="NYC Ferry GTFS") %>%
  pull(url_d) %>%
  read_gtfs()
```

Included in the transitfeeds table is a set of coordinates for each feed. This means you can filter feed sources by location. Or map all of them, as below:

```{r}
library(sf)

feedlist_sf <- st_as_sf(feedlist,
                        coords=c("loc_lng","loc_lat"),
                        crs=4326)

plot(feedlist_sf, max.plot = 1)
```

See the package reference for the `transitfeeds` data frame for more information on the transitfeeds metadata.