R Package

hawkinR

A secure, configurable R interface to the Hawkin API. Profile-based authentication with the OS keychain, automatic access-token refresh, region-aware routing, and tidy data frames for sport scientists and analysts.

Version

2.0.1

Platform

R ≥ 4.1.0

Availability

CRAN · MIT

Installation

Install the released version of hawkinR from CRAN.

# Released version (recommended) install.packages("hawkinR")

Or install the development version from GitHub.

# install.packages("devtools") devtools::install_github("HawkinDynamics/hawkinR")

Requirements: R ≥ 4.1.0. hawkinR uses the keyring package to store your Integration Key in your operating system's credential store (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux).

Authentication

hawkinR v2 uses a profile-based authentication system. Store your Integration Key once, then connect — the package manages access-token refresh for you.

Store Your Integration Key

Run hd_auth_store() once. A secure prompt saves your Refresh Token (Integration Key) to the OS keychain under the "default" profile. Nothing is written to your scripts or history.

Connect to the API

Call hd_connect(region = "Americas"). This reads your stored key, exchanges it for an access token, and sets the active session for subsequent calls.

Start Querying

All get_*() functions use the active session automatically. The access token is refreshed in the background as needed.

Quick Start

A complete, runnable script to get your first data.

library(hawkinR) # 1. Store your Integration Key once (secure interactive prompt) hd_auth_store() # 2. Connect to the Hawkin Cloud (sets the active session) hd_connect(region = "Americas") # 3. Get your organization data roster <- get_athletes() teams <- get_teams() groups <- get_groups() # 4. Get test data for a date range tests <- get_tests( from = "2024-01-01", to = "2024-01-31" ) # 5. View your data head(tests)

Regional Endpoints

Set the region argument in hd_connect() to match your organization's data residency.

Region	Value	Base URL
Americas	`"Americas"`	`cloud.hawkindynamics.com`
Europe	`"Europe"`	`eu.cloud.hawkindynamics.com`
Asia-Pacific	`"APAC"`	`apac.cloud.hawkindynamics.com`

Tutorials & Guides

User Guide

In-depth tutorials covering authentication, data retrieval, force-time and COP analysis, logging, and deploying hawkinR inside a hosted Shiny application.

Getting Started with hawkinR

hawkinR manages the exchange of your Integration Key (Refresh Token) for an ephemeral Access Token automatically in the background. You store your key once, then connect.

Storing Your Integration Key

Run hd_auth_store() once per machine. A secure prompt writes your Refresh Token to the operating system credential store via the keyring package — it is never saved in your scripts, environment files, or command history.

library(hawkinR) # Secure interactive prompt; stores under the "default" profile hd_auth_store() # Store additional named profiles (e.g. a second org) hd_auth_store(profile = "research")

Connecting to the Cloud

Use hd_connect() to initialize your session. It reads the stored key for the profile, authenticates, and sets the active connection used by every get_*() call.

# Connect with the default profile hd_connect(region = "Americas") # Connect with a named profile hd_connect(profile = "research", region = "Europe")

Exploring Your Organization

Once connected, retrieve the structural data of your organization. These IDs are used as filters when pulling performance tests.

roster <- get_athletes() teams <- get_teams() groups <- get_groups()

Authentication Deep Dive

hawkinR v2 supports two authentication environments, selected with the environment argument of hd_connect().

Development — OS Keychain (default)

For local, interactive work, store your key in the OS keychain with hd_auth_store() and connect with the default environment = "development". This is the most secure option for a workstation.

library(hawkinR) hd_auth_store() # one-time: secure prompt -> OS keychain hd_connect(region = "Americas") # environment = "development" (default)

Production — Environment Variable

For servers, containers, and scheduled jobs where a keychain is unavailable, set environment = "production". hawkinR then reads the Refresh Token from an environment variable named HAWKIN_KEY_<PROFILE> (the profile name, upper-cased). The default profile reads HAWKIN_KEY_DEFAULT.

