Fix spelling errors and improve documentation

ITSLeeds · Jul 16, 2023 · 5bfc67a · 5bfc67a
1 parent 6c6b887
commit 5bfc67a
Show file tree

Hide file tree

Showing 16 changed files with 89 additions and 55 deletions.
diff --git a/R/atoc.R b/R/atoc.R
@@ -3,15 +3,15 @@
 #' Convert ATOC CIF files to GTFS
 #'
 #' @param path_in Character, path to ATOC file e.g."C:/input/ttis123.zip"
-#' @param silent Logical, should progress messages be surpressed (default TRUE)
+#' @param silent Logical, should progress messages be suppressed (default TRUE)
 #' @param ncores Numeric, When parallel processing how many cores to use
 #'   (default 1)
 #' @param locations where to get tiploc locations (see details)
 #' @param agency where to get agency.txt (see details)
 #' @param shapes Logical, should shapes.txt be generated (default FALSE)
 #' @param transfers Logical, should transfers.txt be generated (default TRUE)
 #' @param missing_tiplocs Logical, if locations = tiplocs, then will check for
-#'   any missing tiplocs agains the main file and add them.(default TRUE)
+#'   any missing tiplocs against the main file and add them.(default TRUE)
 #' @family main
 #'
 #' @details Locations

diff --git a/R/gtfs_cleaning.R b/R/gtfs_cleaning.R
@@ -4,6 +4,9 @@
 #'
 #' @param gtfs gtfs list
 #' @param trip_ids a vector of trips ids
