The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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:

# 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.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.