# Host sets the env var (never commit the token): # HAWKIN_KEY_DEFAULT = your_refresh_token library(hawkinR) hd_connect(environment = "production", region = "Americas")

Profile → variable mapping: the environment variable name is always HAWKIN_KEY_ plus the upper-cased profile. Profile "prod" reads HAWKIN_KEY_PROD; profile "default" reads HAWKIN_KEY_DEFAULT.

Managing Stored Credentials

Remove a stored key from the keychain with hd_auth_reset().

hd_auth_reset() # removes the "default" profile hd_auth_reset(profile = "research") # removes a named profile

Function	Purpose
`hd_auth_store(profile)`	Securely store a Refresh Token in the OS keychain
`hd_connect(profile, environment, region)`	Authenticate and set the active session
`hd_auth_reset(profile)`	Remove a stored Refresh Token

Getting Tests

The get_tests() function is the primary tool for querying performance data, with flexible filtering by athlete, team, group, test type, and date range. Large queries are paginated automatically using cursor-based pagination (1,000 tests per page).

Note: v2 replaces the old get_tests_ath() / get_tests_team() / get_tests_group() / get_tests_type() functions. Use get_tests() with filter parameters instead. The chunk_size argument is deprecated and ignored.

Basic Usage

Provide a date range using standard date strings or Unix timestamps.

hd_connect(region = "Americas") # All tests (all available history) all_tests <- get_tests() # Tests from the start of 2023 to present tests <- get_tests(from = "2023-01-01")

Filter by Test Type

Use a canonical ID, test type name, or abbreviation. See get_testTypes() for the full list.

# By abbreviation cmj_data <- get_tests(typeId = "CMJ") sj_data <- get_tests(typeId = "SJ") # By full name iso_data <- get_tests(typeId = "Isometric Test")

Filter by Athletes, Teams, or Groups

# By athlete athlete_id <- roster$id[roster$name == "Some Athlete"] ath_tests <- get_tests(athleteId = athlete_id) # By team (accepts a vector; max 10) team_ids <- c("team_id_1", "team_id_2") cohort_data <- get_tests(teamId = team_ids)

Important: Tests can be filtered by only one entity type at a time (plus a time frame). You cannot combine teamId and groupId in the same call.

The Sync Parameter

For incremental refresh logic, use sync = TRUE to pull data based on when it was uploaded/modified rather than when the test occurred.

# Pull everything synced in the last 24 hours last_24h <- as.numeric(Sys.time()) - 86400 new_data <- get_tests(from = last_24h, sync = TRUE)

Data Structure

The returned data frame is organized into four logical sections:

Section	Contents
Trial Info	Basic trial metadata (`id`, `timestamp`, `segment`)
Test Type Info	Details about the movement performed
Athlete Info	`athlete_*` columns (name, teams, groups, profile fields, external properties)
Metrics	All performance metrics (Force, Velocity, Power, etc.)

Including Inactive Data

By default only "active" trials are returned (server-side). For auditing, set includeInactive = TRUE. Set includeEid = TRUE to add the equipment ID (eid) of the hardware that produced each trial.

Force-Time & COP Data

Use get_forcetime() for high-frequency raw force data (1000 Hz; 1200 Hz for TruStrength) and get_cop() for Center-of-Pressure series. Both return S7 objects whose @data slot holds a tidy data frame.

Fetching a Single Test

Get the unique id from get_tests(), then fetch the raw data.

# Find a CMJ from yesterday recent <- get_tests(typeId = "CMJ", from = Sys.Date() - 1) target_id <- recent$id[1] # Fetch raw force-time data (HawkinForceTime object) ft <- get_forcetime(testId = target_id) # Access metadata via @ slots ft@athlete_name #> "John Doe" ft@testType_name #> "Countermovement Jump" # The raw data frame: time_s, left_force_N, right_force_N, # combined_force_N, velocity_m_s, displacement_m, power_W ... head(ft@data)

Plotting

