Helper Functions • smartabaseR

If you haven’t already, please read the vignette("get-started") before preceding.

smartabaseR contains several helper functions that are called from other exported functions. The two main ones are sb_get_user() and sb_get_group().

sb_get_user()

sb_get_user() leverages the Smartabase API to get user data out of Smartabase and into your R session. User data includes identifying information like user ID, about, first/last name, username and email. If the include_all_cols option is to TRUE, extra user information is included like phone numbers, addresses, UUIDs and groups/roles information.

Furthermore, you can filter for certain users via the user_key and user_value filters. Note: if these arguments are left empty, then all data for every user you have access to will be returned.

Why is sb_get_user() useful? Recall that the Smartabase API requires athletes’ user IDs when importing into Smartabase with sb_insert_event() etc. (see vignette("importing-data")). sb_get_user() is just one way to find your athletes’ user IDs for use with sb_insert_event() and the rest of the import functions.

filter

user_key/user_value

user_key and user_value allow you to get user data for specific Smartabase users.

user_key represents the user identification method: “about”, “user_id”, “username” or “email”.

about

All filter values must be generated by the relevant helper function. So, if we’re using sb_get_user() to export user data only for the athlete Jamie Anderson, we would need to use sb_get_user_filter() along with the user_key and user_value options:

sb_get_user(
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_user_filter(
    user_key = "about",
    user_value = "Jamie Anderson"
  )
)

If user_key = "about", data_value accepts full names.

See vignette("exporting-data") for a breakdown of the other possible user_key arguments.

option

include_all_cols

By default, sb_get_user() returns user_id, first_name, last_name, username and email, for each user. However, if we set include_all_cols to TRUE within sb_get_user_option(), then dob, middle_name, known_as, sex, phone and address is also returned.

Note: phone and address are returned as lists of tibbles.

Note #2: if only a single athlete is returned in the payload, then group and role columns (lists of tibbles) are also returned.

user_data <- sb_get_user(
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_user_option(
    include_all_cols = TRUE
  )
)
user_data

#> # A tibble: 1 × 15
#>   user_id about   first_name last_name username email dob   middle_name known_as
#>     <dbl> <chr>   <chr>      <chr>     <chr>    <chr> <chr> <chr>       <chr>   
#> 1   12000 Jamie … Jamie      Anderson  jamie.a… jami… 01/0… ""          ""      
#> # ℹ 6 more variables: sex <chr>, athlete_group <list>, coach_group <list>,
#> #   role <list>, phone <list>, address <list>

To unnest a list column, you can use the unnest() from tidyr:

tidyr::unnest(user_data, athlete_group)
#> # A tibble: 2 × 16
#>   user_id about   first_name last_name username email dob   middle_name known_as
#>     <dbl> <chr>   <chr>      <chr>     <chr>    <chr> <chr> <chr>       <chr>   
#> 1   12000 Jamie … Jamie      Anderson  jamie.a… jami… 01/0… ""          ""      
#> 2   12000 Jamie … Jamie      Anderson  jamie.a… jami… 01/0… ""          ""      
#> # ℹ 7 more variables: sex <chr>, athlete_group_id <dbl>,
#> #   athlete_group_name <chr>, coach_group <list>, role <list>, phone <list>,
#> #   address <list>

sb_get_group()

sb_get_group() returns a list of Smartabase groups available to your account. It’s arguments are username, password and url.

sb_get_group(
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password"
)

#> # A tibble: 3 × 1
#>   group     
#>   <chr>     
#> 1 All Users 
#> 2 First Team
#> 3 Reserves

sb_select_metadata()

Once data has been exported from Smartabase, it is often desirable to retain the metadata variables (e.g. about, start_time etc.) in the data frame before importing back to Smartabase. This helper function will look for any metadata variables present in a data frame and return them, as opposed to needing to write out write out metadata variables names yourself. For example:

example_df <- dplyr::tibble(
  about = c("Jamie Anderson", "Charlie Thompson"),
  start_date = c("14/02/2023", "14/02/2023"),
  form = "Hydration",
  `Body Weight pre training` = round(runif(2, 82, 92), 0),
  `Body Weight post training` = round(runif(2, 82, 92), 0),
  `Urine Colour` = round(runif(2, 1, 8), 0),
  end_date = c("14/02/2023", "14/02/2023")
)

example_df %>% dplyr::select(sb_select_metadata(.))

#> # A tibble: 2 × 4
#>   about            start_date form      end_date  
#>   <chr>            <chr>      <chr>     <chr>     
#> 1 Jamie Anderson   14/02/2023 Hydration 14/02/2023
#> 2 Charlie Thompson 14/02/2023 Hydration 14/02/2023