better intro vignette

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: gtfsio
 Title: Read and Write General Transit Feed Specification (GTFS) Files
-Version: 0.0.0.9035
+Version: 0.0.0.9036
 Authors@R: 
     c(person(given = "Daniel",
              family = "Herszenhut",
@@ -27,10 +27,13 @@ Authors@R:
              email = "[email protected]"),
       person(given = "Ipea - Institute for Applied Economic Research",
              role = c("cph", "fnd")))
-Description: Tools for the development of packages that interact with
-    General Transit Feed Specification (GTFS) files. Defines a 'gtfs'
-    class to represent GTFS files and provides fast and flexible functions
-    to read, write and check such files.
+Description: Tools for the development of packages related to General
+    Transit Feed Specification (GTFS) files. Establishes a standard for
+    representing GTFS feeds using R data types. Provides fast and flexible
+    functions to read and write GTFS feeds while sticking to this
+    standard. Defines a basic 'gtfs' class which is meant to be extended
+    by packages that depend on it. And offers utility functions that
+    support checking the structure of GTFS objects.
 License: MIT + file LICENSE
 URL: https://github.com/r-transit/gtfsio
 BugReports: https://github.com/r-transit/gtfsio/issues

R/gtfsio.R

@@ -1,7 +1,11 @@
 #' gtfsio: Read and Write General Transit Feed Specification (GTFS) Data
 #'
-#' Provides a \code{gtfs} class to represent General Transit Feed Specification
-#' (GTFS) files, and fast and flexible tools to read and write such files.
+#' Tools for the development of GTFS-related packages. Establishes a standard
+#' for representing GTFS feeds using R data types. Provides fast and flexible
+#' functions to read and write GTFS feeds while sticking to this standard.
+#' Defines a basic \code{gtfs} class which is meant to be extended by packages
+#' that depend on it. And offers utility functions that support checking the
+#' structure of GTFS objects.
 #'
 #' @docType package
 #' @name gtfsio

README.Rmd