plot( x = ft@data$time_s, y = ft@data$combined_force_N, type = "l", col = "blue", main = paste("Jump Trace:", ft@athlete_name), xlab = "Time (s)", ylab = "Force (N)" )

Bulk Force-Time Export

Use get_forcetime_bulk() to pull many trials at once, optionally writing each to a file.

# Pass a data frame with an 'id' column (e.g. get_tests() output) cmj <- get_tests(typeId = "CMJ", from = "2024-01-01") # Return a named list of results... ft_list <- get_forcetime_bulk(test_ids = cmj) # ...or export each trial to CSV get_forcetime_bulk( test_ids = cmj, export = TRUE, export_dir = "forcetime_out", format = "csv" )

Center of Pressure (Free Run)

get_cop() returns a HawkinCOP object. COP data is exclusive to the Free Run test type — other test types return a 404.

fr <- get_tests(typeId = "Free Run", from = "2024-01-01") cop <- get_cop(testId = fr$id[1]) # Columns: time_s, cop_x, cop_y, left_cop_x, left_cop_y, # right_cop_x, right_cop_y (mm relative to plate center) head(cop@data)

Logging Features

hawkinR uses the logger package for status updates, background processes, and debugging information. Set the verbosity when you connect via hd_connect(log_level = ...), or configure output destinations with initialize_logger().

Log Levels

Level	Use Case
`TRACE`	Detailed execution logs including request paths
`DEBUG`	Information useful for debugging
`INFO`	(Default) Standard process updates
`WARN`	Warnings about token expiration or non-critical issues
`ERROR`	Critical failures only

Verbose Debugging

# Detailed TRACE logging to the console initialize_logger(log_threshold_stdout = "TRACE") hd_connect(region = "Americas", log_level = "DEBUG") tests <- get_tests(from = "2023-01-01")

Silent Operation (Production)

# Only log critical failures initialize_logger(log_threshold_stdout = "ERROR")

Logging to a File

# Write logs to a file for auditing initialize_logger( log_output = "both", log_file = "hawkin_audit.log", log_threshold_file = "TRACE" )

Deploying hawkinR in a Shiny App

Authentication in a deployed Shiny app is different from running scripts locally. On your workstation you use the OS keychain (interactive). A hosted app has no keychain and no interactive prompt, so it authenticates from an environment variable instead.

Context	How the key is supplied	Connect call
Local scripts / RStudio	`hd_auth_store()` → OS keychain (interactive, once)	`hd_connect(region = "Americas")`
Deployed app (shinyapps.io, Posit Connect, Docker)	`HAWKIN_KEY_DEFAULT` environment variable / platform secret	`hd_connect(environment = "production", region = "Americas")`

1. Set the token as a platform secret

Never commit the token or call hd_auth_store() in deployed code. Instead set the environment variable on your host:

shinyapps.io: app Settings → Environment Variables
Posit Connect: the content's Vars pane
Docker: docker run -e HAWKIN_KEY_DEFAULT=your_token ...

2. Connect once at app startup

Call hd_connect(environment = "production") at the top of app.R (outside server) so the session is authenticated once and shared across sessions.

library(shiny) library(hawkinR) # Reads HAWKIN_KEY_DEFAULT from the platform environment. # Quieter logging is a good default for a hosted app. initialize_logger(log_threshold_stdout = "WARN") hd_connect(environment = "production", region = "Americas") ui <- fluidPage( titlePanel("Hawkin Dashboard"), actionButton("refresh", "Refresh Data"), tableOutput("tests_table") ) server <- function(input, output, session) { test_data <- reactiveVal() observeEvent(input$refresh, { test_data(get_tests(from = Sys.Date() - 7)) }) output$tests_table <- renderTable({ req(test_data()) head(test_data(), 20) }) } shinyApp(ui, server)

Local testing tip: to run the same app on your machine without the keychain, set HAWKIN_KEY_DEFAULT in your .Renviron (via usethis::edit_r_environ()) and keep environment = "production". To use the keychain instead, run hd_auth_store() once and switch the startup call to hd_connect(region = "Americas").

Containerized deployment (Docker)

