updated tests

Author: ankoure

R/parameterized.R

@@ -54,17 +54,16 @@ tm_trip_metrics <- function(start_date, end_date, agg, line, base_url = tm_base_
 
 #' Get scheduled service data
 #'
-#' Returns scheduled service counts aggregated over a date range. Optionally
-#' filtered to a single route.
+#' Returns scheduled service counts aggregated over a date range for a single
+#' MBTA route.
 #'
 #' @inheritParams tm_line_delays
 #' @param agg Aggregation level, e.g. `"daily"` or `"weekly"`.
-#' @param route_id Optional MBTA route ID to filter results.
+#' @param route_id MBTA route ID, e.g. `"Red"`, `"Orange"`, `"Green-B"`.
 #' @return A list of scheduled service records.
 #' @export
 #' @examples
 #' \dontrun{
-#' tm_scheduled_service("2024-01-01", "2024-01-31", agg = "daily")
 #' tm_scheduled_service("2024-01-01", "2024-01-31", agg = "daily",
 #'                      route_id = "Red")
 #' }
@@ -137,29 +136,33 @@ tm_speed_restrictions <- function(line_id, on_date, base_url = tm_base_url()) {
 
 #' Get service hours data
 #'
-#' Returns total revenue service hours aggregated over a date range. Optionally
-#' filtered to a single route.
+#' Returns scheduled vs. delivered service hours aggregated over a date range
+#' for a single MBTA line.
 #'
-#' @inheritParams tm_line_delays
+#' @param start_date Start of the date range. A `Date` object or `"YYYY-MM-DD"`
+#'   string.
+#' @param end_date End of the date range. A `Date` object or `"YYYY-MM-DD"`
+#'   string.
 #' @param agg Aggregation level, e.g. `"daily"` or `"weekly"`.
-#' @param single_route_id Optional MBTA route ID to filter results.
+#' @param line_id MBTA line identifier, e.g. `"line-red"`.
+#' @param base_url Base URL of the TransitMatters API. Defaults to
+#'   `getOption("tm_dashboard_base_url")` or the production host.
 #' @return A list of service hours records.
 #' @export
 #' @examples
 #' \dontrun{
-#' tm_service_hours("2024-01-01", "2024-01-31", agg = "daily")
 #' tm_service_hours("2024-01-01", "2024-01-31", agg = "daily",
-#'                  single_route_id = "Red")
+#'                  line_id = "line-red")
 #' }
-tm_service_hours <- function(start_date, end_date, agg, single_route_id = NULL,
+tm_service_hours <- function(start_date, end_date, agg, line_id = NULL,
                              base_url = tm_base_url()) {
   tm_request(
     "api/service_hours",
     query = list(
-      start_date      = .tm_date(start_date),
-      end_date        = .tm_date(end_date),
-      agg             = agg,
-      single_route_id = single_route_id
+      start_date = .tm_date(start_date),
+      end_date   = .tm_date(end_date),
+      agg        = agg,
+      line_id    = if (!is.null(line_id)) tolower(.tm_gtfs_line_id(line_id))
     ),
     base_url = base_url
   )

tests/testthat/test-dated.R

@@ -1,32 +1,33 @@
-test_that("tm_headways returns headways field", {
+test_that("tm_headways returns a list", {
   httr2::local_mocked_responses(
-    function(req) mock_response('{"headways":{"Red":[]}}')
+    function(req) mock_response("[]")
   )
-  result <- tm_headways("2024-01-15")
-  expect_true("headways" %in% names(result))
+  result <- tm_headways("2024-01-15", stop = "70061")
+  expect_type(result, "list")
 })
 
 test_that("tm_headways accepts a Date object", {
   httr2::local_mocked_responses(
-    function(req) mock_response('{"headways":{}}')
+    function(req) mock_response("[]")
   )
-  expect_no_error(tm_headways(as.Date("2024-01-15")))
+  expect_no_error(tm_headways(as.Date("2024-01-15"), stop = "70061"))
 })
 
-test_that("tm_dwells returns dwells field", {
+test_that("tm_dwells returns a list", {
   httr2::local_mocked_responses(
-    function(req) mock_response('{"dwells":{"Red":[]}}')
+    function(req) mock_response("[]")
   )
-  result <- tm_dwells("2024-01-15")
-  expect_true("dwells" %in% names(result))
+  result <- tm_dwells("2024-01-15", stop = "70061")
+  expect_type(result, "list")
 })
 
-test_that("tm_travel_times returns travel_times field", {
+test_that("tm_travel_times returns a list", {
   httr2::local_mocked_responses(
-    function(req) mock_response('{"travel_times":{"Red":[]}}')
+    function(req) mock_response("[]")
   )
-  result <- tm_travel_times("2024-01-15")
-  expect_true("travel_times" %in% names(result))
+  result <- tm_travel_times("2024-01-15",
+    from_stop = "70076", to_stop = "70064")
+  expect_type(result, "list")
 })
 
 test_that("tm_alerts with no date hits undated endpoint", {
@@ -36,7 +37,7 @@ test_that("tm_alerts with no date hits undated endpoint", {
       mock_response('{"alerts":[]}')
     }
   )
-  result <- tm_alerts()
+  result <- tm_alerts(route = "Red")
   expect_true("alerts" %in% names(result))
 })
 
@@ -47,6 +48,6 @@ test_that("tm_alerts with a date hits dated endpoint", {
       mock_response('{"alerts":[]}')
     }
   )
-  result <- tm_alerts("2024-01-15")
+  result <- tm_alerts("2024-01-15", route = "Red")
   expect_true("alerts" %in% names(result))
 })

vignettes/getting-started.Rmd

@@ -132,6 +132,22 @@ trips <- tm_trip_metrics(
   agg        = "daily",
   line       = "line-red"
 )
+
+# How many trips were scheduled to run each day
+scheduled <- tm_scheduled_service(
+  start_date = "2024-01-01",
+  end_date   = "2024-01-31",
+  route_id    = "Red",
+  agg        = "daily"
+)
+
+# Total revenue service hours each day on the Red Line
+hours <- tm_service_hours(
+  start_date = "2024-01-01",
+  end_date   = "2024-01-31",
+  agg        = "daily",
+  line_id    = "Red"
+)
 ```
 
 **Available line IDs:**
@@ -144,7 +160,7 @@ trips <- tm_trip_metrics(
 | Green Line  | `"line-green"`      |
 | Commuter    | `"line-cr"`         |
 
-## Step 6: Turn the result into a data frame
+## Step 8: Turn the result into a data frame
 
 The API gives back a list, but most R analysis tools (like `ggplot2`) prefer a
 **data frame**. Here's the easiest way to convert:
@@ -167,7 +183,7 @@ head(ridership_df)
 > `do.call(rbind, lapply(ridership_raw, as.data.frame))` — it's a bit more
 > verbose but handles some tricky list shapes.
 
-## Step 7: Make a quick plot
+## Step 9: Make a quick plot
 
 Once you have a data frame you can plot with `ggplot2`:
 
@@ -190,11 +206,54 @@ ggplot(ridership_df, aes(x = as.Date(date), y = count)) +
   theme_minimal()
 ```
 
+## Step 7: Aggregate endpoints
+
+The aggregate endpoints return long-run averages rather than individual trip
+events — useful for trend analysis over weeks or months.
+
+```{r aggregate, eval = FALSE}
+# Average travel time from Park Street to Davis, by date
+travel_agg <- tm_aggregate_travel_times(
+  from_stop  = "70076",
+  to_stop    = "70064",
+  start_date = "2024-01-01",
+  end_date   = "2024-01-31"
+)
+
+# Same data via the v2 endpoint (returns by_date and by_time breakdowns)
+travel_agg2 <- tm_aggregate_travel_times2(
+  from_stop  = "70076",
+  to_stop    = "70064",
+  start_date = "2024-01-01",
+  end_date   = "2024-01-31"
+)
+
+# Average headways at a stop over a date range
+headways_agg <- tm_aggregate_headways(
+  stop       = "70061",
+  start_date = "2024-01-01",
+  end_date   = "2024-01-31"
+)
+
+# Average dwell times at a stop over a date range
+dwells_agg <- tm_aggregate_dwells(
+  stop       = "70061",
+  start_date = "2024-01-01",
+  end_date   = "2024-01-31"
+)
+```
+
+> **Tip:** The v2 travel times endpoint (`tm_aggregate_travel_times2`) is used
+> in the Red Line Analysis vignette for a worked plotting example.
+
 ## Recap: the functions at a glance
 
 | Function | What it returns | Needs |
 |---|---|---|
 | `tm_healthcheck()` | API status | nothing |
+| `tm_git_id()` | Server git commit SHA | nothing |
+| `tm_time_predictions()` | Live time predictions | nothing |
+| `tm_service_ridership_dashboard()` | System-wide ridership summary | nothing |
 | `tm_facilities()` | All MBTA stations | nothing |
 | `tm_routes()` | All available routes by mode | nothing |
 | `tm_stops(route_id)` | Stop IDs for a route | route ID |
@@ -205,9 +264,13 @@ ggplot(ridership_df, aes(x = as.Date(date), y = count)) +
 | `tm_ridership(start, end)` | Ridership counts | date range |
 | `tm_trip_metrics(start, end, agg, line)` | Trip performance | date range + line |
 | `tm_line_delays(start, end, line)` | Delay summaries | date range + line |
+| `tm_scheduled_service(start, end, agg)` | Scheduled trip counts | date range + agg |
+| `tm_service_hours(start, end, agg, line_id)` | Revenue service hours | date range + agg + line |
 | `tm_speed_restrictions(line_id, date)` | Slow zones | line + date |
 | `tm_aggregate_travel_times(...)` | Long-run travel time trends | stop pair + range |
+| `tm_aggregate_travel_times2(...)` | Long-run travel times (v2, with by_date/by_time) | stop pair + range |
 | `tm_aggregate_headways(...)` | Long-run headway trends | stop + range |
+| `tm_aggregate_dwells(...)` | Long-run dwell time trends | stop + range |
 
 Next, check out the **Red Line Analysis** vignette for a full worked example
 that goes from raw API data to a polished chart.