+#' @return Returns a named list of two gtfs objects. The `true` list contains
+#'   trips that matched `trip_ids` the `false` list contains all other trips.
+#'
 #' @export
 
 gtfs_split_ids <- function(gtfs, trip_ids) {
@@ -194,6 +197,14 @@ gtfs_fast_stops <- function(gtfs, maxspeed = 83) {
 #' Clean simple errors from GTFS files
 #'
 #' @param gtfs gtfs list
+#' @details
+#' Task done:
+#'
+#' 1. Remove stops with no location information
+#' 2. Remove stops that are never used
+#' 3. Replace missing agency names with "MISSINGAGENCY"
+#'
+#'
 #' @export
 gtfs_clean <- function(gtfs) {
   # 1 Remove stops with no locations

diff --git a/R/gtfs_compress.R b/R/gtfs_compress.R
@@ -2,10 +2,10 @@
 #'
 #' @param gtfs a gtfs object
 #' @return a gtfs object
-#' @details by default UK2GTFS trys to preserve id numbers during the conversion
-#'   process to allow back comparions to the original files, e.g.
+#' @details by default UK2GTFS tries to preserve id numbers during the conversion
+#'   process to allow back comparisons to the original files, e.g.
 #'   `transxchange2gtfs()` retains stop ids from the NAPTAN. However this means
-#'   files sizes are increased. This fucntion replaces ids with intergers and
+#'   files sizes are increased. This function replaces ids with integers and
 #'   thus reduces the size of the gtfs file.
 #'
 #' @export

diff --git a/R/gtfs_split.R b/R/gtfs_split.R
@@ -1,8 +1,8 @@
 #' Split a GTFS object
 #'
-#' For large regions GTFS fiels can get very big. THis fucntion splits a GTFS
+#' For large regions GTFS files can get very big. This function splits a GTFS
 #' object into a list of GTFS objects. It tries to balance the sizes of the
-#' objects. Splits are made by agency_id so maximumd number of splits equalts
+#' objects. Splits are made by agency_id so maximums number of splits equals
 #' the number of unique agency_ids.
 #'
 #' @param gtfs a gtfs object

diff --git a/R/gtfs_subset.R b/R/gtfs_subset.R
@@ -1,11 +1,11 @@
 #' Clip a GTFS object to a geographical area
 #'
 #' Clips the GTFS file to only include stops within the bounds object, trips
-#' that cross the bouundary of the the object are truncated. Any trips that stop
-#' only once in the bounds are removed completly.
+#' that cross the boundary of the the object are truncated. Any trips that stop
+#' only once in the bounds are removed completely.
 #'
 #' @param gtfs a gtfs object
-#' @param bounds an sf data frame of polygons or multipolygons with CRS 4326
+#' @param bounds an sf data frame of polygons or multi-polygons with CRS 4326
 #' @export
 gtfs_clip <- function(gtfs, bounds) {
 

diff --git a/R/gtfs_validate.R b/R/gtfs_validate.R
@@ -217,8 +217,14 @@ gtfs_validate_external <- function(path_gtfs, path_validator) {
 }
 
 
-#' Force a GTFS to be valid bu removing problems
+#' Force a GTFS to be valid by removing problems
 #' @param gtfs gtfs object
+#' @details
+#' Actions performed
+#' 1. Remove stops with missing location
+#' 2. Remove stops from stop_times that are not in stops
+#' 3. Remove trips from stop_times that are not in trips
+#'
 #' @export
 gtfs_force_valid <- function(gtfs) {
   message("This function does not fix problems it just removes them")

diff --git a/README.Rmd b/README.Rmd
@@ -18,34 +18,33 @@ knitr::opts_chunk$set(
 
 
 
-UK2GTFS is an R package to convert train, tram, bus, and metro timetable data from the unfriendly and difficult to use formats used in the UK to the easy to use [GTFS](https://developers.google.com/transit/gtfs/) format. The main purpose of developing the package is to support using [OpenTripPlanner](https://github.com/ropensci/opentripplanner) in the UK.
+UK2GTFS is an R package to convert and work with train, tram, bus, ferry, and metro timetable data from the unfriendly and difficult to use formats used in the UK to the easy to use [GTFS](https://developers.google.com/transit/gtfs/) format. The main purpose of developing the package is to support using [OpenTripPlanner](https://github.com/ropensci/opentripplanner) in the UK.
 
 **Example results are published as [GitHub releases](https://github.com/ITSLeeds/UK2GTFS/releases) these come with no guarantee of quality.**
 
 ## Introduction
 
-The UK has two main sources of public transport timetable data [**traveline**](https://www.travelinedata.org.uk/) publishes data on buses and light rail and [**ATOC**](http://data.atoc.org/rail-industry-data) publishes data on heavy rail. Each uses a data format that is unique to that organisation and both formats are old and difficult to use.  Many countries have adopted the [GTFS](https://developers.google.com/transit/gtfs/) format which was developed by Google as a simple standard for publishing timetable data. Due to the wide-spread adoption of GTFS many useful tools have been developed that accept GTFS files as inputs. This package is intended to make the conversion of UK data to the GTFS format simple and easy.
+The UK has two main sources of public transport timetable data [**Traveline**](https://www.travelinedata.org.uk/) publishes data on buses and light rail and [**ATOC**](http://data.atoc.org/rail-industry-data) publishes data on heavy rail. Each uses a data format that is unique to that organisation and both formats are old and difficult to use.  Many countries have adopted the [GTFS](https://developers.google.com/transit/gtfs/) format which was developed by Google as a simple standard for publishing timetable data. Due to the wide-spread adoption of GTFS many useful tools have been developed that accept GTFS files as inputs. This package is intended to make the conversion of UK data to the GTFS format simple and easy.
 
 **Update November 2020**
 
-The [Open Bus Data Service](https://data.bus-data.dft.gov.uk/downloads/) Now offers a national GTFS download option based on [ITO World's](https://www.itoworld.com) TransXchange to GTFS converter.
+The [Open Bus Data Service](https://data.bus-data.dft.gov.uk/downloads/) now offers a national GTFS download option based on [ITO World's](https://www.itoworld.com) TransXchange to GTFS converter. For non-expert users it will probably be easier to download there files. However this packages is still being maintained to support conversion of historical files, and because the conversion of TransXchange to GTFS is open to interpretation and having alternative converters is useful.
 
 ## Capabilities - why we need another package
 
 There are a number of pre-existing options for converting data to GTFS. This package aims to go beyond basic conversion by providing a range of additional functionality:
 
 1. Data conversion
     + Conversion of TransXchange to GTFS
-    + Conversion of ATOC CIF files to GTFS
+    + Conversion of CIF files to GTFS
     + reading of TransXchange and CIF files is also supported, although some parts which are not required for GTFS conversion are only partially supported.
 1. Data cleaning, the raw data often contains clear errors, the package does not blindly convert but also corrects some known errors
-    + Improved locations of tiplocs - used to locate feature on the heavy rail network
+    + Improved locations of tiplocs - used to locate features on the heavy rail network
     + Add bus stops missing in the NAPTAN
     + Correction of spelling errors
     + Removal of on-demand bus services (GTFS does not support services that are on-demand)
 1. Data polishing
     + Support of journeys past midnight
-    + Routing of train journeys along tracks rather than straight lines between stops (work in progress)
 1. GTFS tools, functions for working with GTFS data
     + Reading / Writing
     + Cleaning

diff --git a/README.md b/README.md
@@ -3,10 +3,11 @@
 
 # UK2GTFS <a href='https://itsleeds.github.io/'><img src='man/figures/logo.png' align="right" height=215/></a>
 
-UK2GTFS is an R package to convert train, tram, bus, and metro timetable
-data from the unfriendly and difficult to use formats used in the UK to
-the easy to use [GTFS](https://developers.google.com/transit/gtfs/)
-format. The main purpose of developing the package is to support using
+UK2GTFS is an R package to convert and work with train, tram, bus,
+ferry, and metro timetable data from the unfriendly and difficult to use
+formats used in the UK to the easy to use
+[GTFS](https://developers.google.com/transit/gtfs/) format. The main
+purpose of developing the package is to support using
 [OpenTripPlanner](https://github.com/ropensci/opentripplanner) in the
 UK.
 
@@ -17,7 +18,7 @@ no guarantee of quality.**
 ## Introduction
 
 The UK has two main sources of public transport timetable data
-[**traveline**](https://www.travelinedata.org.uk/) publishes data on
+[**Traveline**](https://www.travelinedata.org.uk/) publishes data on
 buses and light rail and
 [**ATOC**](http://data.atoc.org/rail-industry-data) publishes data on
 heavy rail. Each uses a data format that is unique to that organisation
@@ -32,8 +33,12 @@ and easy.
 **Update November 2020**
 
 The [Open Bus Data Service](https://data.bus-data.dft.gov.uk/downloads/)
-Now offers a national GTFS download option based on [ITO
-World’s](https://www.itoworld.com) TransXchange to GTFS converter.
+now offers a national GTFS download option based on [ITO
+World’s](https://www.itoworld.com) TransXchange to GTFS converter. For
+non-expert users it will probably be easier to download there files.
+However this packages is still being maintained to support conversion of
+historical files, and because the conversion of TransXchange to GTFS is
+open to interpretation and having alternative converters is useful.
 
 ## Capabilities - why we need another package
 
@@ -42,29 +47,27 @@ This package aims to go beyond basic conversion by providing a range of
 additional functionality:
 
 1.  Data conversion
-      - Conversion of TransXchange to GTFS
-      - Conversion of ATOC CIF files to GTFS
-      - reading of TransXchange and CIF files is also supported,
+    -   Conversion of TransXchange to GTFS
+    -   Conversion of CIF files to GTFS
+    -   reading of TransXchange and CIF files is also supported,
         although some parts which are not required for GTFS conversion
         are only partially supported.
 2.  Data cleaning, the raw data often contains clear errors, the package
     does not blindly convert but also corrects some known errors
-      - Improved locations of tiplocs - used to locate feature on the
+    -   Improved locations of tiplocs - used to locate features on the
         heavy rail network
-      - Add bus stops missing in the NAPTAN
-      - Correction of spelling errors
-      - Removal of on-demand bus services (GTFS does not support
+    -   Add bus stops missing in the NAPTAN
+    -   Correction of spelling errors
+    -   Removal of on-demand bus services (GTFS does not support
         services that are on-demand)
 3.  Data polishing
-      - Support of journeys past midnight
-      - Routing of train journeys along tracks rather than straight
-        lines between stops (work in progress)
+    -   Support of journeys past midnight
 4.  GTFS tools, functions for working with GTFS data
-      - Reading / Writing
-      - Cleaning
-      - Compression
-      - Validation
-      - Subsetting
+    -   Reading / Writing
+    -   Cleaning
+    -   Compression
+    -   Validation
+    -   Subsetting
 
 ## Installation
 

diff --git a/man/atoc2gtfs.Rd b/man/atoc2gtfs.Rd
diff --git a/man/gtfs_clean.Rd b/man/gtfs_clean.Rd
diff --git a/man/gtfs_clip.Rd b/man/gtfs_clip.Rd
diff --git a/man/gtfs_compress.Rd b/man/gtfs_compress.Rd
diff --git a/man/gtfs_force_valid.Rd b/man/gtfs_force_valid.Rd
diff --git a/man/gtfs_split.Rd b/man/gtfs_split.Rd
diff --git a/man/gtfs_split_ids.Rd b/man/gtfs_split_ids.Rd
diff --git a/vignettes/GTFS.Rmd b/vignettes/GTFS.Rmd
@@ -18,9 +18,9 @@ As well as converting to GTFS `UK2GTFS` has functions for manipulating GTFS file
 
 ## Reading and Writing
 
-`gtfs_read`
+`gtfs_read()`
 
-`gtfs_write`
+`gtfs_write()`
 
 
 ## Cleaning and Validating GFTS
@@ -31,8 +31,6 @@ As well as converting to GTFS `UK2GTFS` has functions for manipulating GTFS file
 
 `gtfs_fast_trips()` Find fast trips
 
-
-
 `gtfs_validate_internal()` Validate a GTFS object (in R)
 
 ## Manupulating GTFS