# Dockerfile FROM rocker/shiny:latest RUN R -e "install.packages('hawkinR')" COPY app/ /srv/shiny-server/ # Run with the token injected as an env var # docker run -e HAWKIN_KEY_DEFAULT=your_token -p 3838:3838 myapp

API Reference

Function Reference

Complete documentation for all exported hawkinR functions — signatures, parameters, return values, and examples.

Authentication

hd_auth_store(profile = "default", token = NULL)

Securely stores your Refresh Token (Integration Key) in the operating system credential store via keyring. Run once per machine/profile. Requires an interactive session.

Parameters

Name	Type	Default	Description
`profile`	character	"default"	A name for this set of credentials
`token`	character	NULL	Optional. If NULL, a secure prompt appears (recommended). Passing the token directly may record it in `.Rhistory`

Returns

No return value; called for its side effect (stores the token in the OS keychain).

Example

hd_auth_store() # secure prompt, "default" profile hd_auth_store(profile = "research")

hd_connect(profile = "default", org_id = "v1",
                environment = "development", region = "Americas", log_level = "INFO")

Initializes a connection to the Hawkin Cloud: creates the session, performs the initial authentication, and sets it as the active connection for subsequent data calls.

Parameters

Name	Type	Default	Description
`profile`	character	"default"	The name of the stored profile credential to use
`org_id`	character	"v1"	Your Organization ID. Defaults to "v1" for standard users
`environment`	character	"development"	"development" to use the local keychain, or "production" to use environment variables
`region`	character	"Americas"	API region: "Americas", "Europe", or "APAC"
`log_level`	character	"INFO"	Logging verbosity: "INFO", "DEBUG", or "WARN"

Returns

Invisibly returns the authenticated HawkinAuth object and sets it as the active session.

Example

# Local (keychain) hd_connect(region = "Americas") # Deployed (reads HAWKIN_KEY_DEFAULT) hd_connect(environment = "production", region = "Americas")

hd_auth_reset(profile = "default")

Deletes a stored Refresh Token from the system keychain.

Parameters

Name	Type	Default	Description
`profile`	character	"default"	The name of the profile to remove

Returns

No return value; called for its side effect.

Data Retrieval

get_tests(from, to, sync, athleteId, typeId, teamId,
                groupId, includeInactive, includeEid, ...)

Retrieves test data from the Hawkin API. Replaces all previous get_tests_* functions. Filters by athlete, team, group, test type, and date/sync range. Cursor pagination is handled automatically.

Parameters

Name	Type	Default	Description
`from`	int / chr	NULL	Start of the time frame. Unix timestamp or "YYYY-MM-DD". If omitted, no lower bound
`to`	int / chr	NULL	End of the time frame. Unix timestamp or "YYYY-MM-DD". If omitted, runs through the most recent test
`sync`	logical	FALSE	If TRUE, filters by last-modified time (sent as syncFrom/syncTo) to include updated and newly created tests
`athleteId`	character	NULL	Filter by a specific athlete ID
`typeId`	character	NULL	Canonical test ID, test type name, or abbreviation
`teamId`	chr / list	NULL	Team ID(s). Max 10
`groupId`	chr / list	NULL	Group ID(s). Max 10
`includeInactive`	logical	FALSE	Include inactive (disabled) trials
`includeEid`	logical	FALSE	Include the equipment ID (`eid`) that produced each trial
`...`			Accepts `profile` (a HawkinAuth object or profile name). `chunk_size` is deprecated and ignored

Returns

A data frame of test trials and their metrics — one row per trial. Empty result returns an empty data frame.

Examples

# All tests (uses active connection) dfAll <- get_tests() # Specific date range dfRange <- get_tests(from = "2023-08-01", to = "2023-08-10") # Filter by athlete and test type dfFiltered <- get_tests(athleteId = "abc123", typeId = "CMJ")

get_forcetime(testId, ...)

Retrieves the raw force-time data for a single test trial. Sampled at 1000 Hz (1200 Hz for TruStrength test types).

