Package {hawkinR}

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Internal State Container

Description

This object is initialized in zzz.R during .onLoad(). It holds the active HawkinAuth connection.

Usage

.hawkin_env

Format

An object of class environment of length 1.

Hawkin Authentication Class

Description

Manages the API session state, including the access token lifecycle and regional endpoints.

Usage

HawkinAuth(
  config = HawkinConfig(),
  access_token = NULL,
  expires_at = NULL,
  region = "Americas"
)

Arguments

Value

An S7 object of class HawkinAuth representing the API session state, including its config, access_token, expires_at, region, and the computed read-only base_url.

Properties

• base_url: The computed API base URL for the region (read-only).

Hawkin Configuration Class

Description

Stores environment and profile configuration settings.

Usage

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

Arguments

Value

An S7 object of class HawkinConfig storing environment and profile configuration settings (profile, org_id, environment, and log_level).

Metric Dictionary

Description

This data frame contains metrics from all tests.

Usage

MetricDictionary

Format

A data frame with 484 rows and 7 variables:

canonicalTestTypeId

The unique id of the canonical test type (character).

testTypeName

The given / common name of the test type (character).

id

PascalCase formatted name of the metric (character).

label

The metric label found in app and cloud UI (character).

label_unit

The metric name returned from the API (character).

header

header of data frame output (character).

units

Metric unit of measure (character).

description

A verbose description of the metric (character).

Source

Generated for demonstration purposes.

Hawkin Dynamics Authentication System

Description

Defines the S7 classes and methods for managing authentication state, secure credential storage, and session configuration.

Authenticate / Refresh Token

Description

Internal S7 generic to exchange a Refresh Token for a new Access Token.

Usage

authenticate(x, ...)

Arguments

Value

An updated HawkinAuth object with a valid access token.

Create Athletes

Description

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

Usage

create_athletes(athleteData, ...)

Arguments

Details

The data frame passed as the argument must use the following schema:

Value

If successful, a confirmation message will be printed with the number of successful athletes created. If there are failures, a data frame containing the athletes that failed to be created will be returned with columns:

Examples

## Not run: 
# Example data frame following the required schema
df <- data.frame(
  name = c("John Doe", "Jane Smith"),
  image = c("https://example.com/johndoe.jpg", "https://example.com/janesmith.jpg"),
  active = c(TRUE, FALSE),
  teams = I(list("team1", c("team2", "team3"))),
  groups = I(list(NULL, "group1")),
  external_property = c("value1", "value2")
)

# Create athletes using the example data frame
create_athletes(athleteData = df)

## End(Not run)

Get Athletes

Description

Get the athletes for an account. Inactive players will only be included if includeInactive parameter is set to TRUE.

Usage

get_athletes(includeInactive = FALSE, ...)

Arguments

Value

Response will be a data frame containing the athletes that match this query. Each athlete includes the following variables:

The optional profile columns (image, position, dob, sport, height, lastTestedOn) and any external property columns only appear when at least one athlete in the response has that field populated.

Examples

## Not run: 
# This is an example of how the function would be called. If you only wish to call active players,
# you don't need to provide any parameters.

df_athletes <- get_athletes()

# If you want to include all athletes, including inactive athletes, include the optional
# `includeInactive` parameter.

df_wInactive <- get_athletes( includeInactive = TRUE)


## End(Not run)

Get Center-of-Pressure Data

Description

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

Usage

get_cop(testId, ...)

Arguments

Value

A HawkinCOP object. The data data frame contains the columns time_s, cop_x, cop_y, left_cop_x, left_cop_y, right_cop_x, and right_cop_y. COP values are in millimeters relative to plate center and may be NA for samples where no weight is on a given plate.

Get Force-Time Data

Description

Retrieves the raw force-time data for a specific test trial ID.

Usage

get_forcetime(testId, ...)

Arguments

Value

A HawkinForceTime object.

Get Raw Force-Time Data (Bulk)

Description

Retrieves raw force-time data for multiple tests. This function acts as a wrapper for both get_tests and get_forcetime.

Usage

get_forcetime_bulk(
  test_ids = NULL,
  export = FALSE,
  export_dir = NULL,
  format = c("csv", "json", "rds", "rda", "tsv", "parquet"),
  file_naming = c("test_id"),
  deidentify = FALSE,
  ...
)

Arguments

Value

When export = FALSE (the default), a named list of raw force-time results, one element per requested test. When export = TRUE, a character vector of the file paths written to export_dir, returned invisibly. Returns NULL if no matching tests are found.

Get Groups

Description

Get the group names and ids for all the groups in the org.

Usage

get_groups(...)

Arguments

Value

Response will be a data frame containing the groups that are in the organization. Each group has the following variables:

Examples

## Not run: 
# This is an example of how the function would be called.

df_groups <- get_groups()


## End(Not run)

Get Test Metrics

Description

Get the metrics and ids for all the metrics in the system.

Usage

get_metrics(testType = "all")

Arguments

Value

Response will be a data frame containing the tests metrics that are in the HD system. The parameter testType can be used to filter and return only metrics of the specified type.

The returned data frame will follow the following schema:

Examples

## Not run: 
# This is an example of how the function would be called.

df_testsMetrics <- get_metrics(testType = "CMJ")


## End(Not run)

Get Tags

Description

Get the tag names and ids for all the tags in the system.

Usage

get_tags(...)

Arguments

Value

Response will be a data frame containing the tags that are in the organization. Each tag has the following variables:

Examples

## Not run: 
# Use active connection
df_tags <- get_tags()

# Use a specific profile by name
df_tags_dev <- get_tags(profile = "my_dev_profile")

## End(Not run)

Get Teams

Description

Get the team names and ids for all the teams in the org.

Usage

get_teams(...)

Arguments

Value

Response will be a data frame containing the teams that are in the organization. Each team has the following variables:

Examples

## Not run: 
# This is an example of how the function would be called.

df_teams <- get_teams()


## End(Not run)

Get Test Types

Description

Get the test type names and ids for all the test types in the system.

Usage

get_testTypes()

Value

Response will be a data frame containing the tests that are in the HD system. Each test type includes the following variables:

Examples

## Not run: 
# This is an example of how the function would be called.

df_tests <- get_testTypes()


## End(Not run)

Get All Tests or Sync Tests

Description

Retrieves test data from the Hawkin Dynamics API. This function replaces all previous ⁠get_tests_*⁠ functions. It can filter by athlete, team, group, date range, or sync timestamp.

Usage

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

Arguments

Details

Pagination: This function uses cursor-based pagination (API v1.13+) to reliably fetch all matching tests regardless of dataset size. The API returns pages of up to 1,000 tests each. The function loops automatically until all pages are retrieved.

• If from is provided, it is used as a time-range filter.

• If from is NOT provided, no lower bound is applied and all available history is returned. Pagination handles arbitrarily large result sets.

• If to is NOT provided, no upper bound is applied (results run through the most recent test).

Schema Handling: Because metrics may be added to the system over time, older test results might have fewer columns than newer ones. This function uses dplyr::bind_rows to combine pages, filling missing columns with NA where necessary.

Athlete columns: The athlete block is prefixed with athlete_ and includes the core fields (athlete_id, athlete_name, athlete_active, athlete_teams, athlete_groups), the API v1.14 profile fields when present (athlete_image, athlete_position, athlete_dob, athlete_sport, athlete_height, athlete_lastTestedOn), and one ⁠athlete_<key>⁠ column per external (custom) property. Athletes missing a given external key receive NA.

Value

A data frame containing test trials and their metrics. Each row represents a single test trial. (if specified).

Examples

## Not run: 
# Call for all tests (active connection)
dfAllTests <- get_tests()

# Call for all tests within a specific time frame
dfFromTo <- get_tests(from = "2023-08-01", to = "2023-08-10")

# Include inactive tests
dfAll <- get_tests(from = "2023-08-01", includeInactive = TRUE)

## End(Not run)

Remove Hawkin Credentials

Description

Deletes a stored Refresh Token from the system keychain.

Usage

hd_auth_reset(profile = "default")

Arguments

Value

No return value, called for side effects. Deletes the stored refresh token for profile from the operating system credential store.

Store Hawkin Credentials Securely

Description

Securely saves your Hawkin Dynamics Refresh Token to your operating system's credential store (Keychain on macOS, Credential Manager on Windows).

Usage

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

Arguments

Value

No return value, called for side effects. Stores the refresh token for profile in the operating system credential store.

Note

When using the token parameter directly (e.g., hd_auth_store(token = "...")), be aware that the token string may be recorded in your .Rhistory file. For maximum security, omit the token parameter to use the secure OS prompt instead.

Connect to Hawkin Dynamics API

Description

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

Usage

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

Arguments

Value

Invisibly returns the authenticated HawkinAuth object.

Logger Settings Controller

Description

This function initializes the logger with customization parameters, including the output destination and log thresholds for both stdout and log file.

Usage

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

Arguments

Details

The function sets up the logging configuration with the specified output destination and log thresholds. If "stdout" is chosen, logs will be output to the console. If "file" is chosen, logs will be written to a file named "hawkinRlog.log" by default. The log_file parameter can be used to use a different file name and location. If "both" is chosen, logs will be output to both the console and the log file.

Users can specify different log thresholds for stdout and log file.

Value

No return value, called for side effects. Configures the logger package's layout, threshold, and appender according to the arguments.

Examples

## Not run: 
# Log messages as stdout with a DEBUG threshold
initialize_logger(log_output = "stdout", log_threshold_stdout = "DEBUG")

# Log to file in 'app' directory with a TRACE threshold
initialize_logger(
  log_output = "file", log_file = "app/mylog", log_threshold_file = "TRACE"
)

## End(Not run)

Update Athletes

Description

Update an athlete or athletes for an account. Bulk update up to 500 athletes at a time.

Usage

update_athletes(athleteData, ...)

Arguments

Details

The data frame passed as the argument must use the following schema:

If optional fields are not present in an update request, those properties will be left unchanged. However, when updating external properties, custom properties that are not present will be removed.

Value

If successful, a confirmation message will be printed with the number of successful athletes updated. If there are failures, a data frame containing the athletes that failed to be updated will be returned with columns:

Examples

## Not run: 
# Example data frame following the required schema
df <- data.frame(
  id = c("uniqueAthleteIdOne", "uniqueAthleteIdTwo"),
  name = c("John Doe", "Jane Smith"),
  image = c("https://example.com/johndoe.jpg", "https://example.com/janesmith.jpg"),
  active = c(TRUE, FALSE),
  teams = I(list("team1", c("team2", "team3"))),
  groups = I(list(NULL, "group1")),
  external_property = c("value1", "value2")
)

# Update athletes using the example data frame
update_athletes(athleteData = df)

## End(Not run)