catapultR: Installation and Login

Prerequisites

In order to utilize the catapultR package, you must have R installed on your computer. Do not install R in “Program Files” directory in Windows. The target directory must not have spaces. You can download R from the Comprehensive R Archive Network (CRAN). Just use the link that corresponds to a location near you.

Installing the package

First, use the code below to install or update catapultR.


devtools::install_bitbucket("catapultsports/catapultr", 
                            dependencies=TRUE, build_vignettes=TRUE)

Now we can load the package along with a few other helpful packages. Also, setting the options to 12 digits enables centiseconds to be returned for some of the functions.

All data presented has been anonymized, removing and changing identifiable characteristics that can be traced back to a team or athlete.


# load packages ------------------------------------------------------------
library(catapultR)
library(tidyverse)
library(lubridate)
options(digits = 12)

The package is copyrighted for Catapult Sports. This can be seen by running the following line in R.


paste0(readr::read_lines(system.file("LICENSE", package = "catapultR"))[1], " ",
       readr::read_lines(system.file("LICENSE", package = "catapultR"))[2])


[1] "YEAR: 2022 COPYRIGHT HOLDER: Catapult Sports Pty Ltd"

Try running these lines for some additional documentation.


package?catapultR
help(package="catapultR")
library(help="catapultR")
browseVignettes("catapultR")
packageVersion("catapultR")
packageDescription("catapultR")

Validate User Credentials

In the past, catapultR users could generate a token using their OpenField username and password, along with a secure client ID and client secret. However, this approach has been replaced by a new procedure that is more secure and flexible for our customers. This allows customers to generate their own secure token strings in OpenField Cloud.

Using a Token String Generated in OF Cloud

If enabled on your account, you can also generate an API token string in OpenField Cloud. After logging in, click on SETTINGS in the top ribbon. Then, select “API Tokens” and create a token. After clicking “Create,” a pop up window will appear with a very long text string. Make sure to copy the token to a secure location as you will not have the opportunity to retrieve it after closing this window.

For more information, see the Catapult Support page on API tokens.

You can then use this string to create a catapultR token:


token <- ofCloudCreateToken(sToken = "STe67MbNGfkO5XH8jaZDyoQvnz4VBYiL0Clg2RcW",  sRegion = "America")

Note that the token string in the example above has been shortened for display purposes. Yours will be much longer. It is suggested that you keep this string secure and sources from a location that is separate from your coding project.


ofCredentials: 
  Name: brian_wsoccer_demo
  Region:  America
  Stage:  main
  TokenTime:  1644331744
  TokenExpireTime:  1644335344
  ApiStatus:  200
  ApiMessage:  
  ApiTimeout:  60

The token will be used to access data for a specific user’s OF account.

Access Account Information

Get the customer information for the account


customer_info <- ofCloudGetCustomerInfo(token)
glimpse(customer_info)


Rows: 1
Columns: 8
$ id                    <fct> 683
$ name                  <fct> Titans
$ db_name               <chr> "wsoccerdemo"
$ aws_region            <chr> "eu-west-1"
$ webserver             <chr> "https://us.catapultsports.com"
$ is_combined           <chr> "0"
$ user_default_timezone <fct> US/Mountain
$ data_setup            <chr> "1"

See what teams are associated the account


teams <- ofCloudGetTeams(token)
glimpse(teams)


Rows: 1
Columns: 24
$ id                      <chr> "7pkjvzc2-pf7x-si7l-jldg-axb2lf7vw9c~
$ sport_id                <chr> "31eff51d-b396-42cb-b3ce-a6e7543e2b8~
$ name                    <chr> "Werewolves Team A"
$ slug                    <chr> "teamA"
$ logo                    <chr> "1e34e5292218dfc8e1fa24b9768d4b4fa69~
$ primary_colour          <chr> "#ff9900"
$ secondary_colour        <chr> "#ffffff"
$ velocity_dwell_time     <int> 1
$ acceleration_dwell_time <dbl> 0.6
$ heart_rate_dwell_time   <dbl> 0.6
$ player_load_dwell_time  <dbl> 0.1
$ rhie_effort_count       <int> 3
$ rhie_effort_recovery    <int> 21
$ velocity_rhie_bands     <chr> "5,6"
$ acceleration_rhie_bands <chr> "1,2,7,8"
$ is_synced               <int> 1
$ is_deleted              <int> 0
$ created_at              <chr> "2014-03-26 02:40:19"
$ modified_at             <chr> "2020-11-05 15:18:41"
$ sport_name              <chr> "Football"
$ tag_list                <list> []
$ logo_url                <chr> "https://clprototype.s3.amazonaws.co~
$ tags                    <list> []
$ is_default              <lgl> TRUE

See what modules are available on the account


modules <- ofCloudGetModules(token)
modules


 [1] "GoalKeeping"                    "Download"                      
 [3] "GPS"                            "PluginSecurity:Adhoc"          
 [5] "VelocityBandSet2"               "Gen2AccelerationBands.Released"
 [7] "Gen1VelocityBands.Released"     "AdhocParams.Released"          
 [9] "Gen1AccelerationBands.Released" "Gen2VelocityBands.Released"    
[11] "GoalkeepingDive"                "GK.V2"                         
[13] "GK.V1"                          "StreamOpenfieldOptimeyeStable"

Conclusion

Now that you have successfully logged in and accessed some account information, you can proceed to the next part of the Quick Start Tutorial.

Contact: Analytics@catapultsports.com (email) | #ask_catapultR (Slack)