Parameters

Name	Type	Default	Description
`testId`	character	—	The unique identifier for the test trial
`...`			Accepts `profile` (HawkinAuth object or profile name)

Returns

A HawkinForceTime S7 object. The @data data frame contains time_s, left_force_N, right_force_N, combined_force_N, velocity_m_s, displacement_m, power_W (plus tri-axial force/moment columns on plate test types). @data_rsi holds RSI when available.

get_forcetime_bulk(test_ids = NULL, export = FALSE,
                export_dir = NULL, format = "csv", file_naming = "test_id", deidentify = FALSE,
                ...)

Retrieves raw force-time data for multiple tests. A wrapper over get_tests() and get_forcetime().

Parameters

Name	Type	Default	Description
`test_ids`	chr / df	NULL	A character vector of Test IDs, or a data frame with an `id` column (e.g. `get_tests()` output). If NULL, `get_tests(...)` is called to find targets
`export`	logical	FALSE	If TRUE, write each result to a file in `export_dir`
`export_dir`	character	NULL	Directory for exported files
`format`	character	"csv"	One of "csv", "tsv", "json", "rds", "rda", "parquet"
`file_naming`	character	"test_id"	Properties used to construct each filename
`deidentify`	logical	FALSE	If TRUE, replaces `athlete_name` with "De-identified"
`...`			Passed to `get_tests()` (e.g. `from`, `typeId`); also accepts `profile`

Returns

When export = FALSE, a named list of force-time results (one per test). When export = TRUE, an invisible character vector of file paths written. NULL if no matching tests are found.

get_cop(testId, ...)

Retrieves raw Center-of-Pressure (COP) time-series data for a test trial. COP data is exclusive to the Free Run test type — any other type returns a 404.

Parameters

Name	Type	Default	Description
`testId`	character	—	The unique identifier for the test trial
`...`			Accepts `profile` (HawkinAuth object or profile name)

Returns

A HawkinCOP S7 object. The @data data frame contains time_s, cop_x, cop_y, left_cop_x, left_cop_y, right_cop_x, right_cop_y — millimeters relative to plate center; NA where no weight is on a plate.

get_metrics(testType = "all")

Get all metrics and their IDs from the bundled metric dictionary. Works offline — no active connection required. Filter by test type using a canonical ID, name, or abbreviation.

Parameters

Name	Type	Default	Description
`testType`	character	"all"	Canonical test ID, test type name, or abbreviation (e.g. "CMJ", "SJ", "ISO", "DJ")

Returns

Data frame with columns canonicalTestTypeID, testTypeName, id, label, label_unit, header, units, description.

Example

df_metrics <- get_metrics(testType = "CMJ")

Organization

get_athletes(includeInactive = FALSE, ...)

Get all athletes for an account. Inactive athletes are only included if includeInactive is TRUE.

Parameters

Name	Type	Default	Description
`includeInactive`	logical	FALSE	Include inactive athletes
`...`			Accepts `profile`

Create new athletes for an account. Bulk create up to 500 athletes at a time.

Parameters

Name	Type	Default	Description
`athleteData`	data.frame	—	Athletes to create. Required column: `name`. Optional: `image`, `active`, `teams`, `groups`, plus any external property columns
`...`			Accepts `profile`

Returns

Invisibly TRUE on full success; on partial failure, a data frame of the failures with columns reason, name.

Example

df <- data.frame( name = c("John Doe", "Jane Smith"), active = c(TRUE, TRUE) ) create_athletes(athleteData = df)

update_athletes(athleteData, ...)

Update existing athletes. Bulk update up to 500 at a time. Optional fields that are omitted are left unchanged.

Parameters

Name	Type	Default	Description
`athleteData`	data.frame	—	Athletes to update. Required column: `id`. Optional: `name`, `image`, `active`, `teams`, `groups`, external properties
`...`			Accepts `profile`

Warning: when updating external properties, any custom properties not present in the request are removed. Always include all external properties you want to keep.

Returns

