Accessing Force-Time Data (Raw)

There are many cases in which a researcher or coach would want to access the high-frequency raw data (1000Hz) from a test trial. Just like the calculated metrics, you can access the time-series data used to create the force plots in your app and cloud.

In v2.0, hawkinR introduces two robust functions for this workflow:

  1. get_forcetime() : Fetches a single test as a structured S7 object containing both metadata and data.

  2. get_forcetime_bulk(): A powerful wrapper for fetching multiple tests, creating lists of objects, or exporting data directly to file (CSV, JSON, Parquet, RDS).

1. Establishing a Connection

The first step is always to initialize your session.

library(hawkinR)

# Connect using your secure profile
hd_connect(profile = "default")

2. Fetching a Single Test

To pull force-time data, you first need the unique id of the specific trial. You can find these IDs by running a standard query with get_tests().

# Find a specific Countermovement Jump from yesterday
recent_tests <- get_tests(typeId = "CMJ", from = Sys.Date() - 1)
target_id <- recent_tests$id[1]

Once you have the ID, use get_forcetime():

# Fetch the raw data
ft_obj <- get_forcetime(testId = target_id)

The HawkinForceTime Object

Unlike previous versions, this function now returns a structured S7 Class. This ensures that metadata (who, what, when) is always attached to the raw numbers without bloating the data frame.

# 1. Access Metadata properties
print(ft_obj@athlete_name)
#> [1] "John Doe"

print(ft_obj@testType_name)
#> [1] "Countermovement Jump"

# 2. Access the Raw Data Frame (Time, Force, Velocity, etc.)
head(ft_obj@data)
#>   time_s force_left_N force_right_N force_combined_N velocity_m_s
#> 1  0.000          450           460              910         0.00
#> 2  0.001          451           459              910         0.00

Simple Plotting Example

# Plot the force trace using base R
plot(
  x = ft_obj@data$time_s, 
  y = ft_obj@data$force_combined_N, 
  type = "l", 
  col = "blue",
  main = paste("Jump Trace:", ft_obj@athlete_name),
  xlab = "Time (s)", 
  ylab = "Force (N)"
)

3. Bulk Fetching & Exporting

If you need to extract data for an entire team, a specific date range, or a research study, get_forcetime_bulk() is the most efficient tool. It handles looping, progress bars, and error handling automatically.

Workflow A: Fetch to List (In-Memory Analysis)

Use this if you want to analyze multiple trials immediately within R.

# Fetch all Drop Jumps from the last 7 days
# Note: We pass standard get_tests() arguments (from, typeId) directly here!
dj_list <- get_forcetime_bulk(
  typeId = "Drop Jump", 
  from = Sys.Date() - 7
)

# Result is a list of HawkinForceTime objects
length(dj_list)
#> [1] 12

# Access the first jump in the list
first_jump <- dj_list[[1]]

Workflow B: Export to File (Data Lake / Research)

Use this if you are building a database or need to pass files to Python, Excel, or PowerBI.

Key Features:

  • Manifest File: Automatically creates metadata_manifest.csv in the folder to summarize all exported files.

  • File Naming: Fully customizable using object properties (e.g., athlete_name, date).

  • Formats: Supports csv, tsv, json, rds, and parquet (requires arrow package).

# Export all tests for a specific athlete to CSV
get_forcetime_bulk(
  athleteId = "athlete_uuid_here",
  export = TRUE,
  export_dir = "C:/My_Research_Data/Raw_Exports",
  format = "csv",
  
  # Custom Naming: "Last, First_TestType_YYYYMMDD_HHMMSS.csv"
  file_naming = c("athlete_name", "testType_name", "date")
)

Naming with Custom Tags

You can even use nested properties from the athlete’s external tags in your filenames using $ syntax:

get_forcetime_bulk(
  ...,
  file_naming = c("athlete_external$student_id", "testType_name")
)

4. De-identification for Research

If you are publishing data or sharing it with third parties, you can strip PII (Personally Identifiable Information) automatically.

get_forcetime_bulk(
  teamId = "team_uuid_here",
  export = TRUE,
  export_dir = "./study_data",
  deidentify = TRUE  # Replaces athlete_name with "De-identified"
)

Note: The athlete_id (UUID) is preserved so you can still distinguish between subjects, but the human-readable names are removed from both the object and the exported filenames.