@@ -18,18 +18,57 @@ knitr::opts_chunk$set(
 [![Codecov test coverage](https://codecov.io/gh/r-transit/gtfsio/branch/master/graph/badge.svg)](https://codecov.io/gh/r-transit/gtfsio?branch=master)
 [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html)
 
-**gtfsio** is a package focused towards package development. It offers tools to read and write transit feeds in the General Transit Feed Specification (GTFS) format according to [Google's Static GTFS Reference](https://developers.google.com/transit/gtfs/reference). It also defines a `gtfs` class, providing relevant methods, which is meant to be extended by packages which depend on it.
+**gtfsio** offers tools for the development of GTFS-related packages. It establishes a standard for representing GTFS feeds using R data types based on [Google's Static GTFS Reference](https://developers.google.com/transit/gtfs/reference). It provides fast and flexible functions to read and write GTFS feeds while sticking to this standard. It defines a basic `gtfs` class which is meant to be extended by packages that depend on it. And it also offers utility functions that support checking the structure of GTFS objects.
 
 ## Installation
 
+Stable version:
+
+```{r, eval = FALSE}
+# soon on CRAN
+# install.packages("gtfsio")
+```
+
 Development version:
 
 ```{r, eval = FALSE}
 # install.packages("remotes")
 remotes::install_github("r-transit/gtfsio")
 ```
 
-## Related packages
+## Usage
+
+GTFS feeds are read using the `import_gtfs()` function:
+
+```{r}
+library(gtfsio)
+
+path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio")
+
+gtfs <- import_gtfs(path)
+
+names(gtfs)
+```
+
+`import_gtfs()` returns a `gtfs` object. The `gtfs` class might be extended by other packages using the constructor, validator and methods provided by **gtfsio**:
+
+```{r}
+class(gtfs)
+```
+
+Use the `export_gtfs()` function to write GTFS objects to disk:
+
+```{r}
+tmpf <- tempfile(fileext = ".zip")
+
+export_gtfs(gtfs, tmpf)
+
+zip::zip_list(tmpf)$filename
+```
+
+For a more complete demonstration please read the [introductory vignette](https://r-transit.github.io/gtfsio/articles/gtfsio.html).
+
+## GTFS-related packages
 
 - [`{tidytransit}`](https://github.com/r-transit/tidytransit)
 - [`{gtfs2gps}`](https://github.com/ipeaGIT/gtfs2gps)

README.md

@@ -10,23 +10,79 @@ coverage](https://codecov.io/gh/r-transit/gtfsio/branch/master/graph/badge.svg)]
 [![Lifecycle:
 experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html)
 
-**gtfsio** is a package focused towards package development. It offers
-tools to read and write transit feeds in the General Transit Feed
-Specification (GTFS) format according to [Google’s Static GTFS
+**gtfsio** offers tools for the development of GTFS-related packages. It
+establishes a standard for representing GTFS feeds using R data types
+based on [Google’s Static GTFS
 Reference](https://developers.google.com/transit/gtfs/reference). It
-also defines a `gtfs` class, providing relevant methods, which is meant
-to be extended by packages which depend on it.
+provides fast and flexible functions to read and write GTFS feeds while
+sticking to this standard. It defines a basic `gtfs` class which is
+meant to be extended by packages that depend on it. And it also offers
+utility functions that support checking the structure of GTFS objects.
 
 ## Installation
 
+Stable version:
+
+``` r
+# soon on CRAN
+# install.packages("gtfsio")
+```
+
 Development version:
 
 ``` r
 # install.packages("remotes")
 remotes::install_github("r-transit/gtfsio")
 ```
 
-## Related packages
+## Usage
+
+GTFS feeds are read using the `import_gtfs()` function:
+
+``` r
+library(gtfsio)
+
+path <- system.file("extdata/ggl_gtfs.zip", package = "gtfsio")
+
+gtfs <- import_gtfs(path)
+
+names(gtfs)
+#>  [1] "calendar_dates"  "fare_attributes" "fare_rules"      "feed_info"      
+#>  [5] "frequencies"     "levels"          "pathways"        "routes"         
+#>  [9] "shapes"          "stop_times"      "stops"           "transfers"      
+#> [13] "translations"    "trips"           "agency"          "attributions"   
+#> [17] "calendar"
+```
+
+`import_gtfs()` returns a `gtfs` object. The `gtfs` class might be
+extended by other packages using the constructor, validator and methods
+provided by **gtfsio**:
+
+``` r
+class(gtfs)
+#> [1] "gtfs"
+```
+
+Use the `export_gtfs()` function to write GTFS objects to disk:
+
+``` r
+tmpf <- tempfile(fileext = ".zip")
+
+export_gtfs(gtfs, tmpf)
+
+zip::zip_list(tmpf)$filename
+#>  [1] "calendar_dates.txt"  "fare_attributes.txt" "fare_rules.txt"     
+#>  [4] "feed_info.txt"       "frequencies.txt"     "levels.txt"         
+#>  [7] "pathways.txt"        "routes.txt"          "shapes.txt"         
+#> [10] "stop_times.txt"      "stops.txt"           "transfers.txt"      
+#> [13] "translations.txt"    "trips.txt"           "agency.txt"         
+#> [16] "attributions.txt"    "calendar.txt"
+```
+
+For a more complete demonstration please read the [introductory
+vignette](https://r-transit.github.io/gtfsio/articles/gtfsio.html).
+
+## GTFS-related packages
 
 -   [`{tidytransit}`](https://github.com/r-transit/tidytransit)
 -   [`{gtfs2gps}`](https://github.com/ipeaGIT/gtfs2gps)

codemeta.json

@@ -5,12 +5,12 @@
   ],
   "@type": "SoftwareSourceCode",
   "identifier": "gtfsio",
-  "description": "Tools for the development of packages that interact with\n    General Transit Feed Specification (GTFS) files. Defines a 'gtfs'\n    class to represent GTFS files and provides fast and flexible functions\n    to read, write and check such files.",
+  "description": "Tools for the development of packages related to General\n    Transit Feed Specification (GTFS) files. Establishes a standard for\n    representing GTFS feeds using R data types. Provides fast and flexible\n    functions to read and write GTFS feeds while sticking to this\n    standard. Defines a basic 'gtfs' class which is meant to be extended\n    by packages that depend on it. And offers utility functions that\n    support checking the structure of GTFS objects.",
   "name": "gtfsio: Read and Write General Transit Feed Specification (GTFS) Files",
   "codeRepository": "https://github.com/r-transit/gtfsio",
   "issueTracker": "https://github.com/r-transit/gtfsio/issues",
   "license": "https://spdx.org/licenses/MIT",
-  "version": "0.0.0.9035",
+  "version": "0.0.0.9036",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",
@@ -143,7 +143,7 @@
       "sameAs": "https://CRAN.R-project.org/package=zip"
     }
   ],
-  "fileSize": "117.81KB",
+  "fileSize": "124.038KB",
   "keywords": [
     "r",
     "gtfs"

vignettes/gtfsio.Rmd

@@ -18,12 +18,9 @@ The General Transit Feed Specification (GTFS) data format defines a common schem
 
 Each one of these, however, represent GTFS feeds in a slightly different way, making the interoperability between packages harder to accomplish. At the end of the day, this lack of integration results in a more painful experience to the final user who may want to enjoy functions from different packages.
 
-**gtfsio** offers tools for the development of GTFS-related packages that aim to increase such interoperability. It establishes a standard for representing GTFS feeds using R data types. It provides fast and flexible functions to read and write GTFS feeds while sticking to this standard. It defines a basic `gtfs` class which is meant to be extended by packages that depend on it. And it also offers utility functions that support checking the structure of GTFS objects.
+**gtfsio** offers tools for the development of GTFS-related packages that aim to increase such interoperability. It establishes a standard for representing GTFS feeds using R data types based on [Google's Static GTFS Reference](https://developers.google.com/transit/gtfs/reference). It provides fast and flexible functions to read and write GTFS feeds while sticking to this standard. It defines a basic `gtfs` class which is meant to be extended by packages that depend on it. And it also offers utility functions that support checking the structure of GTFS objects.
 
-This vignette describes the usage of the GTFS reading and writing functions. Please follow the links below for vignettes covering other topics:
-
-- other
-- vignettes
+This vignette describes the basic usage of **gtfsio**. Please read `get_gtfs_standards()` documentation for more detail on the standards for reading and writing GTFS feeds using R data types.
 
 # Installation 
 
@@ -53,7 +50,9 @@ list.files(data_dir)
 - `ggl_gtfs.zip` has been manually built from the [example GTFS feed](https://developers.google.com/transit/gtfs/examples/gtfs-feed) provided by Google. The files samples are licensed under [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/).
 - `bad_gtfs.zip` is a modified version of `ggl_gtfs.zip` that includes some issues frequently found in GTFS data.
 
-# Reading feeds
+# Basic usage
+
+## Reading feeds
 
 To read a feed use the `import_gtfs()` function. It takes either a local path or an URL to a GTFS `.zip` file and returns a GTFS object (which is, basically, a `list` of data frames):
 
@@ -108,7 +107,7 @@ gtfs$levels
 class(gtfs$levels$elevation)
 ```
 
-# Writing feeds
+## Writing feeds
 
 Use `export_gtfs()` to write a GTFS object to disk. Please note that the function assumes that the object is formatted according to the standards for reading and writing GTFS feeds in **R** - i.e. if it's not, any conversions should be done before using `export_gtfs()`.
 
@@ -146,3 +145,57 @@ export_gtfs(extra_gtfs, tmpd, as_dir = TRUE, standard_only = TRUE)
 levels_fields <- readLines(file.path(tmpd, "levels.txt"), n = 1L)
 grepl("elevation", levels_fields)
 ```
+
+## Checking GTFS objects
+
+**gtfsio** also includes functions to check the structure of GTFS objects. `check_files_exist()` checks the existence of elements representing specific text files inside an object. It returns `TRUE` if the check is successful, and `FALSE` otherwise. `assert_files_exist()` invisibly returns the object if successful, and throws an error otherwise:
+
+```{r, error = TRUE}
+gtfs <- import_gtfs(gtfs_path, files = c("shapes", "trips"))
+
+check_files_exist(gtfs, "shapes")
+check_files_exist(gtfs, "stop_times")
+
+assert_files_exist(gtfs, "shapes")
+assert_files_exist(gtfs, "stop_times")
+```
+
+`check_fields_exist()` checks the existence of fields, represented by columns, inside GTFS objects. It returns `TRUE` if the check is successful, and `FALSE` otherwise. `assert_fields_exist()` invisibly returns the object if successful, and throws an error otherwise:
+
+```{r, error = TRUE}
+gtfs <- import_gtfs(
+  gtfs_path, 
+  files = "trips", 
+  fields = list(trips = "trip_id")
+)
+
+check_fields_exist(gtfs, "trips", fields = "trip_id")
+check_fields_exist(gtfs, "trips", fields = "shape_id")
+
+assert_fields_exist(gtfs, "trips", fields = "trip_id")
+assert_fields_exist(gtfs, "trips", fields = "shape_id")
+```
+
+`check_fields_types()` checks the types of fields inside GTFS objects. It returns `TRUE` if the check is successful, and `FALSE` otherwise. `assert_fields_types()` invisibly returns the object if successful, and throws an error otherwise:
+
+```{r, error = TRUE}
+gtfs <- import_gtfs(gtfs_path, files = "levels")
+
+check_fields_types(gtfs, "levels", fields = "elevation", types = "character")
+check_fields_types(gtfs, "levels", fields = "elevation", types = "integer")
+
+assert_fields_types(gtfs, "levels", fields = "elevation", types = "character")
+assert_fields_types(gtfs, "levels", fields = "elevation", types = "integer")
+```
+
+Please notes that "lower-level" checks are conducted inside each function - e.g. before checking the type of a field, first the existence of such field is checked:
+
+```{r, error = TRUE}
+gtfs <- import_gtfs(gtfs_path, files = "shapes")
+
+check_fields_types(gtfs, "stop_times", fields = "stop_id", types = "character")
+```
+
+These functions are great for package interoperability. If two distinct packages represent GTFS text files using the same data structure (both `{gtfstools}` and `{gtfsrouter}` use `data.table`s, for example), they just need to add some basic checks before proceeding with operations on objects created by the other package.
+
+So, if `{gtfsrouter}` requires the `transfers` element to perform some operations, it might as well perform them on an object created by `{gtfstools}`, as long as it contains a `transfers` element. Thus, it could greatly benefit of some `assert_*`/`check_*` calls before proceeding with such operations.