Update README, fix ropensci#82

.Rbuildignore

@@ -8,3 +8,5 @@ log-latest
 .travis.yml
 ^revdep$
 ^CONDUCT\.md$
+^README\.Rmd$
+^README-.*\.png$

README.Rmd

@@ -1,30 +1,39 @@
 ---
-title: "stplanr"
-bibliography: vignettes/Transport-r-flows.bib
-output:
-  html_document:
-    keep_md: yes
+output: github_document
 ---
 
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+```{r, echo = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  fig.path = "README-"
+)
+```
+
 [![Build Status](https://travis-ci.org/ropensci/stplanr.svg?branch=master)](https://travis-ci.org/ropensci/stplanr) [![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/stplanr)](http://cran.r-project.org/package=stplanr)
 [![rstudio mirror downloads](http://cranlogs.r-pkg.org/badges/stplanr)](https://github.com/metacran/cranlogs.app)
 
 ```{r, echo=FALSE, message=FALSE}
 library(stplanr)
 ```
 
-This is a package for sustainable transport planning with R (stplanr).
+This package is for sustainable transport planning with R (hence the name **stplanr**).
 
 It brings together a range of tools for transport planning practitioners and
 researchers to better understand transport systems and inform policy.
 
 The initial work on the project was funded by the Department of Transport
 ([DfT](https://www.gov.uk/government/organisations/department-for-transport))
-as part of the National Propensity to Cycle Tool
-([NPCT](http://www.ecf.com/news/national-propensity-to-cycle-tool-project-summary-report/)) project to
-identify where bicycle paths are most urgently needed.
-
-stplanr aims to be of use to researchers everywhere.
+as part of the Propensity to Cycle Tool
+([PCT](http://pct.bike/)) project to
+identify where bicycle paths are most urgently needed. Please see
+the package [vignette](https://cran.r-project.org/web/packages/stplanr/vignettes/introducing-stplanr.html)
+or an [academic paper on the PCT](http://arxiv.org/abs/1509.04425)
+for more information on how it can be used. This README gives some basics.
+
+**stplanr** should be useful to researchers everywhere.
 The function `route_graphhopper()`, for example, works anywhere in the world
 using the [graphhopper](https://graphhopper.com/) routing API and
 `read_table_builder()` reads-in Australian data. We welcome contributions that make
@@ -116,11 +125,11 @@ rnet <- overline(sldf = t_routes, attrib = "All", fun = sum)
 osm_tiles <- read_osm(bb(rnet, ext = 1.05))
 rnet$lwd <- rnet$All / mean(rnet$All)
 tm_shape(osm_tiles) +
-    tm_raster(saturation = .25) +
-tm_shape(rnet) +
-    tm_lines(lwd = "lwd", scale = 5, legend.lwd.show = FALSE)  +
-tm_shape(cents) +
-    tm_bubbles()
+  tm_raster(saturation = .25) +
+  tm_shape(rnet) +
+  tm_lines(lwd = "lwd", scale = 5, legend.lwd.show = FALSE)  +
+  tm_shape(cents) +
+  tm_bubbles()
 ```
 
 ## Installation
@@ -178,4 +187,4 @@ To get internal help on a specific function, use the standard way.
 * This project is released with a [Contributor Code of Conduct](CONDUCT.md).
 By participating in this project you agree to abide by its terms.
 
-[![rofooter](http://ropensci.org/public_images/github_footer.png)](http://ropensci.org)
+[![rofooter](http://ropensci.org/public_images/github_footer.png)](http://ropensci.org)

README.md

@@ -1,98 +1,66 @@
-# stplanr
 
-[![Build Status](https://travis-ci.org/ropensci/stplanr.svg?branch=master)](https://travis-ci.org/ropensci/stplanr) [![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/stplanr)](http://cran.r-project.org/package=stplanr)
-[![rstudio mirror downloads](http://cranlogs.r-pkg.org/badges/stplanr)](https://github.com/metacran/cranlogs.app)
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+[![Build Status](https://travis-ci.org/ropensci/stplanr.svg?branch=master)](https://travis-ci.org/ropensci/stplanr) [![CRAN\_Status\_Badge](http://www.r-pkg.org/badges/version/stplanr)](http://cran.r-project.org/package=stplanr) [![rstudio mirror downloads](http://cranlogs.r-pkg.org/badges/stplanr)](https://github.com/metacran/cranlogs.app)
 
+This package is for sustainable transport planning with R (hence the name **stplanr**).
 
+It brings together a range of tools for transport planning practitioners and researchers to better understand transport systems and inform policy.
 
-This is a package for sustainable transport planning with R (stplanr).
+The initial work on the project was funded by the Department of Transport ([DfT](https://www.gov.uk/government/organisations/department-for-transport)) as part of the Propensity to Cycle Tool ([PCT](http://pct.bike/)) project to identify where bicycle paths are most urgently needed. Please see the package [vignette](https://cran.r-project.org/web/packages/stplanr/vignettes/introducing-stplanr.html) or an [academic paper on the PCT](http://arxiv.org/abs/1509.04425) for more information on how it can be used. This README gives some basics.
 
-It brings together a range of tools for transport planning practitioners and
-researchers to better understand transport systems and inform policy.
+**stplanr** should be useful to researchers everywhere. The function `route_graphhopper()`, for example, works anywhere in the world using the [graphhopper](https://graphhopper.com/) routing API and `read_table_builder()` reads-in Australian data. We welcome contributions that make transport research easier worldwide.
 
-The initial work on the project was funded by the Department of Transport
-([DfT](https://www.gov.uk/government/organisations/department-for-transport))
-as part of the National Propensity to Cycle Tool
-([NPCT](http://www.ecf.com/news/national-propensity-to-cycle-tool-project-summary-report/)) project to
-identify where bicycle paths are most urgently needed.
+Key functions
+-------------
 
-stplanr aims to be of use to researchers everywhere.
-The function `route_graphhopper()`, for example, works anywhere in the world
-using the [graphhopper](https://graphhopper.com/) routing API and
-`read_table_builder()` reads-in Australian data. We welcome contributions that make
-transport research easier worldwide.
+Data frames representing flows between origins and destinations must be combined with geo-referenced zones or points to generate meaningful analyses and visualisations of 'flows' or origin-destination (OD) data ([Caceres 2007](https://www.researchgate.net/profile/Francisco_Benitez/publication/3480996_Deriving_origin_destination_data_from_a_mobile_phone_network/links/0f31753ad7db9e7ece000000.pdf)). **stplanr** facilitates this with `od2line()`, which takes flow and geographical data as inputs and outputs a `SpatialLinesDataFrame`. Some example data is provided in the package:
 
-## Key functions
-
-Data frames representing flows between origins and destinations
-must be combined with geo-referenced zones or points to generate meaningful
-analyses and visualisations of 'flows' or origin-destination (OD) data
-([Caceres 2007](https://www.researchgate.net/profile/Francisco_Benitez/publication/3480996_Deriving_origin_destination_data_from_a_mobile_phone_network/links/0f31753ad7db9e7ece000000.pdf)).
-**stplanr** facilitates this with
-`od2line()`, which takes flow and geographical data as inputs and
-outputs a `SpatialLinesDataFrame`. Some example data is provided in the package:
-
-
-```r
+``` r
 library(stplanr)
 data(cents, flow)
 ```
 
 Let's take a look at this data:
 
-
-```r
+``` r
 flow[1:3, 1:3] # typical form of flow data
-```
-
-```
-##        Area.of.residence Area.of.workplace All
-## 920573         E02002361         E02002361 109
-## 920575         E02002361         E02002363  38
-## 920578         E02002361         E02002367  10
-```
-
-```r
+#>        Area.of.residence Area.of.workplace All
+#> 920573         E02002361         E02002361 109
+#> 920575         E02002361         E02002363  38
+#> 920578         E02002361         E02002367  10
 cents[1:3,] # points representing origins and destinations
-```
-
-```
-## class       : SpatialPointsDataFrame 
-## features    : 3 
-## extent      : -1.546463, -1.511861, 53.8041, 53.81161  (xmin, xmax, ymin, ymax)
-## coord. ref. : +init=epsg:4326 +proj=longlat +datum=WGS84 +no_defs +ellps=WGS84 +towgs84=0,0,0 
-## variables   : 4
-## names       :  geo_code,  MSOA11NM, percent_fem,  avslope 
-## min values  : E02002382, Leeds 053,    0.408759, 2.284782 
-## max values  : E02002393, Leeds 064,    0.458721, 2.856563
+#> class       : SpatialPointsDataFrame 
+#> features    : 3 
+#> extent      : -1.546463, -1.511861, 53.8041, 53.81161  (xmin, xmax, ymin, ymax)
+#> coord. ref. : +init=epsg:4326 +proj=longlat +datum=WGS84 +no_defs +ellps=WGS84 +towgs84=0,0,0 
+#> variables   : 4
+#> names       :  geo_code,  MSOA11NM, percent_fem,  avslope 
+#> min values  : E02002382, Leeds 053,    0.408759, 2.284782 
+#> max values  : E02002393, Leeds 064,    0.458721, 2.856563
 ```
 
 These datasets can be combined as follows:
 
-
-```r
+``` r
 travel_network <- od2line(flow = flow, zones = cents)
 w <- flow$All / max(flow$All) *10
 plot(travel_network, lwd = w)
 ```
 
-![](README_files/figure-html/plot1-1.png)\
+![](README-plot1-1.png)
 
-The package can also allocate flows to the road network, for example through
-a link to the [CycleStreets.net API](https://www.cyclestreets.net/api/).
+The package can also allocate flows to the road network, for example through a link to the [CycleStreets.net API](https://www.cyclestreets.net/api/).
 
 Route functions take lat/lon inputs:
 
-
-```r
+``` r
 trip <-
   route_cyclestreet(from = c(-1, 53), to = c(-1.1, 53), plan = "balanced")
 ```
 
 and place names, found using the Google Map API:
 
-
-```r
+``` r
 trip <- route_cyclestreet("London", "Birmingham, UK", plan = "balanced")
 # devtools::install_github("mtennekes/tmap", subdir = "pkg")
 library(tmap)
@@ -103,68 +71,59 @@ tm_shape(osm_tiles) +
   tm_lines(lwd = 3)
 ```
 
-![](README_files/figure-html/cycle-trip-1.png)\
-
-We can replicate this call to CycleStreets.net multiple times
-using `line2route`.
+![](README-cycle-trip-1.png)
 
+We can replicate this call to CycleStreets.net multiple times using `line2route`.
 
-```r
+``` r
 # Remove intra-zone flow
 intrazone <- travel_network$Area.of.residence == travel_network$Area.of.workplace
 travel_network <- travel_network[!intrazone,]
 t_routes <- line2route(travel_network)
 plot(t_routes)
 ```
 
-![](README_files/figure-html/plot2-1.png)\
+![](README-plot2-1.png)
 
 Another way to visualise this is with the leaflet package (not shown):
 
-
-```r
+``` r
 library(leaflet)
 leaflet() %>% addTiles() %>% addPolylines(data = t_routes)
 ```
 
 For more examples, `example("line2route")`.
 
-`overline` is a function which takes a series of route-allocated lines,
-splits them into unique segmentes and aggregates
-the values of overlapping lines. This can represent where there will be
-most traffic on the transport system, as illustrated
-below using the [tmap](https://github.com/mtennekes/tmap) package.
-
+`overline` is a function which takes a series of route-allocated lines, splits them into unique segmentes and aggregates the values of overlapping lines. This can represent where there will be most traffic on the transport system, as illustrated below using the [tmap](https://github.com/mtennekes/tmap) package.
 
-```r
+``` r
 t_routes$All <- travel_network$All
 rnet <- overline(sldf = t_routes, attrib = "All", fun = sum)
 
 osm_tiles <- read_osm(bb(rnet, ext = 1.05))
 rnet$lwd <- rnet$All / mean(rnet$All)
 tm_shape(osm_tiles) +
-    tm_raster(saturation = .25) +
-tm_shape(rnet) +
-    tm_lines(lwd = "lwd", scale = 5, legend.lwd.show = FALSE)  +
-tm_shape(cents) +
-    tm_bubbles()
+  tm_raster(saturation = .25) +
+  tm_shape(rnet) +
+  tm_lines(lwd = "lwd", scale = 5, legend.lwd.show = FALSE)  +
+  tm_shape(cents) +
+  tm_bubbles()
 ```
 
-![](README_files/figure-html/rnet-1.png)\
+![](README-rnet-1.png)
 
-## Installation
+Installation
+------------
 
 To install the stable version, use:
 
-
-```r
+``` r
 install.packages("stplanr")
 ```
 
 The development version can be installed using devtools:
 
-
-```r
+``` r
 # install.packages("devtools") # if not already installed
 devtools::install_github("ropensci/stplanr")
 library(stplanr)
@@ -176,39 +135,33 @@ stplanr depends on rgdal, which can be tricky to install.
 
 On Ubuntu rgdal can be installed with:
 
-```
-sudo apt-get install r-cran-rgdal
-```
-
-Using apt-get ensures the system dependencies, such as
-[gdal](http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries) are also installed.
+    sudo apt-get install r-cran-rgdal
 
-On Mac, homebrew can install gdal. Full instructions are provided
-[here](https://github.com/ropensci/geojsonio#install).
+Using apt-get ensures the system dependencies, such as [gdal](http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries) are also installed.
 
+On Mac, homebrew can install gdal. Full instructions are provided [here](https://github.com/ropensci/geojsonio#install).
 
-## Funtions, help and contributing
+Funtions, help and contributing
+-------------------------------
 
 The current list of available functions can be seen with:
 
-
-```r
+``` r
 lsf.str("package:stplanr", all = TRUE)
 ```
 
 To get internal help on a specific function, use the standard way.
 
-
-```r
+``` r
 ?od2line
 ```
 
-## Meta
+Meta
+----
 
-* Please report issues, feature requests and questions to the [github issue tracker](https://github.com/ropensci/stplanr/issues)
-* License: MIT
-* Get citation information for `stplanr` in R doing `citation(package = 'stplanr')`
-* This project is released with a [Contributor Code of Conduct](CONDUCT.md).
-By participating in this project you agree to abide by its terms.
+-   Please report issues, feature requests and questions to the [github issue tracker](https://github.com/ropensci/stplanr/issues)
+-   License: MIT
+-   Get citation information for `stplanr` in R doing `citation(package = 'stplanr')`
+-   This project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.
 
 [![rofooter](http://ropensci.org/public_images/github_footer.png)](http://ropensci.org)