Invisibly TRUE on full success; on partial failure, a data frame with columns reason, name.

Configuration

HawkinConfig(profile = "default", org_id = "v1",
                environment = "development", log_level = "INFO")

S7 class constructor that stores environment and profile configuration. Most users never call this directly — hd_connect() builds it for you — but it can be used to construct a configuration explicitly.

Properties

Name	Type	Default	Description
`profile`	character	"default"	Profile name used for credential lookup
`org_id`	character	"v1"	Organization ID for API paths
`environment`	character	"development"	"development" (keyring) or "production" (env vars)
`log_level`	character	"INFO"	Logging verbosity ("INFO", "DEBUG", "WARN")

Returns

A HawkinConfig S7 object. The related HawkinAuth object holds live session state (config, access token, expiry, region, computed base URL).

initialize_logger(log_output = "stdout",
                log_threshold_stdout = "INFO", log_file = "hawkinRlog.log", log_threshold_file =
                "INFO")

Configure the logger's output destination and thresholds for stdout and file output. Opt-in — hawkinR writes no log file unless you select a file mode.

Parameters

Name	Type	Default	Description
`log_output`	character	"stdout"	"stdout", "file", or "both"
`log_threshold_stdout`	character	"INFO"	"TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"
`log_file`	character	"hawkinRlog.log"	Custom log file name/path
`log_threshold_file`	character	"INFO"	Log threshold for the file output

Example

# Debug to console initialize_logger(log_output = "stdout", log_threshold_stdout = "DEBUG") # Trace to a file initialize_logger(log_output = "file", log_file = "app/mylog.log", log_threshold_file = "TRACE")

Version History

Changelog

Release notes and version history for hawkinR.

2026

v2.0.1

Fixed

Correct `get_forcetime()` column alignment

get_forcetime() built its data frame by indexing the API response positionally, so when the response fields did not line up with the assumed positions the force-time series were populated from the wrong fields (columns misaligned relative to their labels) with no error. Columns are now selected by their named API fields (Time(s), LeftForce(N), RightForce(N), ...), so each series is populated from the correct vector regardless of field order or omitted optional fields
Added regression tests covering the force-time column mapping (this path previously had no coverage)

2026

v2.0.0

Added Updated

Complete rewrite — now on CRAN

Profile-based authentication via hd_auth_store() + hd_connect(), with secure OS-keychain storage (keyring) for local development and environment-variable credentials for production. Replaces the previous get_access() flow
S7 classes (HawkinConfig, HawkinAuth) for configuration and connection state; automatic access-token refresh
Cursor-based pagination for large test queries (handled automatically), plus region-aware routing (Americas / Europe / APAC)
New get_cop() (Center-of-Pressure, Free Run) and get_forcetime_bulk() for multi-trial export; get_forcetime() returns a HawkinForceTime S7 object
Structured logging via the logger package and initialize_logger()
Requires R ≥ 4.1.0

v2.0.0 is the current CRAN release. The 1.x line below is legacy and is no longer maintained.

2026

v1.2.0 – v1.2.4

Fixed

Legacy 1.2.x maintenance line

v1.2.4 — corrected get_forcetime() column labels (named-field indexing)
v1.2.3 — duplicate-name handling for external properties colliding with core columns (make.unique())
v1.2.2 — token handling & error-response hardening; v1.2.1 — AthletePrep() external-property fix
v1.2.0 — Hawkin API v1.14 compatibility patch (athlete profile fields, name-based column selection)

Superseded by v2.0.0 (CRAN).

2024

v1.1.0 – v1.1.5

Updated Fixed

Unified get_tests, logging, bug fixes

Updated get_tests() with unified filtering
Deprecated get_tests_* functions
teamId and groupId now accept lists and vectors
Added logging functionality and customization
TruStrength test types support

2023

v1.0.0 – v1.0.5

Added

Initial release

Core functions: get_tests_*, get_athletes, get_teams, get_groups, get_forcetime
Added get_tags(), typeId abbreviations
External ID and sync support