p r o p e R

prope [latin] verb Definitions:

1. near, nearby;
2. almost;
3. close by

Contents

• Introduction
• Software Prerequisites
• Installing propeR
  • R installation
  • Docker installation
• Running propeR
  • Data prerequisites
  • Using R
  • Using Docker
• FAQ
• Acknowledgments
• Contributions and Bug Reports
• Licence

Introduction

This R package (propeR) was created to analyse multimodal transport for a number of research projects at the Data Science Campus, Office for National Statistics. This repository is for the installation and use of propeR only, for all OTP graph related guidance, please see graphite.

Software Prerequisites

• R and your GUI of choice, such as RStudio, OR
• Docker

Installing propeR

R installation

The easiest method is to install direct from this GitHub repository using:

library(devtools)
install_github("datasciencecampus/propeR/propeR")

Failing this, you can pull this repository and install locally using:

install("path/to/propeR/dir")

R building

If neither method above works. Or you wish to make changes to the package. Then you will need to build the package. Building propeR requires devtools and roxygen2:

# R
install.packages("devtools")
install.packages("roxygen2")

Then:

build("path/to/propeR/dir")
install("path/to/propeR/dir")

Once you have installed propeR using RStudio you can now start using it in RStudio.

Docker installation

For those who want to run propeR through Docker, we have created a Docker image. The propeR R package can be built from the parent directory as follows:

cd path/to/propeR/dir
docker build . --tag=dsc_proper

Or you can build from the online docker image, using:

docker run datasciencecampus/dsc_proper:1.0

See Dockerfile for more information and dependencies. Once you have installed propeR using Docker you can now start using it in Docker.

Running propeR

Function examples are available in this example.md file.

Data prerequisites

All location data (origin and destination) must be in comma separated (CSV) format and contain the following columns:

• A unique ID column
• A latitude column, where data is in decimal degrees (or a postcode column)
• A longitude column, where data is in decimal degrees (or a postcode column)

The CSV file must contain headers, the header names can be specified in importLocationData().

Using RStudio

As with any R package, it can be loaded in an R session using:

#R
library(propeR)

Then you can use the functions, such as:

#R
pointToPoint(
output.dir="path/to/output/dir", 
originPoints=originPointsdf, 
destinationPoints=destinationPointsdf, 
startDateAndTime="2019-08-02 12:00:00"
)

Outputs will be saved to path/to/output/dir.

Using Docker

Alternatively. If you have installed propeR using Docker you can use Docker to run propeR. Put source and destination .csv data in a directory, e.g., /tmp/data/. Example data files origin.csv and destination.csv can be found in propeR/inst/extdata/, then:

docker run -v path/to/output/dir:/mnt datasciencecampus/dsc_proper:1.0 'otp.host="XXX.XXX.X.X", fun="pointToPoint", src_file="/mnt/origin.csv", dst_file="/mnt/destination.csv", output.dir="/mnt", startDateAndTime="2019-08-02 12:00:00"'

where otp.host is your inet address, which can be found using:

/sbin/ifconfig |grep inet |awk '{print $2}'

Output data will be in path/to/output/dir.

FAQ

Q: How accurate is the cost calculation in the point to point functions?

A: The tool currently cannot ingest fare information. Therefore costEstimate can be used in the point to point functions. This provides an estimate based on the values given in the parameters busTicketPrice, busTicketPriceMax, trainTicketPriceKm and trainTicketPriceMin.

Q: How to I stop propeR printing to the R console:

A: All functions have a parameter called infoPrint. This by default is set to T, please set to F if you want to prevent console printing.

Q: I found a bug!

A: Please use the GitHub issues form to provide us with the information.

Common errors

Q: Why am I receiving the following error when running propeR?

Error in curl::curl_fetch_memory(url, handle = handle) :
  Failed to connect to localhost port 8080: Connection refused
Called from: curl::curl_fetch_memory(url, handle = handle)

A: The OTP server has not been initiated. Please see graphite of this guide.

Q: Why am I receiving the following error when running propeR?

Error in paste0(otpcon, "/plan") : object 'otpcon' not found

A: The OTP connection has not been established. Please see graphite of this guide.

Acknowledgments

• TransXChange2GTFS
• transxchange2gtfs
• dtd2mysql
• OpenTripPlanner
• functions otpConnect(), otpTripTime(), otpTripDistance(), otpIsochrone() are modified from Marcus Young's repo here. Permission to use Marcus Young's code can be found here: marcusyoung/opentripplanner#15

Authors / Contributors

Data Science Campus - Office for National Statistics

• Michael Hodge
• Phillip Stubbings
• Ioannis Tsalamanis

Contributions and Bug Reports

We welcome contributions and bug reports. Please do this on this repo and we will endeavour to review pull requests and fix bugs in a prompt manner.

Built and tested on OS and Windows using R version 3.5.2.

Licence

The Open Government Licence (OGL) Version 3

Copyright (c) 2018 Office of National Statistics

This source code is licensed under the Open Government Licence v3.0. To view this licence, visit www.nationalarchives.gov.uk/doc/open-government-licence/version/3 or write to the Information Policy Team, The National Archives, Kew, Richmond, Surrey, TW9 4DU.