Checking for bad or inappropriate `event` values

[wibeasley]

when a bad/nonexistent event is passed, the columns get shuffled for REDCapR::redcap_read() but not for REDCapR::redcap_read_oneshot(). These projects aren't longitudinal, so I guess the filtering code on the server never runs for events.

This is returned by the playground for just the "blood_pressure" form. I can't enter a bad event.

sbp,dbp,blood_pressure_complete
1.1,11.1,2
1.2,11.2,2
1.3,11.3,2
2.1,22.1,2
2.2,22.2,2
2.3,22.3,2

This is the raw csv returned by the API with the bad event. Notice the server is changing the column order:

blood_pressure_complete,dbp,sbp
2,11.1,1.1
2,11.2,1.2
2,11.3,1.3
2,22.1,2.1
2,22.2,2.2
2,22.3,2.3

uri      <- "https://bbmc.ouhsc.edu/redcap/api/"
token    <- "22C3FF1C8B08899FB6F86D91D874A159" # pid 3181

REDCapR::redcap_read_oneshot(
  redcap_uri  = uri, 
  token       = token,
  forms       = "blood_pressure",
  # events      = "bad-event",
  verbose     = FALSE 
)$data
#> # A tibble: 6 × 3
#>     sbp   dbp blood_pressure_complete
#>   <dbl> <dbl>                   <dbl>
#> 1   1.1  11.1                       2
#> 2   1.2  11.2                       2
#> 3   1.3  11.3                       2
#> 4   2.1  22.1                       2
#> 5   2.2  22.2                       2
#> 6   2.3  22.3                       2

REDCapR::redcap_read_oneshot(
  redcap_uri  = uri, 
  token       = token,
  forms       = "blood_pressure",
  events      = "bad-event",
  verbose     = FALSE 
)$data
#> # A tibble: 6 × 3
#>   blood_pressure_complete   dbp   sbp
#>                     <dbl> <dbl> <dbl>
#> 1                       2  11.1   1.1
#> 2                       2  11.2   1.2
#> 3                       2  11.3   1.3
#> 4                       2  22.1   2.1
#> 5                       2  22.2   2.2
#> 6                       2  22.3   2.3

REDCapR::redcap_read(
  redcap_uri  = uri, 
  token       = token,
  forms       = "blood_pressure",
  # events      = "bad-event",
  verbose     = FALSE 
)$data
#> # A tibble: 8 × 6
#>   record_id redcap_repeat_instrument redcap_repeat_instance   sbp   dbp
#>       <dbl> <chr>                                     <dbl> <dbl> <dbl>
#> 1         1 <NA>                                         NA  NA    NA  
#> 2         1 blood_pressure                                1   1.1  11.1
#> 3         1 blood_pressure                                2   1.2  11.2
#> 4         1 blood_pressure                                3   1.3  11.3
#> 5         2 <NA>                                         NA  NA    NA  
#> 6         2 blood_pressure                                1   2.1  22.1
#> 7         2 blood_pressure                                2   2.2  22.2
#> 8         2 blood_pressure                                3   2.3  22.3
#> # ℹ 1 more variable: blood_pressure_complete <dbl>

REDCapR::redcap_read(
  redcap_uri  = uri, 
  token       = token,
  forms       = "blood_pressure",
  events      = "bad-event",
  verbose     = FALSE 
)$data
#> # A tibble: 8 × 3
#>   record_id redcap_repeat_instrument redcap_repeat_instance
#>       <dbl>                    <dbl>                  <dbl>
#> 1         1                     NA                     NA  
#> 2         2                     11.1                    1.1
#> 3         2                     11.2                    1.2
#> 4         2                     11.3                    1.3
#> 5         2                     NA                     NA  
#> 6         2                     22.1                    2.1
#> 7         2                     22.2                    2.2
#> 8         2                     22.3                    2.3

^{Created on 2023-07-09 with reprex v2.0.2}

[wibeasley]

For redcap_read_oneshot(), I'll won't interfere. The behavior is acceptable. However for redcap_read() (which is what I push people to use by default), I'll throw an error if it's not a longitudinal project, or if the event name isn't recognized.

Tell me if someone has a better error message than these.

Error if non-longitudinal:

Error: This project is NOT longitudinal, so do not pass a value to the `event` argument.

Error if bad event names are passed:

Error: The following events are not recognized for this project: {bad_event_1, bad_event_2}.
Make sure you're using internal `event-name` (lowercase letters & underscores)
instead of the user-facing `event-label` (that can have spaces and uppercase letters).