---
title: "Prerequisites"
author: "Malcolm Morgan"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{opentripplanner-prerequisites}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


## Introduction

This vignette provides guidance for people who new to OpenTripPlanner (OTP) and R.
After you have R and OTP installed and have become familiar with them (e.g. by reading this vignette), we recommend working through [Getting Started vignette](https://docs.ropensci.org/opentripplanner/articles/opentripplanner.html).

### Why would I want to use OpenTripPlanner for R?

[OpenTripPlanner](http://www.opentripplanner.org/) (OTP) is a free, open-source, and cross-platform multi-modal route planner written in Java.  It is like having your own private version of Google Maps. OTP can be used to run public route-finding services such as https://ride.trimet.org but it can also be run on your own computer or server. If you want to analyse a transport networks OTP is a very useful tool. However, OTP is, as the name suggests, a Trip Planner, not analytical software.  So, while OTP can find the fastest route from A to B or find all the places that are within a 20-minute walk of C, it cannot answer a question like “how many people live within 10-minutes of a park?”  This is where R can help.  R can process multiple spatial datasets such as population densities and park locations but does not have a built-in journey planner. 

This package allows you to use the trip planning power of OTP with the analytical might of R.

## What is this package for, and what is a package anyway?

The `opentripplanner` R package makes it easier for R and OpenTripPlanner to communicate.
Specifically, it allows you to do use R to control OTP and use it as a local routing service.
For more on local versus remote routing services, see the Transportation chapter in [Geocomputation with R](https://r.geocompx.org/transport.html).

### What are R and RStudio?

[R](https://www.r-project.org/) is an open-source programming language and free software environment for statistical computing and graphics.  R has many capabilities for analysing data and writing software, but in this context, its ability to produce and analyse spatial data and maps is most relevant. [RStudio](https://posit.co/products/open-source/rstudio/) is an Integrated Development Environment (IDE) for R which is free for personal use.

### What is an R package?

An R package is a small piece of software that extends the basic capabilities of R. It is a bit like how a new phone can do some things out of the box (make phone calls, send email) but you have to install apps to add extra abilities.

### Help with R

To get started with R, see [An Introduction to R](https://cran.r-project.org/doc/manuals/r-release/R-intro.pdf) or from within R by running `help.start()`, introductory tutorials such as DataCamp's free Introduction to R course, or the [R tutor website](https://www.r-tutor.com/r-introduction). The [Geocomputation with R](https://r.geocompx.org/) book covers the packages and skills required to analyse spatial datasets such as those produced by OpenTripPlanner.

A video tutorial for installing R and RStudio 

* On [Mac](https://www.youtube.com/watch?v=cX532N_XLIs) 
* On [Windows](https://www.youtube.com/watch?v=9-RrkJQQYqY)


## What do I need to get started?

You will need a modern computer and to install some software to use OTP and R on your local computer.

### Hardware

Running your own trip planner is computationally expensive an so the best results will be had on a modern desktop computer. This package comes with some demonstration data for the Isle of Wight, which as a very small area will run on most modern laptops and desktops.

**Recommended Hardware**

* Modern CPU (2010 or later)
* 64 Bit Operating System (Windows/Mac/Linux)
* 8+ GB RAM
* 64 GB+ Hard Disk

**Minimum Hardware**

* 32 Bit Operating System (Windows/Mac/Linux)
* 2 GB RAM

OTP requires at least 1 GB of space to run the demonstration dataset, but by default will request 2 GB. On low-end machines, it is necessary to change the default memory allocations and minimise memory use by other programmes. 

For larger areas OTP will need more memory. An approximate guide to memory use is:

* 2 GB - Small Town / Region
* 4 GB - Large Town / City
* 8 GB - Region / Very Large City
* 20 GB - Country
* 50 GB - Continent

OTP is optimised for city-scale routing and performance will degrade with larger areas, although OTP is used successfully with several small European Countries e.g. the Netherlands.

**Note** If you use a 32 Bit version of Java the maximum amount of memory that can be used by OTP is 4 GB.

### Software

The OpenTripPlanner for R package requires:

* R - [download R](https://cran.r-project.org/mirrors.html) selecting your country (or nearest available country)
* RStudio - [download free version](https://posit.co/download/rstudio-desktop/) for personal use. RStudio is not essential but is strongly recommended.
* Java **Note** The version of Java you need depends on the version of OTP you want to use.

#### The correct version of Java for OTP

Different versions of OTP require different version of Java

* OTP v1.5 - Java 8 - **Recommended for beginners**
* OTP v2.0 & v2.1 - Java 11
* OTP v2.2 - Java 17

Use of OTP v1.5 is the default for this package and recommended for beginners and it is stable and full featured. Future updates of the package will add more support for OTP v2.2+.

If possible the 64 Bit version of Java is preferable, especially if you want to use OTP over large areas.

The package includes a simple function for checking if you have the correct version of Java `otp_check_java()`.

To get Java:

* **Windows/Mac** https://www.java.com/en/download/ This link defaults to the 32 Bit version, so also check https://www.java.com/en/download/help/java_win64bit.html.

* **Linux**  we recommend instructions at [StackOverflow](https://askubuntu.com/questions/740757/switch-between-multiple-java-versions).

For Debian based Linux including Ubuntu and Linux Mint, the following commands in the terminal will install the correct version.

```{eval = FALSE}
sudo apt install openjdk-8-jdk
```

## Next Steps

Now that you have installed Java and R go to the [Getting Started vignette](https://docs.ropensci.org/opentripplanner/articles/opentripplanner.html), to find how to install the package, create a graph, and use it to plan trips.
