Exporting Data

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

sb_get_event(), sb_get_profile(), sb_get_id() and sb_sync_event() all leverage the Smartabase API to get event data out of Smartabase and into your R session. While only sb_get_event() requires a date_range value, all export functions contain filter and option arguments. These arguments allow you to extract only the data you need, which means better performance.

date_range

You must supply every call to sb_get_event() with a date_range value. For example, to export event data with event dates between March 1st 2023 to March 7th 2023, we would write:

sb_get_event(
  form = "Example Form",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password"
)

A valid date_range value must be a vector of length 2 containing a start_date and an end_date formatted in dd/mm/YYYY. They must also be character types (so, not produced by as.Date(), for instance) and the end_date must not occur before the start_date.

sb_date_range()

Sometimes it’s easier to think about date ranges in relative terms from today (i.e. format(lubridate::today(), "%d/%m/%Y)).

sb_date_range() sets the end_date to today by default and supplies a start_date depending on how far you want to look back. For instance, if we want data from the last week:

sb_date_range(duration_value = "7", duration_unit = "days")

#>   start_date     end_date 
#> "15/04/2023" "22/04/2023"

In a call to sb_get_event():

sb_get_event(
  form = "Example Form",
  date_range = sb_date_range("7", "days"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password"
)

You can also set your own end_date:

sb_get_event(
  form = "Example Form",
  date_range = sb_date_range("7", "days", end_date = "31/12/1999"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password"
)

time_range

You can also optionally supply a time_range value. By default it is set to time_range = c("12:00 am", "11:59 pm"), which doesn’t filter out any events based on event time. However in the situation that you require to export events that occurred within specific times of the day, you can manually supply a time_range value like so:

sb_get_event(
  form = "Example Form",
  date_range = c("01/03/2023", "01/03/2023"),
  time_range = c("12:45 PM", "1:15 PM"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password"
)

Which would only export events that started on March 1st between 12:45 PM and 1:15 PM. time_range has the same rules as the date_range arguments, except of course we must now use time notation. The Smartabase API requires that the format be h:mm AM/PM.

filter

NOTE: in the next major release of smartabaseR, the filter argument will be required when calling any export function. In particular, user_key and user_value will be required.

All filter values must be generated by the relevant helper function. So, if we’re using sb_get_event() to export data only for the athlete Jamie Anderson, we would need to use sb_get_event_filter():

sb_get_event(
  form = "Example Form",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter(
    user_key = "about",
    user_value = "Jamie Anderson"
  )
)

Each export function has an associated filter function:

• sb_sync_event(..., filter = sb_sync_event_filter())
• sb_get_profile(..., filter = sb_get_profile_filter())
• sb_get_id(..., filter = sb_get_id_filter())
• etc…

Below goes into more detail about each available filter.

User filtering

Note: this section applies to both sb_get_event() and sb_get_profile().

user_key and user_value allow you to filter event/profile data for specific Smartabase users.

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

If we wanted to filter for the athlete “Aiden Thomas” then we”d set user_key = "about" and user_value = "Aiden Thomas".

about

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

sb_get_event(
  form = "Example event form",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter(
    user_key = "about",
    user_value = c("Aiden Thomas", "Jamie Anderson")
  )
)

user_id

If user_key = "user_id", user_value accepts Smartabase user IDs.

Note: Smartabase user IDs are automatically generated by the system and may be different to Smartabase UUIDs, which can be manually set in the Smartabase admin site.

sb_get_event(
  form = "Example event form",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter( 
    user_key = "user_id",
    user_value = c(37204, 37201)
  )
)

username

If user_key = "username", user_value accepts Smartabase usernames.

sb_get_event(
  form = "Example event form",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter( 
    user_key   = "username",
    user_value = c("aiden.thomas", "jamie.anderson"),
  )
)

email

If user_key = "email", user_value accepts users’ emails, as recorded on Smartabase.

sb_get_event(
  form = "Example event form",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter(
    user_key = "email",
    user_value = c("aiden.thomas@teamworks.com", 
                   "jamie.anderson@teamworks.com"),
  )
)

current_group

If user_key = "current_group", the Smartabase API will look for whatever Smartabase group was loaded when you last logged into Smartabase. Data will then only be exported for these users. user_value is ignored.

sb_get_event(
  form = "Example event form",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter(
    user_key = "current_group"
  )
)

group

If user_key = "group", user_value accepts the name of a Smartabase group. Data will then only be exported for users in that Smartabase group.

sb_get_event(
  form = "Example event form",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter( 
    user_key = "group",
    user_value = "Demo Users"
  )
)

To see a list of Smartabase groups that you have access to, use the sb_get_group() function. For more details, see vignette(helper-functions).

Data filtering

Note: profile forms don’t allow data filtering. This section only applies to sb_get_event().

data_key / data_value

data_key and data_value allow you to filter the data according to certain rules.

For example, if you had a “Training Log” form with an “Duration” field, and you only want to export data where Duration was equal to “35”, your sb_get_event() call may look like this

sb_get_event(
  form = "Training Log",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter( 
    data_key = "Duration",
    data_value = "35"
  )
)

data_condition

By default, records that are equal to data_value will be exported. However, you may want to export records where, for example, Duration is greater than “35”. You can achieve this by supplying “greater_than” to the data_condition argument:

sb_get_event(
  form = "Training Log",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter( 
    data_key = "Duration",
    data_value = "35",
    data_condition = "greater_than"
  )
)

data_condition accepts any of the following values:

• "equal_to"
• "not_equal_to"
• "greater_than"
• "less_than"
• "greater_than_or_equal_to"
• "less_than_or_equal_to"
• "contains"

Note that the “greater_than”, “greater_than_or_equal_to”, “less_than” and “less_than_or_equal_to” operators will only work on number fields.

You can use multiple filters in the same call to sb_get_event(). For example, if we only wanted events where Duration < 25 AND RPE > 6:

sb_get_event(
  form = "Training Log",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter( 
    data_key = c("Duration", "RPE"),
    data_value = c("25", "6"),
    data_condition = c("less_than", "greater_than")
  )
)

Just be aware that the API will look data that meet ALL criterion. Practically this tends to mean it makes no sense to create competing conditions for a single Smartabase field:

sb_get_event(
  form = "Training Log",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter( 
    data_key = c("Duration", "Duration"),
    data_value = c("25", "6"),
    data_condition = c("greater_than", "less_than")
  )
)

#> # A tibble: 0 × 0

It’s impossible to have a Duration value that is both greater than 25 and less than 6, so the API returns nothing.

Also note that data_key, data_condition and data_value must be the same length.

Summary

Below are some examples of filtering for both multiple users and multiple conditions in the one sb_get_event() call.

Filter example 1

If we want to filter for 1) “Aiden Thomas” and “Jamie Anderson” using their emails and 2) events where Duration is less than “25” minutes and RPE is greater than or equal to “6”, then our sb_get_event() call would look like this:

sb_get_event(
  form = "Training Log",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter( 
    user_key = "email",
    user_value = c("aiden.thomas@teamworks", "jamie.anderson@teamworks"),
    data_key = c("Duration", "Duration"),
    data_value = c("25", "6"),
    data_condition = c("greater_than", "less_than")
  )
)

Filter example 2

Alternatively, if we wanted data for 1) “Aiden Thomas” and “Jamie Anderson” using their full names and 2) events where Duration is not equal to “50” minutes and RPE contains the word “Hard”:

sb_get_event(
  form = "Training Log",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter( 
    user_key = "email",
    user_value = c("Aiden Thomas", "Jamie Anderson"),
    data_key = c("Duration", "RPE"),
    data_value = c("50", "Hard"),
    data_condition = c("not_equal_to", "contains")
  )
)

option

All option values must be generated by the relevant helper function. So, if we’re using sb_get_event() to export data but we want every column to be a string, we could use sb_get_event_option(guess_col_type = FALSE):

sb_get_event(
  form = "Example Form",
  date_range = c("01/03/2023", "07/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  option = sb_get_event_option(
    guess_col_type = FALSE
  )
)

Each export function has an associated option function:

• sb_sync_event(..., option = sb_sync_event_option())
• sb_get_profile(..., option = sb_get_profile_option())
• sb_get_id(..., option = sb_get_id_option())
• etc…

Below goes into more detail about each available option.

cache

The first time you call the Smartabase API within a given R session, smartabaseR makes a call to sb_login(). If the cache option is set to TRUE (default), then this login object is then saved into memory and passed to further calls to the Smartabase API. If the cache option is FALSE, then each subsequent call to the Smartabase API will be preceded by a call to sb_login().

download_attachment

If you are exporting data that contains a file upload field, you can download any uploaded files to your local machine by setting the download_attachment = TRUE. Smartabase will return the event data as well as any associated files, which are downloaded to the current directory.

sb_get_event(
  form = "Example Form",
  date_range = c("17/03/2023", "17/03/2023"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  option = sb_get_event_option(
    download_attachment = TRUE
  )
)

#> ✔ Hydration (SS) attachment download successful: 5 out of 5 files (80.01kb total) saved to C:/Users/ZacPross/Example_directory
#> ✔ Hydration (SS) export successful (17/03/2023 - 17/03/2023).

#> # A tibble: 1 × 12
#>   about         user_id form  start_date File  Distance   RPE entered_by_user_id
#>   <chr>           <dbl> <chr> <chr>      <chr>    <dbl> <dbl>              <dbl>
#> 1 Jamie Anders…   37201 Exam… 18/04/2023 1234…     3100     7              37201
#> # ℹ 4 more variables: event_id <dbl>, file_name <chr>, attachment_url <chr>,
#> #   name <chr>

include_missing_users

If an athlete has no data stored against them (or the requested date_range, then the Smartabase API won’t return any event data about that athlete.

But sometimes it’s interesting to include rows about athletes that have no data stored against them. For instance, let’s say we want to get data from “Training Log” for the last 2 days and include all athletes from the “Demo Group”, irrespective if they have data in “Training Log” for those 2 days:

sb_get_event(
  form = "Training Log",
  date_range = sb_date_range("2", "days"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter(
    user_key = "group",
    user_value = "Demo Group"
  )
  option = sb_get_event_option(
    include_missing_users = TRUE
  )
)

#> # A tibble: 4 × 8
#>   about      user_id form  start_date Distance   RPE entered_by_user_id event_id
#>   <chr>        <dbl> <chr> <chr>         <dbl> <dbl>              <dbl>    <dbl>
#> 1 Charlie T…   31808 Exam… 15/04/2023     5411     7              37201    16517
#> 2 Jack Will…   31811 Exam… 15/04/2023     2374     3              37201    36505
#> 3 Jamie And…   37201 NA    NA               NA    NA                 NA       NA
#> 4 Liam Walk…   37204 NA    NA               NA    NA                 NA       NA

Jamie Anderson and Liam Walker haven’t entered any data, which could prove relevant information for data quality reporting.

guess_col_type

By default, sb_get_event() and sb_get_profile() guess the data type of each column. For example, setting guess_col_type = TRUE:

sb_get_event(
  form = "Training Log",
  date_range = sb_date_range("2", "days"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter(
    user_key = "about",
    user_value = "Charlie Thompson"
  )
  option = sb_get_event_option(
    guess_col_type = TRUE
  )
)

#> # A tibble: 1 × 9
#>   about            user_id form      start_date `Date of Session` Distance   RPE
#>   <chr>              <dbl> <chr>     <chr>      <chr>                <dbl> <dbl>
#> 1 Charlie Thompson   31808 Example … 15/04/2023 15/04/2023            5411     7
#> # ℹ 2 more variables: entered_by_user_id <dbl>, event_id <dbl>

Notice how in the tibble above the about column has <chr> at the top. This means that the column is character type. The Distance column has <dbl> at the top, which means it contains numeric data.

However, if you don’t want sb_get_event() to guess the column types, and you’d prefer each column to come through as character types, set guess_col_type = FALSE.

sb_get_event(
  form = "Training Log",
  date_range = sb_date_range("2", "days"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter(
    user_key = "about",
    user_value = "Charlie Thompson"
  )
  option = sb_get_event_option(
    guess_col_type = FALSE
  )
)

#> # A tibble: 1 × 10
#>   about       user_id form  start_date end_date `Date of Session` Distance RPE  
#>   <chr>         <dbl> <chr> <chr>      <chr>    <chr>             <chr>    <chr>
#> 1 Charlie Th…   31808 Exam… 15/04/2023 17/04/2… 1555288875000     5411     7    
#> # ℹ 2 more variables: entered_by_user_id <dbl>, event_id <dbl>

Notice how the Distance column is now <chr>, whereas before it was <dbl>.

A few other things to note:

• The metadata columns user_id, entered_by_user_id and event_id are not affected by the guess_col_type argument – they will always come through as numeric.
• Event dates will always be exported as character types since it’s required when importing back into Smartabase.

interactive_mode

sb_get_event() and sb_get_profile() accept an input called interactive_mode. If interactive_mode = FALSE, no messages will be printed to screen. This is for when the package is being run in automated environments. In these situations you may want to minimise progress messages clogging up logs.

sb_get_event(
  form = "Training Log",
  date_range = sb_date_range("2", "days"),
  url = "example.smartabase.com/site",
  username = "example.username",
  password = "example_password",
  filter = sb_get_event_filter(
    user_key = "about",
    user_value = "Charlie Thompson"
  ),
  option = sb_get_event_option(
    interactive_mode = FALSE
  )
)