Merge pull request #122 from UrbanAnalyst/pkgcheck

Add examples for #113

.github/workflows/check-standard.yaml

@@ -18,8 +18,8 @@ jobs:
       fail-fast: false
       matrix:
         config:
-          # - {os: macos-latest,   r: 'release'}
-          # - {os: windows-latest, r: 'release'}
+          - {os: macos-latest,   r: 'release'}
+          - {os: windows-latest, r: 'release'}
           - {os: ubuntu-latest,   r: 'devel', http-user-agent: 'release'}
           - {os: ubuntu-latest,   r: 'release'}
             # - {os: ubuntu-latest,   r: 'oldrel-1'}

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to gtfsrouter
+
+## Opening issues
+
+The easiest way to note any behavioural curiosities or to request any new
+features is by opening a [github issue](https://github.com/UrbanAnalyst/gtfsrouter/issues).
+
+
+## Development guidelines
+
+If you'd like to contribute changes to `gtfsrouter`, we use [the GitHub
+flow](https://guides.github.com/introduction/flow/index.html) for proposing,
+submitting, reviewing, and accepting changes. If you haven't done this before,
+there's a nice overview of git [here](https://r-pkgs.org/git.html), as well
+as best practices for submitting pull requests
+[here](https://r-pkgs.org/git.html#pr-make).
+
+The `gtfsrouter` coding style diverges somewhat from [this commonly used R style
+guide](http://adv-r.had.co.nz/Style.html), primarily in the following two ways,
+both of which improve code readability: (1) All curly braces are vertically aligned:
+```r
+this <- function ()
+{
+    x <- 1
+}
+```
+and **not**
+```r
+this <- function(){
+    x <- 1
+}
+```
+and (2) Also highlighted in that code is the additional whitespace which
+permeates `gtfsrouter` code. Words of text are separated by whitespace, and so
+code words should be too:
+```r
+this <- function1 (function2 (x))
+```
+and **not**
+```r
+this <- function1(function2(x))
+```
+with the natural result that one ends up writing
+```r
+this <- function ()
+```
+with a space between `function` and `()`. That's it.
+
+
+## Code of Conduct
+
+We want to encourage a warm, welcoming, and safe environment for contributing to
+this project. See the
+[code of conduct](https://github.com/UrbanAnalyst/gtfsrouter/blob/master/CONDUCT.md) for
+more information.

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: gtfsrouter
 Title: Routing with 'GTFS' (General Transit Feed Specification) Data
-Version: 0.1.2.020
+Version: 0.1.2.029
 Authors@R: c(
     person("Mark", "Padgham", , "mark.padgham@email.com", role = c("aut", "cre")),
     person("Marcin", "Stepniak", , "marcinstepniak@ucm.es", role = "aut",

R/frequencies_to_stop_times.R

@@ -12,6 +12,14 @@
 #'
 #' @family augment
 #' @export
+#'
+#' @examples
+#' \dontrun{
+#' # Presume an input feed has been created and includes a "frequencies" table:
+#' gtfs2 <- frequencies_to_stop_times (gtfs)
+#' # "gtfs2" will then have an expanded "stop_times" table, with all
+#' # "frequencies" entries converted to equivalent absolute stop times.
+#' }
 frequencies_to_stop_times <- function (gtfs) {
 
     # check if gtfs is a gtfs class of object

R/go_home_work.R

@@ -34,6 +34,9 @@
 #' largely unavoidable.
 #'
 #' @return A `data.frame` specifying the next available route from work to home.
+#' @family additional
+#' @export
+#'
 #' @examples
 #' \dontrun{
 #' # For general use, please set these three variables:
@@ -55,8 +58,6 @@
 #' go_home ()
 #' go_home (3)
 #' }
-#' @family additional
-#' @export
 go_home <- function (wait = 0, start_time) {
 
     go_home_work (home = TRUE, wait = wait, start_time)
@@ -72,6 +73,9 @@ go_home <- function (wait = 0, start_time) {
 #' @inherit go_home return details
 #'
 #' @return A `data.frame` specifying the next available route from work to home.
+#' @export
+#' @family additional
+#'
 #' @examples
 #' \dontrun{
 #' # For general use, please set these three variables:
@@ -93,8 +97,6 @@ go_home <- function (wait = 0, start_time) {
 #' go_to_work ()
 #' go_to_work (3)
 #' }
-#' @export
-#' @family additional
 go_to_work <- function (wait = 0, start_time) {
 
     go_home_work (home = FALSE, wait = wait, start_time)
@@ -178,6 +180,22 @@ get_rds_name <- function (f) {
 #'
 #' @family additional
 #' @export
+#'
+#' @examples
+#' \dontrun{
+#' # For general use, please set these three variables:
+#' Sys.setenv ("gtfs_home" = "<my home station>")
+#' Sys.setenv ("gtfs_work" = "<my work station>")
+#' Sys.setenv ("gtfs_data" = "/full/path/to/gtfs.zip")
+#'
+#' # The following illustrate use with sample data bundled with package
+#' Sys.setenv ("gtfs_home" = "Tempelhof")
+#' Sys.setenv ("gtfs_work" = "Alexanderplatz")
+#' Sys.setenv ("gtfs_data" = file.path (tempdir (), "vbb.zip"))
+#' process_gtfs_local ()
+#' # next available service from current system time:
+#' go_home ()
+#' }
 process_gtfs_local <- function (expand = 2) {
 
     vars <- get_envvars ()

R/route-headway.R

@@ -1,4 +1,3 @@
-
 headway_times <- function (gtfs, start_stns, end_stns, start_time) {
 
     from_to_are_ids <- include_ids <- FALSE # nolint
@@ -14,7 +13,11 @@ headway_times <- function (gtfs, start_stns, end_stns, start_time) {
         max_transfers
     )
 
-    return (range (route$time))
+    ret <- NULL
+    if (nrow (route) > 0L) {
+        ret <- range (route$time)
+    }
+    return (ret)
 }
 
 #' Route headway
@@ -28,13 +31,24 @@ headway_times <- function (gtfs, start_stns, end_stns, start_time) {
 #' services across a single 24-hour period
 #' @family main
 #' @export
+#'
+#' @examples
+#' \dontrun{
+#' path <- berlin_gtfs_to_zip ()
+#' gtfs <- extract_gtfs (path)
+#' gtfs_route_headway (gtfs, from = "Tegel", to = "Berlin Hauptbahnhof")
+#' }
 gtfs_route_headway <- function (gtfs, from, to,
                                 from_to_are_ids = FALSE,
                                 grep_fixed = TRUE,
                                 quiet = FALSE) {
 
     departure_time <- NULL # suppress no visible binding note # nolint
 
+    if (!"timetable" %in% names (gtfs)) {
+        gtfs <- gtfs_timetable (gtfs, quiet = quiet)
+    }
+
     start_stns <- from_to_to_stations (
         from,
         gtfs,
@@ -60,6 +74,9 @@ gtfs_route_headway <- function (gtfs, from, to,
         times <- headway_times (gtfs, start_stns, end_stns, start_time)
         heads <- rbind (heads, unname (times))
         start_time <- times [1] + 1
+        if (length (start_time) == 0) {
+            start_time <- 24 * 3600
+        }
         if (!quiet) {
             utils::setTxtProgressBar (pb, start_time / (24 * 3600))
         }

R/utils.R

@@ -6,6 +6,12 @@
 #' @return Path to newly created zip file
 #' @family extract
 #' @export
+#'
+#' @examples
+#' path <- berlin_gtfs_to_zip ()
+#' gtfs <- extract_gtfs (path)
+#' gtfs <- gtfs_timetable (gtfs, day = "Wed") # A pre-processing step to speed up queries
+#' gtfs_route (gtfs, from = "Tegel", to = "Berlin Hauptbahnhof", start_time = 12 * 3600)
 berlin_gtfs_to_zip <- function () {
     flist <- c (
         "calendar.txt",

codemeta.json

@@ -7,7 +7,7 @@
   "codeRepository": "https://github.com/UrbanAnalyst/gtfsrouter",
   "issueTracker": "https://github.com/UrbanAnalyst/gtfsrouter/issues",
   "license": "https://spdx.org/licenses/GPL-3.0",
-  "version": "0.1.2.020",
+  "version": "0.1.2.029",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",